@jgoz/esbuild-plugin-sass NPM

@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: Exampleimport { 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. Exampleconst 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; }})