esbuild-sass-plugin

3.7.0 verified Mon Apr 27 auth: no javascript

An esbuild plugin for compiling Sass and SCSS files, supporting PostCSS, CSS modules, constructable stylesheets for custom elements, dynamic styles, and CSS result import for lit-element. Version 3.7.0 requires esbuild >=0.27.3 and sass-embedded ^1.97.3 as peer dependencies. Released actively, it offers caching, URL rewriting, pre-compiling for global resources, and support for Sass Embedded Async API. Key differentiators include lit-css output for web components, CSS module support, and the ability to use both sass and sass-embedded backends.

Common errors

error Error: Cannot find module 'sass-embedded' ↓

cause sass-embedded is a peer dependency and not installed.

fix

Run npm install sass-embedded@^1.97.3 or yarn add sass-embedded@^1.97.3.

error TypeError: sassPlugin is not a function ↓

cause CommonJS require returns the module object, not the function directly.

fix

Use const { sassPlugin } = require('esbuild-sass-plugin') instead of const sassPlugin = require('esbuild-sass-plugin').

error error: No matching entry point for 'src/styles/index.scss' (plugin: sass) ↓

cause The sass file is not included in esbuild's entryPoints; you need to import the SCSS from a JS/TS file.

fix

Add import './styles/index.scss' in your JavaScript or TypeScript entry point.

Warnings

breaking Plugin now requires esbuild >=0.27.3 and sass-embedded ^1.97.3 as peer dependencies. Older versions may fail to install or run. ↓

fix Update esbuild and sass-embedded to compatible versions.

deprecated The `sass` package is no longer supported as a peer dependency. Use `sass-embedded` instead. ↓

fix Replace `sass` with `sass-embedded` in your project dependencies.

gotcha TypeScript users may incorrectly import SassPluginOptions as a runtime value. It is a type only and should be imported with `import type`. ↓

fix Use `import type { SassPluginOptions } from 'esbuild-sass-plugin'`.

gotcha CommonJS require() returns the module object; direct usage like `require('esbuild-sass-plugin')()` fails because sassPlugin is a named export. ↓

fix Use `const { sassPlugin } = require('esbuild-sass-plugin')`.

gotcha The `type` option defaults to 'css', which emits external CSS files. For lit-element or constructable stylesheets, set `type: 'lit-css'`. ↓

fix Set `type: 'lit-css'` in the plugin options.

Install

npm install esbuild-sass-plugin

yarn add esbuild-sass-plugin

pnpm add esbuild-sass-plugin

Imports

sassPlugin
wrong
```
const sassPlugin = require('esbuild-sass-plugin')
```
correct
```
import { sassPlugin } from 'esbuild-sass-plugin'
```
Named export; CommonJS require returns the module object, not the function directly.

sassPlugin

wrong

const sassPlugin = require('esbuild-sass-plugin').default

correct

const { sassPlugin } = require('esbuild-sass-plugin')

CommonJS destructuring is correct; there is no default export.

Type imports

wrong

import { SassPluginOptions } from 'esbuild-sass-plugin'

correct

import type { SassPluginOptions } from 'esbuild-sass-plugin'

SassPluginOptions is a TypeScript type, so use import type to avoid runtime inclusion.

Quickstart

Shows basic esbuild build setup with the sass plugin, including loadPaths and caching.

import { sassPlugin } from 'esbuild-sass-plugin';
import * as esbuild from 'esbuild';

await esbuild.build({
  entryPoints: ['src/index.ts'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [
    sassPlugin({
      type: 'css',
      cache: true,
      loadPaths: ['src/styles'],
      // Optional: use sass-embedded
      embedded: true
    })
  ]
});
console.log('Build complete.');