Skip to content

How to Use SCSS With CSS Modules in Next.js

Next.js/

In this tutorial you are going to:

  • Add global SCSS styles
  • Use SCSS in CSS modules
  • Create Webpack aliases to shorten import paths

Prerequisites

You should already have a working Next.js project. If you need to set up one, here’s the command to get started.

npx create-next-app@latest

Step 1 — Installing Sass

Although Next.js has great built-in CSS support, it doesn’t work with Sass out of the box.

You need to install sass package and Next.js will take care of the rest.

npm install --save-dev sass

If your project is already running from npm run dev, you might need to restart it.

Now you should be ready to start styling with Sass.

Step 2 — Setting up Global Styles

Let’s make a stylesheet that you can use to apply global styles to your entire project.

Create a file global.scss in src/styles and add your site-wide styles.

// src/styles/global.scss

* {
  box-sizing: border-box;
}

body {
  color: #303335;
}

Now, open pages/_app.js and import the global.scss stylesheet there.

// src/pages/_app.js

import '../src/styles/global.scss';

If you don’t have a custom _app.js file, you can create one yourself. Here’s the default template that should do the trick.

import '../src/styles/global.scss';

function MyApp({ Component, pageProps }) {
  return <Component {...pageProps} />;
}

export default MyApp;

You can read more about customizing this file in Next.js documentation.

Step 3 — Using CSS Modules

You can simply write SCSS in your CSS modules and Next.js will do its magic to make it work.

Something useful you can do is creating a file to define all your SCSS variables.

// src/styles/_var.scss

$color-blue: #105cc0;

You can then import that file in other SCSS files, including CSS modules.

// src/components/Hello.module.scss
@import '../styles/var';

.helloText {
  color: $color-blue;
  font-weight: 700;
}

Make sure to use camel case when naming your classes. Use helloText and not hello-text.

To use CSS module styles in components, you have to reference the class name as an object property. And JavaScript doesn’t like dashes (-) in property names.

// src/component/Hello.jsx

import styles from './Hello.module.scss';

const Hello = ({ message }) => {
  return <p className={styles.helloText}>Hello, {message}</p>;
};

export default Hello;

(Optional) Step 4 — Setting up Import Aliases

When importing styles from other files in Sass, you can avoid typing long relative import paths with aliases.

// src/components/deeply/nested/Component.module.scss

// Regular import
@import '../../../styles/var';

// Using an alias
@import '@styles/var';

To achieve this, you need to configure webpack to resolve @styles as an actual path.

Open next.config.js and add the following config.

const path = require('node:path');

const nextConfig = {
  webpack(config) {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@styles': path.resolve(__dirname, 'src/styles'),
    };

    return config;
  },
};

module.exports = nextConfig;

Here you use the webpack function to extend the default Next.js usage of webpack.

Since you are overriding the default config.resolve.alias, you need to spread the original aliases first. Next.js relies on some aliases internally, so you need to preserve them.

After that is done, you can go ahead and add your own aliases.

You can now use SCSS inside CSS Modules with import aliases in your Next.js project.