Setup your project #

Starting with the quickstarter #

Start by creating a new folder (e.g. my-vulk-quickstarter-project) and extract the quickstarter-vulk-v1.3.0.zip archive content into it.

# Create a new folder
mkdir my-vulk-quickstarter-project

# Extract the quickstarter archive (replace v1.1.0 with the actual version number)
unzip quickstarter-vulk-v1.1.0.zip -d my-vulk-quickstarter-project

# Go to the newly created folder
cd my-vulk-quickstarter-project

Project overview #

my-vulk-quickstarter-project/
├── public/                  # static files (robots.txt, favicon.ico, etc.)
├── src/
│   ├── components/          # global components
│   ├── composable/          # reusable composition functions 
│   ├── data/                # Demo data to inject into components
│   ├── directives/          # global vuejs directives
│   ├── documentation/       # Component library demo components
│   ├── layouts/             # layout components
│   ├── locales/             # global i18n locales
│   ├── pages/               # pages components, each file is accessible as a route
│   ├── plugins/             # plugin imports to be loaded in the app
│   ├── scss/                # scss files
│   ├── stores/              # pinia stores
│   ├── utils/               # utility functions
│   ├── types/               # global typescript interfaces
│   ├── app.ts               # vulk initialization (head, router, pinia, etc.)
│   ├── entry-client.ts      # client entry point 
│   ├── entry-server.ts      # server entry point 
│   ├── router.ts            # base vue-router configuration
│   ├── styles.ts            # stylesheet configuration (scss, vendor, etc.)
│   └── VulkApp.vue          # vulk root component
├── .env                     # environment variables available to the project
├── index.html               # main entry point (loads src/entry-client.ts)
├── package.json             # project dependencies
├── tsconfig.json            # typescript configuration
├── bulma-css-vars.config.js # Bulma css vars configuration
└── vite.config.ts           # vite plugins and configuration

This is an overview of the most important files and folders in your project. Other files are for linters, testing, docker, etc.

Dependencies installation #

Install the project dependencies by running one of the following commands:

pnpm install

Setup your IDE #

VSCode and Volar #

The recommended IDE setup is VSCode with the Volar extension. Volar provides syntax highlighting and advanced IntelliSense for template expressions, component props and even slots validation. We strongly recommend this setup if you want to get the best possible experience with Vue SFCs.

Vue.js devtools #

If you are on a Chromium based browser, we recommend that you to install the Vue.js devtools extension from any webstore: https://devtools.vuejs.org/guide/installation.html

Start in development mode #

To start the development server, run the following command:

pnpm dev

This will run the dev script from the package.json file.

• The dev script starts the frontend (vite) server. Vite is the build tool that we use to compile the frontend code. It replaces webpack and vue-cli, used in the vue 2 ecosystem.
  Read more about it on vitejs.dev

Building for production #

Once you have the project ready, you can build it for production by running one of the following commands:

pnpm build

This will run both the build:update-bulma-colors and build:vite scripts from the package.json file.

• The build:update-bulma-colors script will patch Bulma to allow using css variables. Read more on the Customizing Vulk - Hybrid Sass section.

• The build:vite script will generate the static production files (in the ./dist folder).

Preview the production build #

Once the production files are generated, you can preview them by running one of the following commands:

pnpm serve

This will run the serve script from the package.json file.

The serve script will create a simple http server within dist folder, with a fallback to index.html when no file is found. This lets vue router handle the routing.
Read more about serve: https://github.com/vercel/serve

Extending the quickstarter #

Quickstarter pages anatomy #

The quickstarter come with a few pages that you can use to start your project.

• A landing page that you can use to introduce your project, everyone can access it.
• An authentication section with login/signup forms.
• A private page that need to be logged in to access.
• And a 404 page when no matching component is found for the requested route.

Here is the overview of the pages:

my-vulk-quickstarter-project/
├── src/
│   ├── layouts/
│   │   └── default.vue
│   ├── pages/
│   │   ├── auth/           # auth nested routes
│   │   │   ├── index.vue   # the auth page accessible at `/auth/`
│   │   │   ├── login.vue   # the auth-login page accessible at `/auth/login`
│   │   │   └── signup.vue  # the auth-signup page accessible at `/auth/signup`
│   │   ├── [...all].vue    # the catch all page (404)
│   │   ├── index.vue       # the index page accessible at `/`
│   │   └── auth.vue        # optional auth nested routes wrapper, should contain a `<RouterView />`

The route are automaticaly generated from the pages/ folder, this is done with the vite-plugin-pages plugin. You can read more about this plugin on it github page here: https://github.com/hannoeru/vite-plugin-pages

As you can see, some pages are not directly accessible, but are wrapper for nested routes. This will allow us to setup layout for an entire section of our app. You can read more about how they work on the official vue-router documentation here: https://next.router.vuejs.org/guide/essentials/nested-routes.html

Creating new pages #

Let's imagine we want to create a new page in our website. We want our new page to be accessible at http://localhost:3000/my-page/.

We have to create a new file:

 my-vulk-quickstarter-project/
 ├── src/
 │   ├── pages/
+│   │   └── my-page.vue           # our new page

Create the src/pages/my-page.vue file.

<script setup lang="ts">
import { useHead } from '@vueuse/head'

// don't forget to setup our page meta
useHead({
  title: 'My page',
})
</script>

<template>
  <div class="my-custom-page-wrapper">
    <!--One of the available hero header components -->
    <HeroA />
  </div>
</template>

<style lang="scss" scoped>
.my-custom-page-wrapper {
  // Here we can add custom styles for the page
  // They will be scoped to this component
}
</style>

Using components from the full template #

Using a layout from the full template #

Layouts are special components that wrap your pages. They are used to control your page or group of similar pages default settings.

You can have as many layouts as you want in your project. The quickstarter comes with a default and auth layout. You can add any from the full project as well. Here are the available layouts:

• Minimal: no navigation
• Default Nav: Megamenu nav
• Inverted Nav: Megamenu nav inverted
• Nav A: Navbar A
• Nav A inverted: Navbar A inverted
• Nav B: Navbar B
• Nav B inverted: Navbar B inverted
• Nav C: Navbar C
• Nav C inverted: Navbar C inverted
• Nav D: Navbar D
• Nav D inverted: Navbar D inverted
• Nav E: Navbar E
• Nav E inverted: Navbar E inverted
• Nav F: Navbar F
• Nav F inverted: Navbar F inverted
• Nav G: Navbar G
• Nav G inverted: Navbar G inverted
• Nav H: Navbar H
• Nav H inverted: Navbar H inverted

Copy the layout into your src/layouts project directory. Notice that in the quickstarter, only default, inverted-nav and minimal are available. They can be used for any of your pages.

You can copy anyone of these layouts in your src/layouts directory and start using it.

Defining a layout for a page #

When you create a page, it will use the default layout if you don't specify not to do so. To use another layout, add some route yaml meta instructions at the top of your page:

<route lang="yaml">
meta:
  layout: inverted-nav
</route>

in the layout parameter, put the name of the layout file you want to use for your page removing the .vue extension. That's as easy as that, your page now uses the layout you specified.