ecij

ecij (Extract CSS-in-JS) is a zero-runtime css-in-js plugin for Rolldown and Vite.

It achieves this via static analysis by using oxc-parser, as such it is limited to static expressions. The plugin will ignore dynamic or complex expressions.

The plugin does not process the CSS in any way whatsoever, it is merely output in virtual CSS files for Rolldown and Vite to handle. Separate plugins may be used to process these virtual CSS files.

Installation

npm install -D ecij

The plugin is built on Rolldown's APIs, so rolldown is a required peer dependency. In a Vite project it is already part of the dependency tree — npm and pnpm resolve the peer to that same copy — but package managers which do not install peer dependencies automatically (e.g. Yarn) require it to be installed explicitly.

Usage

Source input:

/* main.ts */
import { css } from 'ecij';
import { redClassname } from './styles';

const myButtonClassname = css`
  border: 1px solid blue;

  &.${redClassname} {
    border-color: red;
  }
`;

/* styles.ts */
import { css } from 'ecij';

const color = 'red';

export const redClassname = css`
  color: ${color};
`;

Build output:

/* js */
const color = 'red';

const redClassname = `css-a1b2c3d4`;

const myButtonClassname = `css-1d2c3b4a`;

/* css */
.css-a1b2c3d4 {
  color: red;
}

.css-1d2c3b4a {
  border: 1px solid blue;

  &.css-a1b2c3d4 {
    border-color: red;
  }
}

Set up

In rolldown.config.ts:

import { defineConfig } from 'rolldown';
import { ecij } from 'ecij/plugin';

export default defineConfig({
  // ...
  plugins: [ecij()],
});

In vite.config.ts:

import { defineConfig } from 'vite';
import { ecij } from 'ecij/plugin';

export default defineConfig({
  // ...
  plugins: [ecij()],
});

Configuration

The ecij() plugin accepts an optional configuration object:

export interface Configuration {
  /**
   * Include patterns for files to process, matched against the module id.
   *
   * @default `/\.[cm]?[jt]sx?$/`
   */
  include?: string | RegExp | ReadonlyArray<string | RegExp> | undefined | null;

  /**
   * Exclude patterns for files to skip, matched against the module id.
   *
   * @default `[/\/node_modules\//, /\.d\.ts$/]`
   */
  exclude?: string | RegExp | ReadonlyArray<string | RegExp> | undefined | null;

  /**
   * Prefix for generated CSS class names.
   *
   * Should not be empty, as generated hashes may start with a digit, resulting in invalid CSS
   * class names.
   *
   * @default `'css-'`
   */
  classPrefix?: string | undefined | null;
}

Example:

ecij({
  classPrefix: 'lib-',
});

Development

# Build the plugin
npm run build

# Format the code
npm run format

# Run the linter
npm run lint

# Auto-fix lints
npm run lint:fix

# Type check
npm run typecheck

# Run tests once
npm test

# Update test snapshots
npm test -- -u

TODO

• Full import/export handling (default/namespace import/export)