@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; }}) |