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

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.
   * Can be a string, RegExp, or array of strings/RegExp.
   * @default /\.[cm]?[jt]sx?$/
   */
  include?: string | RegExp | ReadonlyArray<string | RegExp>;

  /**
   * Exclude patterns for files to skip.
   * Can be a string, RegExp, or array of strings/RegExp.
   * @default [/\/node_modules\//, /\.d\.ts$/]
   */
  exclude?: string | RegExp | ReadonlyArray<string | RegExp>;

  /**
   * 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;
}

Example:

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

Development

Building

npm run build

Formatting

npm run format

Type Checking

npm run typecheck

Running Tests

The project uses integration tests with inline snapshot testing to validate transformations.

# Run tests once
npm test

# Run tests with coverage
npm run test:coverage

# Update inline snapshots after intentional changes
npm test -- -u

TODO

• Log CSS extraction failures
• Scope handling
• Validate that the css used refers to the ecij export
• Full import/export handling (default/namespace import/export)
• Sourcemaps