callstack / callstack/linaria

Support and document how to publish modules using Linaria to NPM

Open
#178 14 comments 19 reactions 0 assignees View on GitHub
cat: documentation 📖 cat: improve publishing 🚢 enhancement: approved ✅ status: up for grabs 🙏
Dominant language
TypeScript
Stars
12.4k
Forks
413
PR merge metrics
No merged PRs in 30d

Description

## 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

- [x] Convert imports paths to be relative to the file, pretty-straightforward (#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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.