css-in-js tooling direction

[43081j]

i figured a discussion might be the best place to track this stuff since it can easily get lost on discord.

CSS in lit components basically has two ways of working right now:

• external CSS (import css files. via build tooling for now at least), transform and interact with those files like any other normal CSS files
• embedded CSS (via lit templates, i.e. static styles, adopted sheets, etc)

in the recent eng catch ups we decided to lean more towards people using external CSS if they want to make use of css tooling.

External CSS

In an ideal world, we would have import assertions and CSS modules such that this works:

import sheet from './styles.css' assert {type: 'css'};

class SomeElement extends LitElement {
  static styles = [sheet];
}

For now, you can still achieve this without import assertions by using a bundler.

Pros

• All existing CSS tooling works out of the box

Cons

• Build required
• Interpolations not possible

Existing solutions

rollup-plugin-import-css exists to allow you to import CSS in your JS files via rollup (also supports import assertions).

Various other equivalent solutions exist for webpack, esbuild and so on too.

Embedded CSS

Using lit styles as normal:

class MyElement extends LitElement {
  static styles = css`
    .foo { color: hotpink; }
  `;
}

In order to use any tooling with this, you would need something which understands template literals and expression interpolation into them.

Pros

• Can interpolate expressions, have dynamically created styles at run-time, etc
• Follows what is currently documented in the lit docs
• No build needed in theory (just tooling you run against your sources)

Cons

• No existing CSS tooling works out of the box with it
• Existing tooling needs plugins to tell it how to understand lit templates (e.g. a postcss syntax)
• Dealing with interpolation in such plugins is overly complicated

Existing solutions

postcss-lit exists as a custom syntax to tell postcss how to interpret embedded CSS. Most CSS tooling depends on postcss so this allows users to use tailwind, stylelint, etc already.

However, it needs a bit of a refactor at some point and I am the sole maintainer so it is taking a long time.

I won't go into it too much but it all comes down to handling interpolations. There are two solutions, both are fairly complex and both have their downsides. There isn't really a "perfect" solution.

Examples

Some examples i've seen of why people would choose to embed css over making it external. Most are to do with interpolations.

From a related GH issue:

export const baseStyles = css`
  button {
    background-color: var(--app-button-color, ${unsafeCSS(tokens.brandColor)});
  }
`;

From another GH comment:

const headings = [...Array(6).keys()].map((i) => css`
  h${i + 1}, .nb-h${i + 1} {
    color: var(--nb-h${i + 1}-color);
  }
`);

I think @bennypowers also has something along these lines at redhat (for now).

You get the idea. People are using interpolations to essentially create their design system CSS at run-time via computations.

Of course we could argue people should do that at build time, and it would be more efficient (for the user, bundle size, etc).

However, we should assume the worst: that these people don't have the time/budget to refactor their design systems so are likely to stick with what they have.

Wrap up

Personally i feel like we can't push one way or the other. We need to at least have basic support or documentation (or both) for both solutions/directions.

For external stylesheets, i suggest we document "integrations" somewhere on lit.dev. For example, a brief page for:

• Integrating styles with rollup
• Integrating styles with esbuild

For embedded stylesheets, I already have the majority of the postcss syntax we need. There's a very large bump in the road im slowly climbing up. If i had any help getting over that, I feel like it'd be a fairly stable solution we'd barely have to touch ever again.

I'd also be happy to move postcss-lit into the monorepo if thats a sensible idea at some point too. Keep in mind though, it has two parts:

• the lit-specific syntax
• the underlying css-in-js support it builds on

Both are packages i maintain.

cc @kevinpschaaf @justinfagnani

[iSokrat]

Hi all, I've described more cases which would be nice to support 43081j/postcss-lit#47. According to the lit docs, they are all possible and, actually, on my project <style></style> approach (more than 500 components) is used in most of the components.

[jodekirk]

I would like to use external .css, but after upgrading npm packages had issues and gave up. Upgraded to rollup 3 and installed rollup-plugin-import-css, but had csstag browser errors after copying the website to the web server.
I would love to see updated examples showing how to use the CSS imports with TypeScript and Rollup.

[jodekirk]

The css import browser error msg I was getting is:
s-tag.js:6 Uncaught TypeError: Failed to set the 'adoptedStyleSheets' property on 'ShadowRoot': Failed to convert value to 'CSSStyleSheet'. at css-tag.js:6:994 at ge.createRenderRoot (reactive-element.js:6:2901) at ge.createRenderRoot (lit-element.js:6:163) at ge.connectedCallback (reactive-element.js:6:3013) at ge.connectedCallback (lit-element.js:6:478) at q.S (lit-html.js:6:4576) at q.T (lit-html.js:6:4650) at q.$ (lit-html.js:6:5024) at q._$AI (lit-html.js:6:4483) at Y (lit-html.js:6:7837) (

[muratcorlu]

I personally use external css via @bennypowers’s lit-css and happy with it. I will also definitely try CSS Module Scripts once its arrived to browsers. I would like to see built-in support (maybe with a polyfilll for CSS modules) for using external files.

[bennypowers]

FWIW and IMO it's a great idea to document the "interpolate in your ts sources and pile ast-aware tools on top" approach, but I think it would be a liability to support that by moving such tooling into the monorepo. This especially as the import assertions proposal has pivoted from assert syntax with no runtime significance (back) to with syntax that controls runtime behaviour, which means in the near future I'll get to put a big warning on the lit-css README and instruct people to just use the browser APIs instead.

[43081j]

given the two available methods of having stylesheets:

• have an inline styles static template
• import an external css file via a bundler

once import attributes land, it means the latter will disappear rather than the former.

we'll ultimately end up with:

• have inline styles
• import external css via import attributes

so we need to document and support both.

supporting the latter just means making sure imported stylesheets can be consumed by lit (naturally they will, so this one will "just work").

the inline styles however, will still be the primary use case and what people read in the docs, examples, starters, etc.

thats really why i was suggesting we move postcss-lit into the monorepo. i agree also it is pretty complex code though to support such transforms.

[muratcorlu]

Correct me if I'm wrong but CSS Module Scripts is not exactly the same as what lit-css provides. lit-css imports external css as inline in build time but CSS Module Scripts will fetch style on runtime. I'm not sure about the effect of this difference in the FOUC effect, so I still see a value to have "external css in dev env" approach.

It would be like a dream to have style and script in same file but in separate sections (aka Single File Components) supported in browsers natively, but this is not an option anymore I think.

[43081j]

you're right, lit-css (and other tools solving the same problem) inline the referenced css as templates.

however, it becomes a non-lit problem to solve when import attributes land.

at that point, its the responsibility of the bundler. for example, i'd expect someone makes a rollup plugin (or rollup itself) which has the option to bundle imported assets as JS rather than loading them at runtime.

[yorrd]

honestly, we do a lot with a custom directive along the lines of <element ${css({} satisfies Styles)}></element>. Component level styles only if need be. Therefore we don't have a lot of component level styles. Therefore, I would prefer embedded styles.

[redfox-mx]

Hi! Recently I have noticed one of the biggest problems with how "normal" css template tags work in lit. Beyond how you can import your styles, css tooling nowadays does a lot more. Transform your css dialects, add browser-specific prefixes, generate on-demand css classes, or create hashed identifiers for your shared styles. And usually, these features are part of css ecosystem through bundlers plugins, so you don't need to reinvent the wheel! Probably our focus should need to be on how to integrate these cool plugins into a lit-specific context. I start to look at the work of @bennypowers and @43081j with lit-css monorepo and lit-postcss, and It is cool!!. I dream about some holistic approach with both initiatives lit-css only needs to take care of how to transform code from resulting css post-processed files into lit tagged templates (with some ast code manipulations, just like postcss-lit does). It can be more powerful and easier to integrate with other tools. I don't know, maybe I am so enthusiastic or innocent, but we can build great things together.

PS: Of course, I write another plugin for vite (maybe you must try the alpha tag and not the latest) vite-plugin-lit-css