esbuild-stylus-loader

0.4.6 verified Fri May 01 auth: no javascript

An esbuild plugin for compiling Stylus (.styl) files, currently at v0.4.6. It integrates Stylus preprocessing into esbuild bundling, supporting Stylus options like define, import, include, use, and includeCss. Released under active development with fixes for watch mode and ReDoS vulnerability. Ships TypeScript definitions. Requires esbuild >=0.10.0 and stylus >=0.52.4 as peer dependencies. Differentiated from alternatives (e.g., esbuild-sass-plugin) by its focus on Stylus and compatibility with esbuild's plugin system.

Common errors

error Cannot find module 'stylus' ↓

cause Stylus peer dependency is not installed.

fix

Run 'npm install stylus' or 'yarn add stylus'.

error TypeError: stylusLoader is not a function ↓

cause Incorrect import: using default import instead of named import.

fix

Use import { stylusLoader } from 'esbuild-stylus-loader'.

error Plugin must be an object with a name property ↓

cause Did not call stylusLoader() as a function; passed the function reference instead.

fix

Call stylusLoader() in the plugins array: plugins: [stylusLoader()].

error Options.stylusOptions.define[0] is not an array ↓

cause define items must be arrays of [name, value, raw?].

fix

Ensure define is an array of arrays, e.g., define: [['BG_IMAGE', 'url']].

Warnings

breaking In v0.4.0, stylus was moved from dependencies to peerDependencies. You must install stylus manually. ↓

fix Run 'npm install stylus' or add stylus to your project's dependencies.

breaking In v0.3.0, plugin options were moved into a stylusOptions object. Previously flat options are now nested. ↓

fix Wrap Stylus-specific options in stylusLoader({ stylusOptions: { ... } }).

gotcha The plugin does not automatically include CSS files; you must enable includeCss option. ↓

fix Set includeCss: true in stylusOptions if you want Stylus to process @import './file.css'.

gotcha Watch mode for imported Stylus files requires v0.4.5 or later. Earlier versions only watch the entry file. ↓

fix Upgrade to v0.4.5+ to ensure imported Stylus files trigger rebuilds.

deprecated Minimum esbuild version raised to 0.10.0 in v0.4.6 due to watchFiles option dependency. ↓

fix Ensure esbuild >=0.10.0 is installed.

Install

npm install esbuild-stylus-loader

yarn add esbuild-stylus-loader

pnpm add esbuild-stylus-loader

Imports

stylusLoader

wrong

const stylusLoader = require('esbuild-stylus-loader')

correct

import { stylusLoader } from 'esbuild-stylus-loader'

Package is ESM/CJS dual; named export 'stylusLoader' is the plugin function.

StylusLoaderOptions

wrong

import StylusLoaderOptions from 'esbuild-stylus-loader'

correct

import type { StylusLoaderOptions } from 'esbuild-stylus-loader'

TypeScript type import; not a runtime value.

stylusLoader

wrong

const stylusLoader = require('esbuild-stylus-loader').default

correct

const { stylusLoader } = require('esbuild-stylus-loader')

CJS require destructuring; default export is not available.

Quickstart

Sets up esbuild build with Stylus plugin, showing define and include options.

const { build } = require('esbuild');
const { stylusLoader } = require('esbuild-stylus-loader');

build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    stylusLoader({
      stylusOptions: {
        define: [['BG_IMAGE', 'https://example.com/bg.jpg']],
        include: ['./styles'],
        includeCss: false,
      },
    }),
  ],
}).catch(() => process.exit(1));