esmcss

0.2.15 verified Fri May 01 auth: no javascript

esmcss (v0.2.15) enables importing CSS via JavaScript/TypeScript modules (.css.ts/.css.js) and provides focused CSS helper classes, built on esbuild >=0.23.1. It allows you to co-locate styles with components, leveraging esbuild's bundling for zero-runtime CSS. Frequent releases, with a focus on ESM-only workflows and esbuild integration. Differentiates from CSS-in-JS by generating static CSS files during build, avoiding runtime overhead.

Common errors

error Error: esbuild version 0.21.0 does not satisfy peer dependency >=0.23.1 ↓

cause esbuild version too old.

fix

Run npm install esbuild@latest to update to >=0.23.1.

error TypeError: Cannot read properties of undefined (reading 'css') ↓

cause Named import instead of default export; likely using wrong import syntax.

fix

Use import { css } from 'esmcss' instead of import css from 'esmcss'.

error Module not found: Error: Can't resolve 'esmcss/esbuild' ↓

cause Missing or misconfigured path to the plugin.

fix

Install esmcss and import from 'esmcss/esbuild' correctly: import { esmcssPlugin } from 'esmcss/esbuild'.

Warnings

breaking esmcss v0.2.x drops support for esbuild <0.23.1. Upgrade esbuild to >=0.23.1. ↓

fix Update esbuild to 0.23.1 or later.

deprecated The function `createTheme` from v0.1.x is removed; use `css` with CSS variables instead. ↓

fix Replace createTheme with css tagged template literals and CSS custom properties.

gotcha esmcss only supports ESM imports; CommonJS require() will not work. Use dynamic import() in CJS environments. ↓

fix Use `import('esmcss')` in CommonJS or switch to ESM.

gotcha The esbuild plugin must be registered before other plugins that transform CSS. ↓

fix Place esmcssPlugin() early in the plugins array.

gotcha CSS helper classes (xs, sm, etc.) are numeric pixel values (e.g., 480, 768) and must be interpolated in `css` tagged literals, not used directly in JSX styles. ↓

fix Use `${md}` inside css`...` template literal.

Install

npm install esmcss

yarn add esmcss

pnpm add esmcss

Imports

css
wrong
```
import css from 'esmcss'
```
correct
```
import { css } from 'esmcss'
```
css is a named export, not default. Only ESM imports supported.
xxs
```
import { xxs, xs, sm, md, lg, xl, xxl } from 'esmcss'
```
CSS helper classes exported as named constants. TypeScript types available.
.css.ts file convention
wrong
```
Using .css.ts without exporting css tagged template literal
```
correct
```
// styles.css.ts
export const button = css`color: var(--blue);`
```
Files must export css template literals; imported in JS via import { button } from './styles.css.ts'

Quickstart

Shows defining a css tagged template literal with size helpers and using esbuild plugin.

import { css, md, xl } from 'esmcss'
import { build } from 'esbuild'
import { esmcssPlugin } from 'esmcss/esbuild'

// Define styles in a .css.ts file (e.g., styles.css.ts)
export const container = css`
  display: flex;
  padding: ${md};

  @media (min-width: 768px) {
    padding: ${xl};
  }
`

// In your build script
await build({
  entryPoints: ['src/index.js'],
  bundle: true,
  plugins: [esmcssPlugin()],
  outdir: 'dist',
})

// Then import the styles in your JS:
import { container } from './styles.css.ts'
console.log(container) // outputs the generated class name