esbuild-plugin-sass

1.0.1 verified Mon Apr 27 auth: no javascript maintenance

esbuild plugin for compiling Sass/SCSS files. v1.0.1 (no further updates since 2021). Integrates the node-sass or dart-sass compiler into esbuild's build pipeline. Supports custom Sass options (except file). Differentiates from alternatives like esbuild-sass-plugin by its minimal API and lack of active maintenance. Only peer dependency is esbuild >=0.11.14. Ships TypeScript types.

Common errors

error Error: Cannot find module 'esbuild-plugin-sass' ↓

cause Package not installed or not resolved.

fix

Run npm install esbuild-plugin-sass (and esbuild if not installed).

error TypeError: sassPlugin is not a function ↓

cause Using CJS require() on an ESM-only import; the imported value is an object, not the function directly.

fix

Use dynamic import: const sassPlugin = (await import('esbuild-plugin-sass')).default; or switch to ES modules.

error Error: [plugin: sass] Option 'file' is not allowed ↓

cause Passing 'file' in customSassOptions, which is reserved by plugin.

fix

Remove the 'file' option from customSassOptions. The plugin sets it internally.

Warnings

deprecated Package appears unmaintained since 2021; no updates for esbuild v0.12+ changes. ↓

fix Consider using esbuild-sass-plugin (still maintained) or write custom plugin.

gotcha Requires esbuild >=0.11.14. Using an older version will fail. ↓

fix Update esbuild to >=0.11.14.

gotcha Does not support esbuild's loader option for CSS; generates separate CSS file (does not inline into JS). ↓

fix Use esbuild's CSS handling if you need inlining. This plugin creates a .css file alongside the JS output.

gotcha Assumes sass (dart-sass) is installed; does not work with node-sass by default. ↓

fix Install dart-sass: npm install sass. For node-sass, you must alias 'sass' or modify resolution.

Install

npm install esbuild-plugin-sass

yarn add esbuild-plugin-sass

pnpm add esbuild-plugin-sass

Imports

default
wrong
```
const sassPlugin = require('esbuild-plugin-sass')
```
correct
```
import sassPlugin from 'esbuild-plugin-sass'
```
Package is ESM-only as of v1.0.1; require() will fail unless using dynamic import or a bundler that can handle ESM.

Options

wrong

import { Options } from 'esbuild-plugin-sass' (no runtime value, only type)

correct

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

Options is a TypeScript type, not a runtime export.

default with CommonJS

wrong

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

correct

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

In CJS, the default export is accessed via .default due to ESM compatibility.

Quickstart

Shows how to integrate Sass compilation into an esbuild build script using the plugin.

import esbuild from 'esbuild';
import sassPlugin from 'esbuild-plugin-sass';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'bundle.js',
  plugins: [sassPlugin()],
});

// src/index.js: import './style.scss';