Skip to content
On this page

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.

bash
# 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

TIP

We recommend to initialize a new git repository for your project and create your first commit at this point.

Project overview

sh
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:

bash
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.

TIP

Once you have enabled the Volar extension:

  1. Open the project folder in VSCode and follow this guide to enable Take Over Mode: https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669

  2. Run the VSCode command Volar: Select TypeScript Version... then choose Use Workspace Version

These steps should be made on each new project Vue 3 you create.

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:

bash
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

TIP

  • Access the Vulk frontend in your browser at http://localhost:3000/

WARNING

If you have any trouble while installing, check the Common issues or contact us on our Support portal

Building for production

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

bash
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).

TIP

You may want to explore the vite.config.ts file to customize the build

Preview the production build

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

bash
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

TIP

  • Access the Vulk frontend in your browser at http://localhost:3000/

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:

sh
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:

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

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

vue
<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>

TIP

To start customizing your pages, you can check prebuilt content in the src/pages/ to see how you can arrange elements to create awesome websites!

Using components from the full template

WARNING

Retreiving components from the full template should be made carrefully, as it can contain <RouterLink> to pages or other components that do not exist yet in your project. Make sure you copy everything a component needs in your project before inserting somewhere.

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:

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.

WARNING

You will have to replace all <RouterLink> parameters. A good way to do so is to replace all names to index and routes to /

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:

vue
<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.

All Rights Reserved