babel-plugin-transform-scss

1.2.0 verified Sat Apr 25 auth: no javascript

Babel plugin that converts SCSS/SASS imports to inline CSS and injects them into the document head at runtime. Current stable version 1.2.0, released sporadically. Replaces webpack sass-loader by transforming style imports into JavaScript functions that create <style> tags. Unique for Babel-centric builds without webpack, but requires peer dependencies node-sass ^8.0.0 and sass ^1.3.0. Limited maintainer activity and sparse documentation.

Common errors

error Cannot read properties of undefined (reading '0') ↓

cause Plugin version <1.0.11 had a bug when parsing certain SCSS files.

fix

Upgrade to v1.0.11 or later.

error Module not found: Error: Can't resolve 'node-sass' ↓

cause node-sass is not installed as a peer dependency.

fix

Run 'npm install --save-dev node-sass' or switch to sass.

error Error: Node Sass does not yet support your current environment ↓

cause Incompatible version of node-sass with Node.js or platform.

fix

Use sass (dart-sass) instead of node-sass.

Warnings

deprecated node-sass is deprecated. Consider using sass (dart-sass) instead. ↓

fix Install sass instead of node-sass, and ensure both are listed as peer dependencies.

gotcha Plugin only works in browser environments because it uses document.head. ↓

fix Do not use in server-side rendering (SSR) without checking for window.

gotcha Import paths must be relative (e.g., './style.scss'). Absolute or module paths may fail. ↓

fix Ensure all SCSS imports start with './' or '../'.

breaking v1.2.0 introduced options.include to filter directories. Old configs without include may process too many files. ↓

fix Add include option if you want to restrict transformation to specific folders.

gotcha Identical filenames in different directories now have unique data-scss-component attributes; old code relying on class names may break. ↓

fix Update selectors or tests to use generated unique IDs.

Install

npm install babel-plugin-transform-scss

yarn add babel-plugin-transform-scss

pnpm add babel-plugin-transform-scss

Imports

babel-plugin-transform-scss

wrong

import it in JavaScript code

correct

Add to Babel plugins list in config, e.g. 'plugins': ['babel-plugin-transform-scss']

It's a Babel plugin, not a runtime import.

Quickstart

Shows how to install and configure the plugin, and how it transforms SCSS imports into inline styles at runtime.

// Install: npm install --save-dev babel-plugin-transform-scss node-sass sass
// .babelrc or babel.config.js:
{
  "plugins": [
    ["babel-plugin-transform-scss", { "include": "node_modules" }]
  ]
}
// Then in your source:
import React from 'react';
import './style.scss';

const Button = () => {
  return <div className="button">Custom button</div>;
};
export default Button;