@jgoz/esbuild-plugin-sass

An esbuild plugin for loading Sass/SCSS files using the CSS content type.

This plugin was forked from esbuild-sass-plugin to facilitate migrations from Webpack. Libraries that rely on sass-loader's import resolution logic should mostly just work.

Features

• Uses same module resolution algorithm as Webpack's sass-loader, including ~ as a prefix for node_modules in imports
• Provides a separate transform stage on the resulting CSS that may be used to apply PostCSS/Autoprefixer processing (mimics chained loaders in Webpack)
• Supports the same options as Dart Sass

Install

$ npm i @jgoz/esbuild-plugin-sass

Usage

Add it to your esbuild plugins:

const esbuild = require('esbuild');
const { sassPlugin } = require('@jgoz/esbuild-plugin-sass');

await esbuild.build({
  // ...
  plugins: [sassPlugin()],
});

This will produce a separate CSS output file for each entry point you define containing the transpiled Sass output.

Usage with PostCSS/Autoprefixer

The transform option can be used to process CSS output using PostCSS or any other utility.

const esbuild = require('esbuild');
const { sassPlugin } = require('@jgoz/esbuild-plugin-sass');
const autoprefixer = require('autoprefixer');
const presetEnv = require('postcss-preset-env');
const postcss = require('postcss');

const processor = postcss([autoprefixer, presetEnv()]);

await esbuild.build({
  // ...
  plugins: [
    sassPlugin({
      async transform(source, resolveDir) {
        const { css } = await processor.process(source, { from: resolveDir });
        return css;
      },
    }),
  ],
});

API

function sassPlugin(options?: SassPluginOptions): Plugin

Plugin options:

Name	Type	Default	Description
alias	Record<string, string | string[]>	-	Import aliases to use when resolving imports from within sass files. These will not be used when esbuild resolves imports from other module types.
basedir	string	process.cwd()	Base directory to use when resolving the sass implementation.
functions	Record<string, LegacySyncFunction>	-	Holds a collection of custom functions that may be invoked by the sass files being compiled.
importer	LegacySyncImporter | LegacySyncImporter[]	-	Resolves @import directives between sass files. This is not used when esbuild resolves imports from other module types, e.g., when importing from JS/TS files or when defining a Sass file as an entry point. If left undefined, a default importer will be used that closely mimics webpack's sass-loader resolution algorithm, which itself closely mimic's the default resolution algorithm of dart-sass. If you want to extend the import algorithm while keeping the default, you can import it like so: Example import { createSassImporter } from '@jgoz/esbuild-plugin-sass'; const defaultImporter = createSassImporter( [], // includePaths {}, // aliases ); sassPlugin({ importer: [myImporter, defaultImporter] })
includePaths	string[]	[]	An array of paths that should be looked in to attempt to resolve your @import declarations. When using data, it is recommended that you use this.
indentType	"space" | "tab"	'space'	Used to determine whether to use space or tab character for indentation.
indentWidth	number	2	Used to determine the number of spaces or tabs to be used for indentation.
indentedSyntax	boolean	false	Enable Sass Indented Syntax for parsing the data string or file.
linefeed	"cr" | "crlf" | "lf" | "lfcr"	'lf'	Used to determine which sequence to use for line breaks.
outputStyle	"compressed" | "expanded"	'expanded'	Determines the output format of the final CSS style.
sourceMap	string | boolean	-	Enables the outputting of a source map.
sourceMapContents	boolean	false	Includes the contents in the source map information.
sourceMapEmbed	boolean	false	Embeds the source map as a data URI.
sourceMapRoot	string	-	The value will be emitted as sourceRoot in the source map information.
transform	(css: string, resolveDir: string) => string | Promise<string>	-	A function that will post-process the css output before wrapping it in a module. This might be useful for, e.g., processing CSS output with PostCSS/autoprefixer. Example const postCSS = require("postcss")([ require("autoprefixer"), require("postcss-preset-env")({ stage:0 }) ]); sassPlugin({ async transform(source, resolveDir) { const { css } = await postCSS.process( source, { from: resolveDir } ); return css; } })