{"id":21290,"library":"esbuild-sass-plugin","title":"esbuild-sass-plugin","description":"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.","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/glromeo/esbuild-sass-plugin","tags":["javascript","esbuild","plugin","sass","scss","css","postcss","css-modules","typescript"],"install":[{"cmd":"npm install esbuild-sass-plugin","lang":"bash","label":"npm"},{"cmd":"yarn add esbuild-sass-plugin","lang":"bash","label":"yarn"},{"cmd":"pnpm add esbuild-sass-plugin","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency: plugin integrates with esbuild's build system","package":"esbuild","optional":false},{"reason":"peer dependency: required for Sass compilation; alternative to sass package","package":"sass-embedded","optional":true}],"imports":[{"note":"Named export; CommonJS require returns the module object, not the function directly.","wrong":"const sassPlugin = require('esbuild-sass-plugin')","symbol":"sassPlugin","correct":"import { sassPlugin } from 'esbuild-sass-plugin'"},{"note":"CommonJS destructuring is correct; there is no default export.","wrong":"const sassPlugin = require('esbuild-sass-plugin').default","symbol":"sassPlugin","correct":"const { sassPlugin } = require('esbuild-sass-plugin')"},{"note":"SassPluginOptions is a TypeScript type, so use import type to avoid runtime inclusion.","wrong":"import { SassPluginOptions } from 'esbuild-sass-plugin'","symbol":"Type imports","correct":"import type { SassPluginOptions } from 'esbuild-sass-plugin'"}],"quickstart":{"code":"import { sassPlugin } from 'esbuild-sass-plugin';\nimport * as esbuild from 'esbuild';\n\nawait esbuild.build({\n  entryPoints: ['src/index.ts'],\n  bundle: true,\n  outfile: 'dist/bundle.js',\n  plugins: [\n    sassPlugin({\n      type: 'css',\n      cache: true,\n      loadPaths: ['src/styles'],\n      // Optional: use sass-embedded\n      embedded: true\n    })\n  ]\n});\nconsole.log('Build complete.');","lang":"typescript","description":"Shows basic esbuild build setup with the sass plugin, including loadPaths and caching."},"warnings":[{"fix":"Update esbuild and sass-embedded to compatible versions.","message":"Plugin now requires esbuild >=0.27.3 and sass-embedded ^1.97.3 as peer dependencies. Older versions may fail to install or run.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Replace `sass` with `sass-embedded` in your project dependencies.","message":"The `sass` package is no longer supported as a peer dependency. Use `sass-embedded` instead.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Use `import type { SassPluginOptions } from 'esbuild-sass-plugin'`.","message":"TypeScript users may incorrectly import SassPluginOptions as a runtime value. It is a type only and should be imported with `import type`.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Use `const { sassPlugin } = require('esbuild-sass-plugin')`.","message":"CommonJS require() returns the module object; direct usage like `require('esbuild-sass-plugin')()` fails because sassPlugin is a named export.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set `type: 'lit-css'` in the plugin options.","message":"The `type` option defaults to 'css', which emits external CSS files. For lit-element or constructable stylesheets, set `type: 'lit-css'`.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Run `npm install sass-embedded@^1.97.3` or `yarn add sass-embedded@^1.97.3`.","cause":"sass-embedded is a peer dependency and not installed.","error":"Error: Cannot find module 'sass-embedded'"},{"fix":"Use `const { sassPlugin } = require('esbuild-sass-plugin')` instead of `const sassPlugin = require('esbuild-sass-plugin')`.","cause":"CommonJS require returns the module object, not the function directly.","error":"TypeError: sassPlugin is not a function"},{"fix":"Add `import './styles/index.scss'` in your JavaScript or TypeScript entry point.","cause":"The sass file is not included in esbuild's entryPoints; you need to import the SCSS from a JS/TS file.","error":"error: No matching entry point for 'src/styles/index.scss' (plugin: sass)"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}