# Working with CSS

Vue CLI projects comes with support for PostCSS, CSS Modules and pre-processors including Sass, Less and Stylus.

# Referencing Assets

All compiled CSS are processed by css-loader, which parses url() and resolves them as module requests. This means you can refer to assets using relative paths based on the local file structure. Note if you want to reference a file inside an npm dependency or via webpack alias, the path must be prefixed with ~ to avoid ambiguity. See Static Asset Handling for more details.

# Pre-Processors

You can select pre-processors (Sass/Less/Stylus) when creating the project. If you did not do so, the internal webpack config is still pre-configured to handle all of them. You just need to manually install the corresponding webpack loaders:

# Sass
npm install -D sass-loader sass

# Less
npm install -D less-loader less

# Stylus
npm install -D stylus-loader stylus

Then you can import the corresponding file types, or use them in *.vue files with:

<style lang="scss">
$color: red;
</style>

npm install -D fibers

# Automatic imports

If you want to automatically import files (for colors, variables, mixins...), you can use the style-resources-loader. Here is an example for stylus that imports ./src/styles/imports.styl in every SFC and every stylus files:

// vue.config.js
const path = require('path')

module.exports = {
  chainWebpack: config => {
    const types = ['vue-modules', 'vue', 'normal-modules', 'normal']
    types.forEach(type => addStyleResource(config.module.rule('stylus').oneOf(type)))
  },
}

function addStyleResource (rule) {
  rule.use('style-resource')
    .loader('style-resources-loader')
    .options({
      patterns: [
        path.resolve(__dirname, './src/styles/imports.styl'),
      ],
    })
}

You can also use the vue-cli-plugin-style-resources-loader.

# PostCSS

Vue CLI uses PostCSS internally.

You can configure PostCSS via .postcssrc or any config source supported by postcss-load-config, and configure postcss-loader via css.loaderOptions.postcss in vue.config.js.

The autoprefixer plugin is enabled by default. To configure the browser targets, use the browserslist field in package.json.

# CSS Modules

You can use CSS Modules in *.vue files out of the box with <style module>.

To import CSS or other pre-processor files as CSS Modules in JavaScript, the filename should end with .module.(css|less|sass|scss|styl):

import styles from './foo.module.css'
// works for all supported pre-processors as well
import sassStyles from './foo.module.scss'

If you want to drop the .module in the filenames, set css.modules to true in vue.config.js:

// vue.config.js
module.exports = {
  css: {
    modules: true
  }
}

If you wish to customize the generated CSS modules class names, you can do so via css.loaderOptions.css in vue.config.js. All css-loader options are supported here, for example localIdentName and camelCase:

// vue.config.js
module.exports = {
  css: {
    loaderOptions: {
      css: {
        localIdentName: '[name]-[hash]',
        camelCase: 'only'
      }
    }
  }
}

# Passing Options to Pre-Processor Loaders

Sometimes you may want to pass options to the pre-processor's webpack loader. You can do that using the css.loaderOptions option in vue.config.js. For example, to pass some shared global variables to all your Sass/Less styles:

// vue.config.js
module.exports = {
  css: {
    loaderOptions: {
      // pass options to sass-loader
      // @/ is an alias to src/
      // so this assumes you have a file named `src/variables.sass`
      // Note: this option is named as "data" in sass-loader v7
      sass: {
        prependData: `@import "~@/variables.sass"`
      },
      // by default the `sass` option will apply to both syntaxes
      // because `scss` syntax is also processed by sass-loader underlyingly
      // but when configuring the `data` option
      // `scss` syntax requires an semicolon at the end of a statement, while `sass` syntax requires none
      // in that case, we can target the `scss` syntax separately using the `scss` option
      scss: {
        prependData: `@import "~@/variables.scss";`
      },
      // pass Less.js Options to less-loader
      less:{
        // http://lesscss.org/usage/#less-options-strict-units `Global Variables`
        // `primary` is global variables fields name
        globalVars: {
          primary: '#fff'
        }
      }
    }
  }
}

Loaders which can be configured via loaderOptions include:

• css-loader
• postcss-loader
• sass-loader
• less-loader
• stylus-loader