How to Fix: Update default sass js api or add the ability to choose through sassOptions

Next.js can still invoke the legacy Sass JavaScript API, which becomes a real problem once your project, dependencies, or CI pipeline expect the modern Dart Sass API. The result is usually noisy deprecation warnings today and potential breakage later, especially when you need explicit control through sassOptions but the framework does not expose the API selector cleanly.

Understanding the Root Cause

This issue exists because Next.js integrates Sass internally and historically relied on behavior compatible with the legacy Sass JS API. While application developers can pass some configuration through sassOptions in next.config.js, not every internal Sass runtime choice is necessarily exposed.

That becomes a mismatch when the Sass ecosystem moves forward. Dart Sass has been steering users toward its modern JavaScript API, while older integration layers may still call deprecated entry points such as legacy render or renderSync-style flows. If Next.js keeps that default internally, you may see:

• Deprecation warnings during development or builds
• Inconsistent behavior between local and CI environments
• Trouble configuring custom importers or advanced Sass behavior
• Difficulty future-proofing your styling pipeline

In short, the root problem is not your SCSS syntax. It is an integration-level API default: Next.js chooses how Sass is invoked, and developers want either a newer default or an explicit switch inside sassOptions.

Step-by-Step Solution

If you are working around this issue today, the most reliable path is to make sure your project uses Dart Sass, keep your configuration minimal, and avoid assumptions that Next.js will honor unsupported Sass API flags unless the framework explicitly documents them.

1. Install the supported Sass implementation

Make sure you are using the sass package, not deprecated Node Sass tooling.

npm install sass

or

yarn add sass

or

pnpm add sass

2. Configure Next.js Sass options correctly

Start with a clean next.config.js:

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

module.exports = nextConfig

This does not force the modern API by itself, but it ensures your project is using the officially supported Sass package and avoids introducing unrelated config errors.

3. Avoid unsupported API flags unless your Next.js version documents them

You may be tempted to try something like this:

/** @type {import('next').NextConfig} */
const nextConfig = {
  sassOptions: {
    api: 'modern',
  },
}

module.exports = nextConfig

This only works if the installed Next.js version actually forwards that option to the underlying Sass runtime. The core issue in the GitHub thread is that developers need Next.js either to update its default internally or to expose this choice safely through configuration.

4. Upgrade Next.js and Sass before testing behavior

Before concluding that the issue is unresolved in your setup, update both packages:

npm install next@latest sass@latest

Then restart the dev server:

npm run dev

After that, run a production build to confirm whether warnings persist:

npm run build

5. Verify whether the warning comes from your app or the framework layer

If the deprecation warning still appears, inspect the stack trace carefully. If your own code never calls the old Sass API directly, the warning likely originates from:

• Next.js internals
• A loader in the build chain
• A third-party package that compiles Sass independently

This distinction matters because changing application-level SCSS files will not fix a framework-level invocation path.

Practical Workarounds for Current Next.js Versions

Until Next.js changes the default Sass API or fully supports selecting it via sassOptions, these are the safest workarounds.

Use the latest stable toolchain

Many Sass integration issues are version-sensitive. Keep next, react, and sass aligned with current stable releases.

npm outdated
npm install next@latest react@latest react-dom@latest sass@latest

Reduce custom Sass complexity

If you are using advanced importers, unusual path aliases, or build-time Sass hooks, simplify temporarily. That helps confirm whether the problem is specifically the legacy API default or a custom extension point.

Patch only if your organization accepts maintenance overhead

Some teams use tools like local dependency patching to adjust framework internals until an upstream fix lands. This is possible, but it is usually a last resort because every Next.js upgrade can invalidate the patch.

If you go that route, document:

• The exact Next.js version patched
• The internal Sass call site modified
• How to reapply or remove the patch after upgrades

Track the upstream discussion

Since this is a framework behavior issue, the long-term fix belongs upstream. Follow the related GitHub discussion through this Next.js thread and watch release notes for Sass integration changes.

Common Edge Cases

1. The warning persists even after installing latest Sass

That usually means the warning is triggered by how Sass is called, not by which package version you installed. If Next.js or a loader still uses the old API, upgrading sass alone will not eliminate the message.

2. A dependency triggers its own Sass compilation

Some packages compile styles independently of Next.js. In that case, you may be dealing with multiple Sass invocation paths in the same build. Search your lockfile and build logs for additional tooling such as custom webpack loaders or style processors.

3. Monorepo resolution issues

In monorepos, the app may resolve one version of sass while another package resolves a different one. That can make the warning appear inconsistent across apps or pipelines. Use your package manager’s dependency inspection tools to confirm a single expected version.

npm ls sass

or

pnpm why sass

4. CI behaves differently from local development

This often happens when the lockfile is stale, the Node version differs, or dependency hoisting changes package resolution. Make sure local and CI environments use the same:

• Node.js version
• Lockfile
• Package manager version
• Next.js and Sass versions

5. Trying undocumented sassOptions keys has no effect

That is expected if Next.js does not pass those keys through. The presence of a sassOptions object does not guarantee every Sass runtime option is wired into the framework implementation.

FAQ

Can I fix this just by changing my SCSS files?

No. If the warning comes from the legacy Sass JS API invocation, the problem is in the build integration layer, not in normal SCSS syntax.

Does setting sassOptions.api = 'modern' always work in Next.js?

No. It only works if your installed Next.js version actually forwards that option to Sass. The issue specifically requests that Next.js either change the default or allow developers to choose it explicitly.

What is the safest production recommendation right now?

Use the latest next and sass versions, keep your Sass config minimal, verify whether the warning is framework-originated, and monitor the upstream Next.js discussion for an official fix.

The key takeaway is simple: this bug is about framework control over the Sass execution API. Until Next.js updates that default or exposes a supported selector through sassOptions, project-level fixes can reduce noise but may not fully eliminate the underlying deprecation path.