Support and document how to publish modules using Linaria to NPM

[satya164]

Background

Linaria is probably the best option to choose among CSS in JS libraries if you are making a component library which you want to publish on NPM.

• It produces vanilla CSS files, which means anyone can consume them
• It doesn't have a runtime overhead, so regardless what solution the user uses for CSS, this is not going to another CSS in JS lib to the mix

Today I was trying to publish one of my libraries to NPM which uses Linaria but hit a couple of roadblocks. I hope we can address them.

Approaches

• Use single: true and ask users to take care of loading the CSS file
• Use single: false and require a bundler like webpack to load the CSS files
• Publish the source to npm and ask users to transpile their node_modules with Babel

Blockers

• The inserted imports are absolute paths, which make it impossible to share the stylesheets among different machines
• The class names might not be unique because they are based on developer's folder structure, so if two people named "Dave" have same folder structure, e.g. Users/Dave/projects/components, but have libraries with different names, the class names might clash

Proposal

• Convert imports paths to be relative to the file, pretty-straightforward (fix: insert relative imports for CSS files and support absolute path in outDir #180)
• It's impossible to generate globally unique names, but we can have some logic so that the hashes include the package name, for example: instead of src/App.js, we use awesome@version~src/App.js to generate the hash, where awesome is the name of the package and version is the version of package we read from package.json if it exists, this assumes package names are globally unique. This won't work properly in some scenarios where the styles changed but version number didn't (e.g. installing from git), but it's impossible/extremely hard to do it.

Currently, I only need the first one, which should be easy to fix. Appreciate your thoughts.

We also need to document the process of publishing libraries using Linaria to NPM.

[mxstbr]

FWIW I'm just going to chime in here and challenge this statement:

It produces vanilla CSS files, which means anyone can consume them

That is why we even started thinking about making a CSS-in-JS library, which ended in styled-components. We made ElementalUI (which is on npm), but users would have to use webpack and configure it exactly right with the less and css loader so they could use our components, which was a pain.

Instead, styled-components lets you publish components and your users don't have to care about how exactly it is styled: they just import it and are ready to go! If they wanna override it, just add a className and boom, done.

I don't think that assumption ("It generates CSS files so it's great for npm libs!") is true at all, in fact I think it hurts the usability.

[satya164]

I think styled-components could have been a nice solution to this problem, but there are several other CSS in JS libraries too. Which means that if developers start publishing code using CSS in JS libraries to NPM, it's not going to be only styled-components. Developers are going to use their preferred libraries. And for the users using those libraries, they might get multiple CSS in JS libraries included in their bundles, and even multiple copies of the same CSS in JS library are possible when the libraries use different versions.

In addition to this, there's also the question if multiple CSS in JS libs going to conflict with each other. I have no idea, but it doesn't seem far-fetched.

Even if we solve these issues somehow, for people who do server rendering, they have to configure it to generate CSS for each of the CSS in JS libraries used by their dependencies, which is far more worse than configuring their bundler once. And I'm not sure how it will work if the library you depend upon uses a different version of the same CSS in JS library that you use in your app/from a different dependency. When those libraries upgrade/change their dependency on the CSS in JS library, you also have to update your server rendering code.

If they wanna override it, just add a className and boom, done.

I'm not sure how will it work. Won't they have to worry about insertion order? i.e. whatever styling solutions they use, they need to make sure that their CSS gets injected after the library injects its CSS. Which might be tricky.

No doubt vanilla CSS files are not fully automatic (they are in parcel though) and hence not a great DX, but they avoid all of the above issues. The configuration is one-time and they provide a better UX overall. It's certainly not perfect, but it's the best we have currently.

[mxstbr]

I see where you're coming from but we're working on all of those DX issues with https://github.com/cssinjs/istf-spec and @kitten's github.com/kitten/sweetsour, so interop will soon be the standard for CSS-in-JS libs! CSS files ain't changing anytime soon 😉

Anyways, let's agree to disagree, just wanted to chime in with those thoughts.

[satya164]

I don't think there's anything to disagree here. These are not opinions, but problems which prevent using CSS in JS library.

ISTF is great, and I hope it'll solve most of these issues. But to do that, all CSS in JS libraries need to adopt that. What you're saying is ideal, but not practical right now. It'll happen, but in future. And until that happens, vanilla CSS files are the best we have.

[kitten]

@satya164 To be fair, not all CSS-in-JS libraries need to adopt ISTF or even the connected pipeline. The important part is that a diverse amount of libraries that might or might not form a majority adpot it.

Btw it'd be great to talk about how we can proceed with Sweetsour/ISTF. I'm planning to use it for React Native first to test out its constraints and practicality.

[mxstbr]

I don't think there's anything to disagree here.
[...] vanilla CSS files are the best we have.

That's exactly where we disagree!

For our needs, a shared component library that's meant to be used by any developer who can run npm install, vanilla CSS (or less or sass or linaria) didn't and still doesn't work. That's why we built styled-components, and it is a better solution than vanilla CSS files for our use case.

I'm not saying styled-components is perfect, don't get me wrong you identified very real pain points above, but with these (temporary) pain points (which we're tackling) it's still a better solution for us than vanilla CSS.

That's why I said that the statement above doesn't ring true for my use case at all:

"Linaria is probably the best option [...] if you are making a component library which you want to publish on NPM"

YMMV of course and you're free to say whatever the hell you want, all I'm trying to get across is that that sentence doesn't make any sense to me after I spent two years trying to get rid of vanilla CSS files in my npm packages 😉

[satya164]

Btw it'd be great to talk about how we can proceed with Sweetsour/ISTF. I'm planning to use it for React Native first to test out its constraints and practicality.

HMU! You know where to find me :D