esbuild-style-loader

0.3.4 verified Fri May 01 auth: no javascript

A style loader plugin for esbuild that supports CSS, SCSS, LESS, Stylus, and CSS Modules. Current stable version is 0.3.4. It uses lightningcss for fast CSS processing and includes autoprefixer with sensible defaults (ios >= 11, android >= 5, chrome >= 54). Unlike other esbuild CSS plugins, it offers zero-config setup, built-in CSS Modules support for files matching .module.css or ?modules query, and handles multiple preprocessors via built-in loaders (LESS built-in, sass via peer dep). Released under MIT license with TypeScript types included.

Common errors

error Error: Cannot find module 'esbuild-style-loader' ↓

cause Package not installed

fix

npm install esbuild-style-loader

error Error: Must use import to load ES Module: esbuild-style-loader ↓

cause Using require() with ESM-only version (v0.3.3+)

fix

Use import { styleLoader } from 'esbuild-style-loader'

error TypeError: styleLoader is not a function ↓

cause Importing wrong symbol or default export

fix

Use named import: import { styleLoader } from 'esbuild-style-loader'

error CSS Modules file './style.css' imported with styleLoader but not treated as module ↓

cause File name does not match .module.css or query

fix

Rename to style.module.css or import with ?modules

Warnings

breaking v0.3.3 removed CJS support for ESM-only builds; update imports accordingly. ↓

fix Switch to ESM imports: import { styleLoader } from 'esbuild-style-loader'

deprecated Passing 'true' for cssModules option is deprecated; use an object with 'pattern' ↓

fix Use cssModules: { pattern: '[local]__[hash]' } instead of cssModules: true

gotcha CSS Modules only work for files matching .module.css or ?modules query; normal imports are treated as global CSS ↓

fix Rename file to .module.css or append ?modules query

gotcha Sass requires the 'sass' peer dependency; node-sass and sass-embedded are not supported ↓

fix Install sass: npm install sass

deprecated The 'namespace' option default changed from 'file' to ['native-component', 'file'] ↓

fix Explicitly set namespace if relying on old behavior

Install

npm install esbuild-style-loader

yarn add esbuild-style-loader

pnpm add esbuild-style-loader

Imports

styleLoader

wrong

const styleLoader = require('esbuild-style-loader')

correct

import { styleLoader } from 'esbuild-style-loader'

ESM-only since v0.3.3; named export, not default.

styleLoader

wrong

const styleLoader = require('esbuild-style-loader').default

correct

const { styleLoader } = require('esbuild-style-loader')

CommonJS destructured import works; no default export.

StyleLoaderOptions

import type { StyleLoaderOptions } from 'esbuild-style-loader'

Type-only import for TypeScript users.

Quickstart

Sets up esbuild with the style loader plugin, bundling CSS imports from app.js and outputting to dist/

import { build } from 'esbuild';
import { styleLoader } from 'esbuild-style-loader';

build({
  entryPoints: ['src/app.js'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    styleLoader({
      filter: /\.(css|less|scss|sass)(\?.*)?$/,
    }),
  ],
}).catch(() => process.exit(1));