@acab/ecsstatic

🎈 ecsstatic

The predefinite CSS-in-JS library for Vite.

• fully static. compiles away like it never existed.
• uses regular css syntax, not javascript objects.
• minimal api surface: you write some styles, you get back a scoped class.
• suppports nesting selectors and at-rules, including @container, and @layer.
• supports sass itself!

Try one of the starter templates on stackblitz:

• vite + preact
• vite + react
• vite + solid
• astro + react
• astro + solid

Also check out the landing page: ecsstatic.dev.

Usage

Install:

npm install --save-dev @acab/ecsstatic

Add the vite plugin to your config:

import { ecsstatic } from '@acab/ecsstatic/vite';

export default defineConfig({
  plugins: [ecsstatic()],
});

Start using css in any JS/TS file:

import { css } from '@acab/ecsstatic';

export const Button = (props) => {
  return <button {...props} className={button} />;
};

const button = css`
  all: unset;
  font: inherit;
  color: #862e9c;
  border: 1px solid;
  border-radius: 4px;
  padding: 0.5rem 1rem;

  &:hover,
  &:focus {
    color: #be4bdb;
  }
`;

Or use with /scss:

import { css } from '@acab/ecsstatic/scss';

export const Button = (props) => {
  return <button {...props} className={button} />;
};

const button = css`
  @use 'open-props-scss' as op;

  // ...
  color: op.$purple-9;

  &:hover,
  &:focus {
    color: op.$purple-6;
  }
`;

Evaluating expressions (interpolation)

Evaluating expressions interpolated in the template strings works out-of-the-box for many cases but might not work perfectly in big files/projects. If you are seeing unexpected results, try moving your component out to a smaller file.

By default, npm packages are not processed (they are "external"-ized) before evaluating expressions. This requires the package to be compatible with Node ESM. If it doesn't work, you can pass its name to the resolvePackages option to force it to be processed before evaluating expressions.

export default defineConfig({
  plugins: [ecsstatic({ resolvePackages: ['some-non-esm-pkg'] })],
});

Global styles

The createGlobalStyle function can be used to apply unscoped, global styles. Note that this is unnecessary in most cases as you can just create a regular .css/.scss file, but it can be useful for interpolating values that only exist in JS.

import { createGlobalStyle } from '@acab/ecsstatic';

createGlobalStyle`
  :root {
    --foo: ${1 + 1};
  }
`;

Syntax highlighting

For syntax highlighting and intellisense, use the vscode-styled-components extension.

Atomic classes

There is an experimental flag marqueeMode. When enabled, the prod build output will contain atomic classes, where one class maps to one declaration. This can potentially result in a smaller CSS file, at the cost of bloating the markup with lots of classes. This tradeoff can be worth it for large sites where the size of the CSS would be a concern.

export default defineConfig({
  plugins: [ecsstatic({ marqueeMode: true })],
});

Prior art

Huge shoutout to the previous libraries that came before this; ecsstatic would not have been possible without them paving the way.

• styled-components / emotion
• css modules
• linaria

Contributing

Open an issue or see CONTRIBUTING.md.