How to Share Sass Variables Across Components in Next.js SCSS Projects

Use sassOptions.includePaths in next.config.js to make a shared variables file resolvable from any SCSS file, then import it with @use in both global stylesheets and CSS Modules.

Next.js provides built-in support for Sass/SCSS through its compiler infrastructure, processing styles via Turbopack (or Webpack) during the build phase. To reuse variables across your application, you must explicitly configure the Sass import resolution paths and import the definitions into each file that needs them, as variables are not automatically global across the codebase.

Understanding Next.js SCSS Processing Architecture

Next.js handles two distinct categories of SCSS files during compilation. According to the vercel/next.js source, the bundler processes these differently:

• Global SCSS — Files imported in app/layout.tsx (App Router) or pages/_app.tsx (Pages Router) are bundled into a single global stylesheet emitted for the entire application.
• CSS Modules (*.module.scss) — Files imported directly into components are scoped locally, with class names hashed to prevent collisions.

The compiler walks the import graph of every .scss file at build time. When you configure sassOptions in next.config.js, these options pass directly to the underlying Sass compiler (referenced in the internal loader at packages/next/src/compiler/swc-loader.ts), allowing you to customize import resolution.

Setting Up a Shared Variables File

Create a dedicated partial to house your design tokens. By convention, prefix the filename with an underscore to indicate it is a Sass partial.

/* styles/_variables.scss */
$primary-color: #1e90ff;
$spacing-unit: 1rem;
$font-stack: 'Inter', sans-serif;

This file does not generate CSS output on its own; it only defines variables available for import.

Configuring Sass Import Paths in next.config.js

To avoid relative path hell (../../../../styles/variables), add the styles directory to the Sass include path. This allows you to import the file by name alone from any location in your project.

// next.config.js
const path = require('path');

/** @type {import('next').NextConfig} */
const nextConfig = {
  sassOptions: {
    includePaths: [path.join(__dirname, 'styles')],
  },
};

module.exports = nextConfig;

For more complex aliasing requirements, the repository demonstrates advanced configuration in examples/cms-sitecore-xmcloud/src/lib/next-config/plugins/sass.js, where a custom importer creates a @sass alias pointing to a shared folder:

// Advanced: Using sass-alias plugin (from cms-sitecore-xmcloud example)
const SassAlias = require('sass-alias');

module.exports = {
  sassOptions: {
    importer: new SassAlias({
      '@sass': path.join(__dirname, 'src', 'styles')
    }).getImporter()
  }
};

Importing Variables in Global Stylesheets

Import the variables file into your global stylesheet to apply design tokens to the entire application. The examples/with-sass/styles/globals.scss file in the repository demonstrates this pattern.

/* styles/globals.scss */
@use 'variables' as *;

body {
  background-color: $primary-color;
  font-family: $font-stack;
  padding: $spacing-unit;
}

Import this global file once in your root layout:

// app/layout.tsx
import '@/styles/globals.scss';

export default function RootLayout({ 
  children 
}: { 
  children: React.ReactNode 
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

For the Pages Router, place the import in pages/_app.tsx instead.

Using Variables in Component CSS Modules

Component-scoped styles can access the same variables by importing the partial. This works because the includePaths configuration resolves the import regardless of the component's location.

/* components/Button.module.scss */
@use 'variables' as *;

.button {
  background-color: $primary-color;
  padding: $spacing-unit;
  font-family: $font-stack;
  
  &:hover {
    filter: brightness(1.1);
  }
}

Reference the classes in your component:

// components/Button.tsx
import styles from './Button.module.scss';

export default function Button({ children }: { children: React.ReactNode }) {
  return <button className={styles.button}>{children}</button>;
}

The examples/with-sass/components/hello-world.module.scss file provides a working example of component-level SCSS modules in the repository.

Summary

• Sass variables are file-scoped by default and must be imported into every file that uses them.
• Configure sassOptions.includePaths in next.config.js to make your variables directory resolvable from anywhere in the project.
• Use @use 'variables' as * to import variables without namespace prefixes in both global SCSS and CSS Modules.
• Import global styles once in app/layout.tsx (App Router) or pages/_app.tsx (Pages Router).
• Reference specific files: examples/with-sass/styles/globals.scss for global patterns and examples/cms-sitecore-xmcloud/src/lib/next-config/plugins/sass.js for advanced alias configuration.

Frequently Asked Questions

Why are my Sass variables undefined in component modules?

Variables are scoped to the file that defines them unless explicitly imported. You must add @use 'variables' as *; at the top of every .scss file that references the variables, and ensure sassOptions.includePaths includes the directory containing your _variables.scss file.

Should I use @import or @use for sharing variables in Next.js?

Use @use. The Sass team deprecated @import in favor of the module system (@use and @forward). Next.js supports both, but @use provides better encapsulation and clearer dependency graphs, which helps Turbopack and Webpack optimize your build.

Can I share mixins and functions the same way as variables?

Yes. Any Sass members—variables, mixins, or functions—defined in a partial can be shared using the same @use import mechanism. Place them in your _variables.scss file (or a separate _mixins.scss file) and import them where needed.

Does importing variables into every component duplicate the CSS output?

No. Sass variables compile away during the build process; they do not generate CSS rules unless used to define actual properties. The compiled output contains only the resolved CSS values, not the variable definitions themselves, so there is no runtime overhead or CSS bloat.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}