Setup your project

Starting with the quickstarter

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

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

# Extract the quickstarter archive
unzip quickstarter-vulk-vv2.1.1.zip -d my-vulk-quickstarter-project

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

Initialize a git repository

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

# Create a new folder
git init

# Add all files to git
git add .

# Create your first commit
git commit -m "Initial commit"

WARNING

Remember to make your repository private if you fork or create a new git repository, as the template is a paid product.

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.)
│   ├── app.config.ts        # app configuration (title, description, etc.)
│   └── VulkApp.vue          # vulk root component
├── .env                     # environment variables available to the project
├── index.html               # main entry point (loads src/entry-client.ts)
├── build-ssg.config.ts      # server side generation configuration
├── 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

First of all, you have to install the dependencies, run the following command:

pnpm install

---

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

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:

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

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:

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:

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 automatically 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://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">
// don't forget to setup our page meta
useHead({
  title: 'My page',
})
</script>

<template>
  <div class="my-custom-page-wrapper">
    <!-- Your page content -->
  </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 pre-built content in the src/pages/ to see how you can arrange elements to create awesome websites!

Configuring your project

You can configure your project by editing the src/app.config.ts in order to customize the project title, description, SEO image, darkmode and your default layout.

import type { VulkConfig } from '/@src/types'

/**
 * Set your default Navbar by importing a vue component
 * Note: If you rename the import, make sure to update the type definition bellow
 *
 * @example import Navbar from '/@src/components/blocks/navbar-blocks/NavbarA.vue'
 */
import Navbar from '/@src/components/navigation/navbar/Navbar.vue'

/**
 * Set your default Footer by importing a vue component
 * Note: If you rename the import, make sure to update the type definition bellow
 *
 * @example import Footer from '/@src/components/blocks/footer-blocks/FooterA.vue'
 */
import Footer from '/@src/components/layout/footer/Footer.vue'

// Auto detect the type of the imported components
type NavbarType = typeof Navbar
type FooterType = typeof Footer
type AppConfig = VulkConfig<NavbarType, FooterType>

/**
 * This is the main configuration file for the app
 */
export default {
  name: 'My App',
  title: 'My App Default Title',
  description: 'My App Default Description',
  // The base url of the website, optional
  url: 'https://example.com/',
  // The default seo image, optional
  image: 'https://example.com/assets/images/seo-image.png',
  // Darkmode settings
  theme: {
    // Auto detect system color scheme, can be 'system', 'dark' or 'light'
    default: 'system',
    // Display the theme switcher, set to false to disable darkmode toggle
    toggle: true,
    // Disable transitions to avoid transition flickering when switching theme
    disableTransitions: true,
  },
  // global logo settings
  logo: {
    src: '/assets/logo/logo.svg',
    // The dark logo will be used when darkmode is enabled, optional
    srcDark: '/assets/logo/logo-dark.svg',
    width: 45,
    height: 45,
  },
  layout: {
    // name of the page transition
    transition: 'fade-fast',
    backToTop: {
      // Display the back to top button
      enabled: true,
    },
    navbar: {
      enabled: true,
      // Here you can set the component used for the navbar
      component: Navbar,
      props: {
        // define default props for Navbar here, you can override them using page meta
        // the props are passed to the component using v-bind="props"
      },
    },
    footer: {
      enabled: true,
      // Here you can set the component used for the footer
      component: Footer,
      props: {
        // define default props for Footer here, you can override them using page meta
        // the props are passed to the component using v-bind="props"
      },
    },
  },
} as AppConfig

To help you choose navbar or footers, you can take a look at the components available here:

• https://vulk.cssninja.io/blocks/navbar
• https://vulk.cssninja.io/blocks/footer

WARNING

Retrieving components from the full template should be made carefully, 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.

Overriding a layout for a page

When you create a page, you will be able to customize the layout via pages meta that you can set using yaml in top of your page like:

<route lang="yaml">
meta:
  navbar:
    enabled: false
  footer:
    enabled: false
  backToTop:
    enabled: false
</route>

<template>
  <div>
    <!-- Use a custom navbar -->
    <NavbarA fixed />

    <!-- Your page content-->
    
    <!-- Use a custom footer -->
    <FooterD
      text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Negare non possum. Apparet statim, quae sint officia, quae actiones."
      color="light"
      :social-links="[
        {
          name: 'Facebook',
          url: 'https://facebook.com',
          icon: 'fa:facebook',
        },
        {
          name: 'Twitter',
          url: 'https://twitter.com',
          icon: 'fa:twitter',
        }
      ]"
    />
  </div>
</template>

Setup your IDE

VS Code and Vue Language Tools

The recommended IDE setup is VS Code with the Vue Language Tools (ex Volar) extension. Vue Language Tools 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 Vue Language Tools extension:

1. Open the project folder in VS Code and follow this guide to enable Take Over Mode: https://github.com/vuejs/language-tools/discussions/471#discussioncomment-1361669

2. Run the VS Code 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