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

> Learn how to share Sass variables in Next.js SCSS projects. Configure next config js to import Sass variables globally across components for seamless styling.

- Repository: [Vercel/next.js](https://github.com/vercel/next.js)
- Tags: how-to-guide
- Published: 2026-02-20

---

**Use `sassOptions.includePaths` in [`next.config.js`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/app/layout.tsx) (App Router) or [`pages/_app.tsx`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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.

```scss
/* 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.

```javascript
// 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`](https://github.com/vercel/next.js/blob/main/examples/cms-sitecore-xmcloud/src/lib/next-config/plugins/sass.js), where a custom importer creates a `@sass` alias pointing to a shared folder:

```javascript
// 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`](https://github.com/vercel/next.js/blob/main/examples/with-sass/styles/globals.scss) file in the repository demonstrates this pattern.

```scss
/* 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:

```tsx
// 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`](https://github.com/vercel/next.js/blob/main/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.

```scss
/* 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:

```tsx
// 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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/app/layout.tsx) (App Router) or [`pages/_app.tsx`](https://github.com/vercel/next.js/blob/main/pages/_app.tsx) (Pages Router).
- **Reference specific files**: [`examples/with-sass/styles/globals.scss`](https://github.com/vercel/next.js/blob/main/examples/with-sass/styles/globals.scss) for global patterns and [`examples/cms-sitecore-xmcloud/src/lib/next-config/plugins/sass.js`](https://github.com/vercel/next.js/blob/main/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`](https://github.com/vercel/next.js/blob/main/_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`](https://github.com/vercel/next.js/blob/main/_variables.scss) file (or a separate [`_mixins.scss`](https://github.com/vercel/next.js/blob/main/_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.