callstack / linaria

Zero-runtime CSS in JS library

Zero-runtime CSS in JS library.

---

Features

• Write CSS in JS, but with zero runtime, CSS is extracted to CSS files during build
• Familiar CSS syntax with Sass like nesting
• Use dynamic prop based styles with the React bindings, uses CSS variables behind the scenes
• Easily find where the style was defined with CSS sourcemaps
• Lint your CSS in JS with stylelint
• Use JavaScript for logic, no CSS preprocessor needed
• Optionally use any CSS preprocessor such as Sass or PostCSS
• Supports atomic styles with @linaria/atomic

Why use Linaria

Learn how Airbnb improved both developer experience and web performance with Linaria

Installation

npm install @linaria/core @linaria/react @wyw-in-js/babel-preset

or

yarn add @linaria/core @linaria/react @wyw-in-js/babel-preset

Setup

Linaria is now built on top of wyw-in-js.dev. It supports various bundlers to extract the CSS at build time. To configure your bundler, check the following guides on the wyw-in-js.dev site:

• webpack
• esbuild
• Rollup
• Vite
• Svelte

See Configuration to customize how Linaria processes your files.

Syntax

Linaria can be used with any framework, with additional helpers for React. The basic syntax looks like this:

import { css } from '@linaria/core';
import { modularScale, hiDPI } from 'polished';
import fonts from './fonts';

// Write your styles in `css` tag
const header = css`
  text-transform: uppercase;
  font-family: ${fonts.heading};
  font-size: ${modularScale(2)};

  ${hiDPI(1.5)} {
    font-size: ${modularScale(2.5)};
  }
`;

// Then use it as a class name
<h1 className={header}>Hello world</h1>;

You can use imported variables and functions for logic inside the CSS code. They will be evaluated at build time.

If you're using React, you can use the styled helper, which makes it easy to write React components with dynamic styles with a styled-component like syntax:

import { styled } from '@linaria/react';
import { families, sizes } from './fonts';

// Write your styles in `styled` tag
const Title = styled.h1`
  font-family: ${families.serif};
`;

const Container = styled.div`
  font-size: ${sizes.medium}px;
  color: ${props => props.color};
  border: 1px solid red;

  &:hover {
    border-color: blue;
  }

  ${Title} {
    margin-bottom: 24px;
  }
`;

// Then use the resulting component
<Container color="#333">
  <Title>Hello world</Title>
</Container>;

Dynamic styles will be applied using CSS custom properties (aka CSS variables) and don't require any runtime.

See Basics for a detailed information about the syntax.

Demo

Documentation

• Basics
• API and usage
  • Client APIs
  • Server APIs
• Configuration
• Dynamic styles with css tag
• Theming
• Critical CSS extraction
• Bundlers integration
  • webpack
  • Rollup
• CLI
• Linting
• How it works
• Example

Contributing

We appreciate any support in library development!

Take a look on Contributing docs to check how you can run Linaria in development mode.

Trade-offs

• No IE11 support when using dynamic styles in components with styled, since it uses CSS custom properties

• Dynamic styles are not supported with css tag. See Dynamic styles with css tag for alternative approaches.

• Modules used in the CSS rules cannot have side-effects. For example:

  import { css } from '@linaria/core';
  import colors from './colors';
  
  const title = css`
    color: ${colors.text};
  `;

  Here, there should be no side-effects in the colors.js file, or any file it imports. We recommend to move helpers and shared configuration to files without any side-effects.

Interoperability with other CSS-in-JS libraries

Linaria can work together with other CSS-in-JS libraries out-of-the-box. However, if you want to use styled components from Linaria as selectors in styled-components/emotion, you need to use @linaria/interop

Editor Plugins

VSCode

• Syntax Highlighting - language-babel
• Autocompletion - vscode-styled-components
• Linting - stylelint

Atom

• Syntax Highlighting and Autocompletion - language-babel

Webstorm

• Syntax Highlighting & Autocompletion - webstorm-styled-components

Sublime Text

• Syntax Highlighting & Autocompletion - Naomi, JSCustom (refer to document on how to turn on Styled Component syntax)
• Linting - SublimeLinter-stylelint, LSP Stylelint

Recommended Libraries

• gatsby-plugin-linaria – Gatsby plugin that sets up Babel and webpack configuration for Linaria.
• polished.js - A lightweight toolset for writing styles in JavaScript.
• craco-linaria - A Craco plugin that allows you to use Linaria without ejecting from a CRA.

Inspiration

• glam
• styled-components
• css-literal-loader

Acknowledgements

This project wouldn't have been possible without the following libraries or the people behind them.

• babel
• stylis.js

Special thanks to @kentcdodds for his babel plugin and @threepointone for his suggestions and encouragement.

Made with ❤️ at Callstack

Linaria is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. Callstack is a group of React and React Native geeks, contact us at [email protected] if you need any help with these or just want to say hi!

Like the project? ⚛️ Join the team who does amazing stuff for clients and drives React Native Open Source! 🔥

Sponsors

Contributors

Thanks goes to these wonderful people (emoji key):

Paweł Trysła 💻 📖 🤔	Satyajit Sahoo 💻 📖 🤔	Michał Pierzchała 💻 📖 🤔	Lucas 📖	Alexey Pronevich 📖	Wojtek Szafraniec 💻	Anton Evzhakov 💻 🤔 📖
Tushar Sonawane 📖 💡	Ferran Negre 📖	Jakub Beneš 💻 📖	Oscar Busk 🐛 💻	Dawid 💻 📖	Kacper Wiszczuk 💻 📖	Denis Rul 💻
Johan Holmerin 💻 📖	Gilad Peleg 📖	Giuseppe 💻	Matija Marohnić 💻 📖	Stefan Schult 💻	Ward Peeters 💻	radoslaw-medryk 💻
杨兴洲 💻	Dawid Karabin 📖	Chris Abrams 💻 📖 🤔	Jayphen 💻	c4605 💻	Toru Kobayashi 💻	Jakub Mazurek 💻
Joshua Nelson 💻 🤔 📖	Tomasz Krzyżowski 💻	Martin Schulze 💻	wmzy 💻	Hyeseong Kim 💻	Martin Hochel 💻	Daniel Lo Nigro 💻
0xflotus 💻	Afzal Sayed 💻	AijiUejima 💻	Oleksii Vasyliev 💻	Alican Erdoğan 💻	Aman Kubanychbek 💻	Andrew Gerard 💻
Andrey Frolov 💻	Benjamin Solum 💻	Billy Kwok 💻	Christian Todd 💻	David Peek 💻	Denis Skiba 💻	Dima Kharitonov 💻
Gabriel Valfridsson 💻	Gitai 💻	Hampus Kraft 💻	Igor Sukharev 💻	Ikko Ashimine 💻	Iman Mohamadi 💻	JB 💻
Jack Works 💻	James George 💻	Jed Mao 💻	Joe Lencioni 💻	Joey Cozza 💻	Juan Ferreras 💻	Kazuma Ebina 💻
Lars Kappert 💻	Luciano Mammino 💻	Madhav Varshney 💻	Malash 💻	Martijn Swaagman 💻	Matias Lahti 💻	Michael James 💻
Michael Strobel 💻	Michał Chudziak 💻	Mike 💻	Mike Stop Continues 💻	Mokshit Jain 💻	Oleksandr Fediashov 💻	Paddy O'Brien 💻
Patrik Smělý 💻	Pavel Udaloff 💻	Przemysław Bitkowski 💻	RiN 💻	Roman Sokhan 💻	Seokmin Hong (Ray) 💻	Serge K Lebedev 💻
Sergey Korovin 💻	Shreyas Sreenivas 💻	Sky Wickenden 💻	Stanislav Panferov 💻	Ted Jenkins 💻	Thanh Tran 💻	Thor Amorim 💻
tobenna 💻	Tomas Carnecky 💻	Tsubasa1218 💻	Turadg Aleahmad 💻	Vitor Buzinaro 💻	Mistereo 💻	Vladislav Kozulya 💻
Yuhei Yasuda 💻	Danil Kamyshov 💻	Sebastian Landwehr 💻	everdimension 💻	ptol 💻	roottool 💻	ryamaguchi0220 💻
simka 💻	soso 💻	Nikita Skovoroda 💻	黄小健 💻	iMoses 💻	Jeremy Neander 💻	Andy Parsons 💻
Platane 📖	Tim Kutnick 📖	Dmitrii Pikulin 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

linaria's Issues

Review and update website content before open sourcing

Allow to disable auto prefixng for extracted CSS

Currently the CSS will be autoprefixed to support as far as IE8. We need to be able to customize the browser target to reduce any extra code we don't need.

Perhaps we should switch to PostCSS instead of stylis as the parser so we have finer control over the extraction.

Add a `include` helper

What do you think about a include helper (kinda like the @include in sass)

const a = css`
  color: blue;
`;

const b = css`
  ${include(a)}
  font-family: sans-serif;
`

Will produce:

.a_hg654gv {
  color: blue;
}

.b_56rwtyf {
  color: blue;
  font-family: sans-serif;
}

The implementation will be something like:

function include(...classNames: string[]): string {
  return classNames.reduce((acc, curr) => {  
    const style = stylesCache.find(item => item.selector === curr);
    if (typeof style !== 'undefined') {
      return acc + '\n' + style.css;
    }
    throw new Error(`Unable to find CSS for the class name: ${curr}`);
  }, '');
}

Add cache to babel plugin in order to skip builds

Website

• design
• development

Action required: Greenkeeper could not be activated 🚨

🚨 You need to enable Continuous Integration on all branches of this repository. 🚨

To enable Greenkeeper, you need to make sure that a commit status is reported on all branches. This is required by Greenkeeper because we are using your CI build statuses to figure out when to notify you about breaking changes.

Since we did not receive a CI status on the greenkeeper/initial branch, we assume that you still need to configure it.

If you have already set up a CI for this repository, you might need to check your configuration. Make sure it will run on all new branches. If you don’t want it to run on every branch, you can whitelist branches starting with greenkeeper/.

We recommend using Travis CI, but Greenkeeper will work with every other CI service as well.

ESLint or Stylelint plugin to lint styles

It should be possible to use class names inside css text

Currently the following throws an error:

const title = css`
  color: blue;
`;

const container = css`
  padding: 2rem;

  .${title} {
    margin-bottom: 1rem;
  }
`;

Babel plugin doesn't rewire imports with `yarn link`

Webpack loader to extract the CSS to a separate file

It can probably work with extract-text-webpack-plugin to extract the CSS to separate file. Or maybe we can write our own plugin to do all of it which will better from a DX view.

Babel plugin to inline constants

We should resolve and inline constants and integrate with libs like polished, color, polychrome etc.

Add ability to use JS objects for people who prefer that

Syntax highlighters for Atom

Improve class name composition

Composing classnames should ensure correct specificity so that class name towards end has higher specificity. We can increase the specificity manually to achieve this.

e.g. - compose('header__gyt654', 'title__gf63rt') might produce .title__gf63rt, .title__gf63rt.header__gyt654 and .header__gyt654 instead of .title__gf63rt and .header__gyt654

Documentation

• Syntax and API docs @satya164 (#77)
• Features, differences from CSS modules and libraries, tade-offs @satya164 (#84)
• Tips & tricks, gotchas (theming, dynamic styles) @satya164 (#84)
• Testing with jest @zamotany
• Recommended libraries and tools @satya164 (#84)
• Babel plugins @zamotany
• Configuring Webpack @zamotany
• SSR @thymikee (#77)

Implement a snapshot serialiser for Jest

It should be possible to snapshot the styles when testing the components

Babel plugin to Hoist CSS

What if we could write a CSS rule inline without having to give it a name? A Babel plugin can automatically hoist this to the program scope and give it a name.

This JavaScript:

function MyComponent() {
  return <article {...styles(css`color: blue;`)} />;
}

Gets transpiled into:

function MyComponent() {
  return <article {...styles(_article)} />;
}
var _article = css`color: blue;`;

Context: https://twitter.com/ryanflorence/status/907316693084418048

Implementation:

export default function(babel) {
  const { types: t } = babel;

  return {
    visitor: {
      Program: {
        enter(path, state) {
          state.cssRules = {};
        },
        exit(path, state) {
          Object.keys(state.cssRules).forEach(name => {
            path.node.body.push(
              t.variableDeclaration("var", [t.variableDeclarator(t.identifier(name), state.cssRules[name])])
            );
          });
        }
      },
      JSXOpeningElement(path, state) {
        path.node.attributes.forEach(attr => {
          if (t.isJSXSpreadAttribute(attr) && t.isCallExpression(attr.argument) && attr.argument.callee.name === "styles") {
            attr.argument.arguments = attr.argument.arguments.map(arg => {
              if (t.isTaggedTemplateExpression(arg) && arg.tag.name === "css") {
                const className = path.scope.generateUidIdentifier(path.node.name.name);
                state.cssRules[className.name] = arg;
                return className;
              }
              return arg;
            });
          }
        });
      }
    }
  };
}

PR and issue templates

GitHub allows for creating nice templates for PRs and Issues, which is helpful both for maintainers and contributors. Would be nice to set this up.

Support CRA or at least https://github.com/timarney/react-app-rewired

Codemods for switching from other libraries

We should have some codemods for switching from other class name based libraries like aphrodite, glamor etc.

Utilities to help with server rendering

Given some HTML and CSS, we should be able to extract the CSS that's actually used, useful for critical CSS.

We can probably use https://www.npmjs.com/package/string-extract-class-names

Deduplicate CSS rules

When the content of two rules are the same, use the same rule instead of adding duplicates:

e.g.: instead of

.header { font-size: 2rem; }

.title { font-size: 2rem; }

We should produce:

.header,
.title { font-size: 2rem; }

Better class names

We should include the variable names in the class name. We could write a babel plugin to replace const header = css with const header = css.named('header__ghg54t') which will achieve that

Minify the generated CSS

Investigate how to rebuild parent module, if requirements (child modules) have changed

This issue is connected with #45.

Related kentcdodds/babel-plugin-preval#19

Add a note in generated CSS

Just to avoid confusion for new devs coming to the project, it's useful if we append a small note to the generated file, just like Yarn does:

/* THIS IS AN AUTOGENERATED FILE BY LINARIA. DO NOT EDIT THIS FILE DIRECTLY. */

.hero_37644b71{background:#fffaf6;padding:150px 0;}
.heading_37644b71{color:#DE2D68;font-weight:700;font-size:4em;text-transform:uppercase;text-shadow:0 0 #FFEBCE,1px 1px #FFEBCE,2px 2px #FFEBCE,3px 3px #FFEBCE,4px 4px #FFEBCE,5px 5px #FFEBCE;}

Output CSS files to a single directory instead

Right now the generated CSS files pollute the project directory. It'll be nicer to have them in a single directory e.g. .linaria-cache or something

API for adding global CSS

Migrate to CircleCI 2

Rewire require statements

Currently only import statements are rewired. require calls should be rewired too. Refer #49 for details.

Export a function to dump stylesheets on server

Polyfill CSS Variables Support

API

The API for writing styles remains the same. For example:

const title = css`
  color: var(--title-color);
`;

When using this class name in a component:

function MyComponent({ color }) {
  return <h1 {...styles(title, { '--title-color': color })} />;
}

How to implement

1. Write a Babel plugin which looks for styles calls with variables and assigns an unique ID for each. Something like:

   styles(title, { __id: 'xgfs65d', '--title-color': color });

   This ID is necessary so that we can keep track of dynamic styles and avoid inserting same styles multiple times. The ID should be unique, but shouldn't change between builds. The easiest way is to hash the current file path and the sequential number in the file.
2. We will need to generate an AST from the CSS string. We can probably use the ast plugin for stylis to generate the ast, but I had a broken ast when I used nested media queries. We will probably need to fix the plugin. We will also need to write a simple serializer which takes the AST and serializes it to plain CSS string.
3. The css tagged template literal should parse the CSS string to an AST to determine if there are CSS variables in the string. It should generate 2 different CSS strings, one with properties using variables, and one without. The one without is inserted normally to the sheet API, but the ones with variables is returned as a templates. It's an array because there can be multiple rules. The returned object from css can look like following:

   { toString() { return 'xgsf64f'; }, templates: ['.xgsf64f { color: var(--title-color); }'] }

   Something to keep in mind is that if a property is redeclared after a variable use, we should discard the one with variable, i.e. color: var(--title-color); color: blue should be considered as color: blue.
4. The names function should be updated to look for these objects and use toString when necessary
5. The styles function should look for templates and do a search replace in them with the value of the variables, then insert it to the CSSOM with the insertRule API. If CSS custom properties are supported in the browser, it should avoid the search replace and use inline styles to set the variable values.
6. The babel presets should be separated to client and server presets, where the server preset excludes the preval-extract extract plugin and includes a plugin which just converts css to css.named calls.
7. Server rendering APIs and instructions should be updated to read the stylesheet from the string in memory instead of from a file.
8. This should be configurable in the Babel preset options. If the polyfill behaviour is disabled, templates shouldn't be generated and inline styles should be used to set the variables instead.

Advantages

1. A consistent prop-based way to use dynamic styles with components
2. Variables don't cascade anymore, and results are more predictable
3. No overhead for browsers which already support CSS variables

Disadvantages

1. Some overhead for browsers which don't support CSS variables

Clear requirements in modules cache between transpilations

Updating external variables (e.g. theme colors) has no effect in produced CSS.

// theme.js
export default {
  text: 'black';
}

// App.js
import theme from '../styles/theme';

const navLink = css`
  color: ${theme.text}; 
`;

cc @zamotany

Setup SSR example on the website

Setup example with css extraction

Setup CI and testing

• circle CI
• build process
• testing

API for theming

Babel plugin to extract style sheets to a separate file

All the CSS code that can be statically determined should be extracted to a separate CSS file to reduce parsing time of JavaScript and faster loading time by parallel loading of the styles.

Export babel plugins

We need to export 2 different babel plugins:

linaria/classnames - should transform css to css.named with the variable name. this is useful for development where we would like to have better class names, this is also useful for server rendering
linaria/extract-css - should inline the constants etc. with preval and extract the CSS files

Webpack integration

We should be able to use Webpack's HTML plugin to inject generated stylesheet into the HTML file, probably using css-loader and style-loader. This probably works already, but needs to be tested and documented.

Ensure we throw nice errors when users do something unsupported

Using undefined variables

Handled in #81

Errors thrown during preval

Handled in #111

If a function throws an error during preval, we should catch it and throw nice error with proper stacktrace.

const test = () => {
  throw new Error('Some weird error');
}

const test = css`
  color: ${test()};
`;

Typos in CSS

If the user mistyped a variable name, we could print an error instead of generating invalid CSS. For example, say we get undefined during interpolation:

const colors = {
  blue: 'blue'
}

cont title = css`
  color: ${colors.bleu};
`

Verify hashes are unique

We need to ensure that the short hash module never produces same hash for different CSS text. Probably better to vendor this module (it's tiny) or look at other CSS in JS libs' implementation and copy them.

Support dynamic properties in CSS

We'll need some runtime for this, so not exactly zero-runtime anymore.

Redundant CSS in webpack HMR

I started to work on website (using Next.js) and this is what I'm hitting in HMR:

There's a bunch duplicated css in every hot update. Wonder if we can do something about it? Not a HMR ninja unfortunately :<

cc @zamotany

Spread syntax for styles

This is a proposal for a possible syntax for styles

advantages of spread syntax

• less typing
• less noise
• same syntax can be used on a different platform like RN

disadvantages

• not obvious how to pass styles from a parent component

Example App link broken on the website

Do you want to request a feature or report a bug?
Bug (with website)

Currently at the bottom of the website in the Docs and Examples section, the link to an example app is broken, it points to https://github.com/callstack-io/linaria/tree/master/example.

Release blog post

Don't include parser in the bundle

Since we pre-evaluate all css code during build time, we don't need to include the css tag and the CSS parser in the bundle. To reduce the bundle size, we can:

• Rewrite the import for css with a function that throws an error
• Rewrite the import for include with a function that throws an error
• Rewrite imports like import { names } from 'linaria' to import names from 'linaria/build/names'

Setup E2E test with the example app

Investigate source maps for extracted styles