All jobs

Migrate from node-sass to Dart Sass in a Webpack Project

Yes. An agent swaps node-sass for the sass package, rebuilds with webpack, surfaces the deprecation warnings the build hides, and opens a PR with the output.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent begins with why the build no longer installs. In a project like wbkd/webpack-starter, package.json asks for node-sass ^8.0.0 and sass-loader ^13.2.0, and package-lock.json holds them at 8.0.0 and 13.2.0. node-sass is a native module, and its README's support table stops at Node 20, which needs version 9; version 8 covers Node 14, 16, 18 and 19. On Node 22, npm ci fails inside node-sass's install script: it finds no usable binary for that Node, tries to compile LibSass locally and gives up. The same README opens by saying Node Sass has reached end of life, and npm marks the package deprecated in favour of sass or sass-embedded.

The swap itself is small, and the agent shows that it is. Both webpack/webpack.config.dev.js and webpack/webpack.config.prod.js name 'sass-loader' with no implementation option, and sass-loader 13 picks the compiler from the installed packages, preferring sass when it is present. So the agent removes node-sass, adds sass, and changes no webpack file. It runs npm run build and reads the stylesheet in build/css/: src/styles/index.scss declares one variable, $body-color: slateblue, and uses it once, and the compiled rule carries the colour through.

Then it looks for what the build is not saying. The production config sets stats: 'errors-only', so npm run build prints nothing about Sass even when Dart Sass has complaints. The agent runs webpack once more with --stats normal and finds a warning on every build: the legacy JS API is deprecated and will be removed in Dart Sass 2.0. That one comes from the loader, not the stylesheet. sass-loader 13 calls the old API, and sass-loader 16 switched to the modern one by default. The agent reports the warning with its source and proposes the loader upgrade as a separate step, because newer sass-loader majors also raise the minimum Node and the latest one drops node-sass support altogether.

For a real stylesheet the warnings are about your code, so the agent checks for the two that matter most. Dart Sass warns on / used for division outside calc() and recommends math.div or calc, and it warns that @import rules are deprecated and will be removed in Dart Sass 3.0, pointing to its automated migrator. The starter's single SCSS file has neither. In a larger project the agent lists every warning with its file and line, fixes divisions in place, and leaves an @import to @use conversion out unless asked, since that changes how variables are scoped across files. It finishes with npm run lint:styles, which runs stylelint src with stylelint-config-standard, to confirm the stylesheet still lints.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Replace node-sass with Dart Sass (the sass package) in this webpack project and open a pull request. Read package.json, package-lock.json, webpack/webpack.common.js, webpack/webpack.config.dev.js, webpack/webpack.config.prod.js, postcss.config.js, .browserslistrc, .stylelintrc.json, .travis.yml and every file under src/styles first. Run npm ci on the sandbox's Node before changing anything and record what happens; check node-sass's README for which Node versions the locked release supports. Remove node-sass and add sass. Say how the locked sass-loader chooses its Sass implementation and whether any webpack config has to change. Run npm run build and show the compiled CSS. The production config hides warnings, so also run the production build with --stats normal and list every Sass deprecation warning with its file and line, saying for each if it comes from the stylesheets or from the loader. Fix deprecated division in the stylesheets. Do not convert @import to @use; count the @import rules and say what the conversion would involve. Do not upgrade sass-loader in this pull request; say which sass-loader major would remove the loader's own warning and what Node version it needs. Run npm run lint:styles. Update .travis.yml or the README only if they mention node-sass.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

The pull request changes package.json and package-lock.json: node-sass out, sass in, and with it the native build tooling node-sass pulled into the lockfile. No webpack config changes, and the description says why, quoting the sass-loader 13 README on which implementation wins. It opens with the failed npm ci from before the change and the successful one after, so the reason for the work is on the page.

The middle of the description is the compiled CSS and the warnings. The CSS from build/css/ is shown in full for a project this size, and for a larger one as a diff against the last build node-sass could produce, where an old Node is available to make it. The warnings are grouped by cause: the loader's legacy API notice, then each division and each @import by file and line. Fixed divisions appear in the diff; the @import count comes with a note that Dart Sass publishes a migrator for it.

A reviewer compares the compiled stylesheet with production's, because Dart Sass and LibSass can differ in number precision and in how they print some values even when the source is unchanged. They also decide what follows. Leaving sass-loader at 13 keeps the build working with a warning that webpack's production config hides; moving to 16 or later removes the warning, and its minimum Node has to be checked against CI, where .travis.yml runs npm run build on the latest and LTS Node lines.

Run it on every repository still on node-sass

Most teams have this in more than one place: an old marketing site, an admin panel, a component library. Send one POST /o/{org}/sessions per repository with this prompt and that repository in resources. Each run reads its own lockfile and stylesheets, so a repository on node-sass 4 with hundreds of partials gets a longer warning list than this starter, and each opens its own pull request. Give the key a webhook_url to receive run.completed for every run it starts, with session_url to read the pull request from.

To keep it from coming back, add an automation in each Project with a schedule trigger on a weekly cron and a timezone, and a prompt that builds with --stats normal, counts Sass deprecation warnings and opens a pull request only when it can remove some. The automation's max runs per hour is its own limit; the key's max_concurrent does not apply to runs an automation starts.

The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.

Why run it on Rush?

This migration is a claim about output: the CSS still comes out, and it comes out the same. That can only be shown by building. In a Rush sandbox the agent runs the failing install, the swap and both builds on a clean machine with a current Node, which is exactly the environment where node-sass breaks, and the run's record keeps each command with its output. The pull request's before and after are copied from that record.

It also finds the warning nobody sees. A developer who swaps the package on a laptop runs npm run build, gets a quiet success and moves on, because the production config suppresses everything but errors. An agent told to rebuild with normal stats brings back the deprecations that will become errors in a later Dart Sass, each tied to a file and line, while the fix is still a small one.

Frequently asked questions

Do I need to change my webpack config?

Usually not. sass-loader resolves the compiler from your installed packages, and version 13 prefers sass when it is there, so removing node-sass and adding sass is enough. A config that sets implementation: require('node-sass') explicitly does need that line changed, and the agent searches for it.

Will my compiled CSS be identical?

For simple stylesheets, in practice yes. Differences show up in number precision, in the formatting of some values and in code that relied on LibSass behaviour Dart Sass treats as an error. The agent shows the compiled output, and a reviewer compares it with what production serves before merging.

What about the slash division warnings?

Dart Sass deprecates / as division outside calc() and suggests math.div(a, b) or calc(a / b). The agent rewrites each one it finds and adds @use "sass:math" at the top of the file, where @use rules have to go. The build output before and after is in the pull request.

Should I use sass or sass-embedded?

Either compiles the same language. sass is pure JavaScript and installs anywhere; sass-embedded wraps the native Dart executable and is faster on large codebases. The agent uses sass unless you say otherwise, since sass-loader 13 picks it by default and it adds no platform-specific binary.

More webpack jobs

More jobs like this: Upgrade dependencies weekly

Keep reading