esbuild-plugin-ekscss

0.0.23 verified Fri May 01 auth: no javascript

An esbuild plugin that adds support for XCSS (extensible CSS) preprocessing during bundling. Current stable version 0.0.23, actively maintained. Integrates with esbuild >=0.13.0 and ekscss ^0.0.23. Differentiates from other CSS plugins by leveraging the ekscss preprocessor for custom syntax and variables.

Common errors

error Error: Cannot find module 'esbuild-plugin-ekscss' ↓

cause Package not installed or mismatched peer dependencies

fix

Run npm install esbuild-plugin-ekscss ekscss esbuild@latest

error TypeError: (intermediate value).filter is not a function ↓

cause ekscssPlugin() called without options or with invalid options

fix

Call ekscssPlugin() without arguments or with an object: ekscssPlugin({ filter: /.*\.xcss$/ })

error Error: Build failed with 1 error: error: Expected ';' ↓

cause XCSS syntax error in a .xcss file

fix

Check your XCSS file for missing semicolons or incorrect syntax per ekscss spec.

Warnings

breaking ekscss 0.0.23 introduced changes that may break XCSS syntax used in earlier versions ↓

fix Review ekscss changelog for updated syntax rules.

deprecated The 'loader' option in plugin options is deprecated and will be removed in v1.0.0 ↓

fix Use 'filter' option instead.

gotcha Plugin will not process files that are not imported/required in the bundle ↓

fix Ensure all XCSS files are imported in your entry points or use esbuild's 'inject' option.

Install

npm install esbuild-plugin-ekscss

yarn add esbuild-plugin-ekscss

pnpm add esbuild-plugin-ekscss

Imports

ekscssPlugin

wrong

const ekscssPlugin = require('esbuild-plugin-ekscss')

correct

import { ekscssPlugin } from 'esbuild-plugin-ekscss'

ESM-only package. No default export; use named import.

xcssPlugin

wrong

import { xcssPlugin } from 'esbuild-plugin-ekscss'

correct

import { ekscssPlugin } from 'esbuild-plugin-ekscss'

The exported symbol is ekscssPlugin, not xcssPlugin.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-ekscss'

correct

import type { PluginOptions } from 'esbuild-plugin-ekscss'

PluginOptions is a TypeScript interface; use type import to avoid runtime emission.

Quickstart

Shows basic usage of esbuild-plugin-ekscss with esbuild's build API, bundling XCSS files.

import { build } from 'esbuild';
import { ekscssPlugin } from 'esbuild-plugin-ekscss';

await build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outfile: 'dist/bundle.js',
  plugins: [ekscssPlugin()],
});