Frequently Asked Questions

General

How does ECSS differ from CSS Modules or styled-components?

The logic of "which style to apply" lives in the .ecss file (in @if conditions), not in the component, and is fully typed. Static CSS reaches the browser — no style generation at runtime. For more, see Comparison.

Do I have to give up plain CSS?

No. ECSS is a superset of CSS: any valid CSS stays valid ECSS. Directives are added as needed.

How much JavaScript ends up in the bundle?

The minimum: static CSS plus a tiny helper that sets the class and data attributes. No style computation in the browser — see How ECSS Compiles.

Is SSR supported?

Yes. The styles are static CSS, so SSR works out of the box. The Astro adapter renders with no client-side JS at all.

Is TypeScript required?

No, ECSS works in JS projects too. But in TypeScript you get autocompletion and parameter checking — see TypeScript Integration.

Styles and syntax

Are nesting (&), @media, and var() supported?

Yes. CSS nesting and native at-rules (@media, @supports, @container, …) work as usual; var() and custom properties too.

Can I use Sass/SCSS syntax inside ECSS?

No. ECSS is a superset of plain CSS, not SCSS: $var variables, @mixin/@include, @function, @each/@for loops, and similar constructs are not supported — many of them complicate styles. Some of the usual tasks are solved with ECSS's own features: nesting (native CSS), tokens via @const, conditions via @if. An equivalent of mixins and functions is planned for the future.

How does @enum differ from @const?

@enum is a list of allowed values (a type for @param); @const is a reusable value (a token). See Enums and Constants.

How does extends differ from @external?

extends is inheritance: a block absorbs the parent's styles. @external is contextual styling of another block inside the current one, without inheritance. See Inheritance.

Components and frameworks

Why does my <EButton> render as a <div>?

By default the component's root tag is <div>. Specify the one you need via the as prop: <EButton as="button">. See Components and Adapters.

Can I set the HTML tag right in .ecss (like styled.button)?

No, and that's deliberate. ECSS's philosophy is to describe only styles and the management of their state; everything related to markup is decided at the component level. So the tag is set at usage time via the as prop: <EButton as="button">, <ECard as="section">.

How do I pass regular attributes and handlers (id, onClick, aria-*)?

Any props other than params and as are forwarded to the root element as is.

Does ECSS work without a framework?

Yes — the Vanilla JS (DOM) adapter gives you components on the plain DOM API.

Can I use ECSS in Angular?

Not yet. There is no separate adapter for Angular (the ready-made adapters are React, Vue, Svelte, SolidJS, Astro, and plain DOM), and the build integration currently works only through Vite, which isn't part of Angular's standard toolchain. This may change once plugins for webpack and rspack appear.

Can I use multiple frameworks in one project?

Yes: register multiple adapters and choose the one you need with the ?<id> suffix on import. See Multiple adapters.

Can I change the E prefix in the component name?

Yes, with the adapter's componentNamePrefix option — see the adapters overview.

Build and integration

Which bundlers are supported?

At the moment (version 0.2) — only Vite (@ecss/vite-plugin). The configuration (@ecss/config) is not tied to a bundler; support for webpack and rspack is planned later.

ECSS compiles to modern CSS — what about older browsers?

ECSS does not do downleveling: the output is plain modern CSS. Support for older browsers (vendor prefixes, polyfills for new features) is provided by a separate CSS post-processing step at the bundler level — for example, Lightning CSS (optionally supported by Vite) or PostCSS with Autoprefixer / postcss-preset-env, configured through Browserslist.

Is there a separate CLI?

No. ECSS works as a bundler plugin.

Do I need to commit the .ecss/ directory?

No — it is recreated on every build. Add .ecss to .gitignore.

Why does ESLint complain about files in the .ecss/ folder?

.ecss/ is generated code (components and types), not your sources. It's recommended to add the directory to the linter's and formatter's ignore lists, just like in .gitignore: for example, ignores: ['.ecss/**'] in the ESLint flat config (or the line .ecss in .eslintignore / .prettierignore).

Is there ECSS support in Stylelint?

No. Stylelint does not understand ECSS directives (@block, @param, @if, etc.). Errors in .ecss are already caught at the compilation stage, and a built-in ECSS linting of its own is planned for the future — without any dependency on Stylelint.

Why isn't my .ecss import typed?

Most likely rootDirs isn't set up in tsconfig. See TypeScript Integration.