Working with CSS in Nuxt.js

The first part of a series of articles about working with CSS in Nuxt.js, showing different ways of adding CSS to a Nuxt.js project.

Main topics in this article are preprocessors, autoprefixing, CSS Source Maps , global styles and how to add a separate CSS file to the document head.

There are a lot of similarities with how CSS works in Vue.js (read the article series “Working with CSS in Vue.js”), however since the Nuxt.js project is set up slightly differently, there are also some differences.

Start Setup

Note that both setup, plugins and framework are evolving. Changes will in time most certainly happen that make the techniques described in this post less relevant.

I’ve used create-nuxt-app version 2.10.0 to set up the project. When setting up the project, I chose NPM as package manager and jsconfig.json as development tool (only choice available and recommended for VS Code).

Production Output

Unlike the default production setting in a Vue.js project, styles are not automatically output as a CSS file. The CSS output depends on the chosen setup.

Adding SASS/SCSS to a Nuxt.js project

Adding SASS/SCSS to a Nuxt.js project works just like for a Vue.js project. Install sass-loader and node-sass in your project:
npm install --save-dev sass-loader
npm install --save-dev node-sass

To read more about working with CSS in Vue.js projects, see the articles series starting with “Working with CSS in Vue.js”.

Autoprefixing

Autoprefixing is included in Nuxt.js and is handled by autoprefixer, which in turn relies on Browserslist.

To control which browser versions are included, you could create a separate browserslistrc config file, or add a setting in the package.js file. Place the setting after devdependecies:

"browserslist": "cover 99.5%" //or whatever settings you prefer

Prefixes are added to the CSS during development as well as for production.

CSS Source Maps

CSS source maps seem to be supported out of the box with the create-nuxt-app package. To also have CSS source maps in production, add the setting cssSourceMap: true to the nuxt.config file:

  /* Build configuration */
  build: {
    /* You can extend webpack config here */
   cssSourceMap: true,
  }

Note that for some reason, the source maps did not seem to work for me when testing in Mozilla Firefox. This closed bug thread suggests that extending the webpack configuration manually might do the trick. However note that the syntax of the suggested configuration differs from what is suggested in the nuxt documentation.

Global Styles

Global styles in the form of .css or .scss files can be added via the nuxt.config file.

  /* Global CSS */
  css: [
    '~assets/styles/global.css',
    '~assets/styles/globalscss.scss'
  ],

In that way, it is possible to set up an SCSS or CSS workflow that is completely outside of the style tags in .vue files or components, similarly to working without a framework.

Note that the variables declared in these files are not available in the .vue file style section. Classes declared in the global files are available to use in the template parts of .vue files, and can be overwritten in the .vue style section.

Output Separate CSS File

This corresponds to the setting css: {extract: true} in a vue.config.js file for a Vue.js project.

For a Nuxt.js project, add the line extractCSS: true to the nuxt.config.js file:

  /* Build configuration */
  build: {
    /* You can extend webpack config here */
    extractCSS: true,
  }

Note that this will also take scoped styles and place them in .css files to be linked in the document head. The .css files are not concatenated; each one is added separately for every scoped section.

To get all of the styles into one single .css file (and save some requests), use the Nuxt.js optimization setting splitChunks. splitChunks is a part of webpack, so the splitChunks webpack documentation is more detailed.

Adding External CSS to Document Head

Sometimes you want to add external CSS, like for example Google Fonts to your project. In Nuxt.js projects, you’ll find settings for this in the nuxt.config.js file. Add the link to your file in the link array in the head object:

  /* Headers of the page */
  head: {
    /* ...other things that will be output to the head element */
    link: [
      /* add your header links here, for example to favicon and Google Fonts*/
      { rel: 'icon', type: 'image/x-icon', href: '/favicon.ico' },
      { rel: 'stylesheet', href: 'https://fonts.googleapis.com/css?family=Yrsa&display=swap'}
    ]
  },