Clean Vue 3 Code with Global SCSS Variables in Vite: A Step-by-Step Guide to Organizing Your Project Structure

In this tutorial, we will go through the steps to set up global SCSS variables for a Vue 3 project using Vite. We will create a SCSS variables file, a global SCSS file, and configure our Vite configuration file to use the variables globally.

Prerequisites

Before we begin, you need to have a few things set up:

• Node.js and npm installed on your computer
• A basic understanding of Vue.js and SCSS

Step 1: Create a new Vue 3 project

First, we need to create a new Vue 3 project. You can do this using the npm init vue@latest command in your terminal. Select the option that suits your project and follow the prompts.

npm init vue@latest

Run the following command to install sass as a dev dependency:

npm install -D sass

Step 2: Create a SCSS variables file

Next, create a SCSS variables file in the src/assets/scss folder. We'll name ours _variables.scss and define color variables in it.
Note that we preceeded the file name with a _ to indicate to Sass that it’s a partial file that should not be compiled into a standalone CSS file.

$color-primary: #0074d9;
$color-secondary: #7fdbff;
$color-tertiary: #39cccc;

Step 3: Create a global SCSS file

Now, we’ll create a global SCSS file in the same src/assets/scss folder, where we can @import or @forward the _variables.scss file. We'll name ours global.scss.
Updated based on the feedback from Alexandru Adrian Lucaci.
This file should primarily include your SCSS variables, mixins, and functions.

By structuring it this way, we’re ensuring that we don’t introduce any duplicate style declarations in our final CSS output. Instead, we’re making our SCSS helpers globally available, so they can be utilized within the individual components.

// src/assets/scss/global.scss

@forward "variables";

Step 4: Configure the Vite configuration file

Next, we’ll set up the css.preprocessorOptions option in our Vite configuration file to use the global SCSS file we just created. You'll typically find the vite.config.js file in the root of your project. Your configuration should look something like this:

import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
    plugins: [vue()],
    resolve: {
        alias: {
            "@": fileURLToPath(new URL("./src", import.meta.url)),
        },
    },
    css: {
        preprocessorOptions: {
            scss: {
                additionalData: `@import "@/assets/scss/global.scss";`,
            },
        },
    },
});

The additionalData option in the scss object tells Vite to include the global.scss file in every SCSS file that it compiles.

Conclusion

That’s it! You’ve successfully set up global SCSS variables for your Vue 3 project using Vite. You can now use the variables defined in _variables.scss globally in your project. Same can be done for mixins and functions.

Remember that by limiting the content of your global.scss file to only SCSS variables, mixins, and functions, you ensure efficiency and avoid the pitfall of duplicated styles in the compiled CSS.

Extras

Just in case you have no idea of how to use the global scss variables declared, here is what it looks like and how you could call a variable within your vue components or pages

//HOME.vue

<template>
  <h1>Learn Easy Code</h1>
</template>

<style lang="scss">
  h1 {
    color: $color-primary;
  }
</style>