<p align="center"> <img src="./goober_cover.png" width="500" alt="goober" /> </p>

🥜 goober, a less than 1KB css-in-js solution.

🪒 The Great Shave Off Challenge

Can you shave off bytes from goober? Do it and you're gonna get paid! More info here

Motivation

I've always wondered if you could get a working solution for css-in-js with a smaller footprint. While I was working on a side project I wanted to use styled-components, or more accurately the styled pattern. Looking at the JavaScript bundle sizes, I quickly realized that I would have to include ~12kB(styled-components) or ~11kB(emotion) just so I can use the styled paradigm. So, I embarked on a mission to create a smaller alternative for these well established APIs.

Why the peanuts emoji?

It's a pun on the tagline.

css-in-js at the cost of peanuts! 🥜goober

Talks and Podcasts

• React Round Up 👉 https://reactroundup.com/wrangle-your-css-in-js-for-peanuts-using-goober-ft-cristian-bote-rru-177
• ReactDay Berlin 2019 👉 https://www.youtube.com/watch?v=k4-AVy3acqk
• PodRocket by LogRocket 👉 https://podrocket.logrocket.com/goober
• ngParty 👉 https://www.youtube.com/watch?v=XKFvOBDPeB0

Table of contents

• Usage
• Examples
• Tradeoffs
• SSR
• Benchmarks
  • Browser
  • SSR
• API
  • styled
  • setup
    • With prefixer
    • With theme
    • With forwardProps
  • css
  • targets
  • extractCss
  • createGlobalStyles
  • keyframes
  • shouldForwardProp
• Integrations
  • Babel Plugin
  • Babel Macro Plugin
  • Next.js
  • Gatsby
  • Preact CLI Plugin
  • CSS Prop
• Features
  • Sharing Style
  • Autoprefixer
  • TypeScript
  • Content Security Policy (CSP)-
• Browser Support
• Contributing

Usage

The API is inspired by emotion styled function. Meaning, you call it with your tagName, and it returns a vDOM component for that tag. Note, setup needs to be ran before the styled function is used.

import { h } from 'preact';
import { styled, setup } from 'goober';

// Should be called here, and just once
setup(h);

const Icon = styled('span')`
    display: flex;
    flex: 1;
    color: red;
`;

const Button = styled('button')`
    background: dodgerblue;
    color: white;
    border: ${Math.random()}px solid white;

    &:focus,
    &:hover {
        padding: 1em;
    }

    .otherClass {
        margin: 0;
    }

    ${Icon} {
        color: black;
    }
`;

Examples

• Vanilla
• React
• Preact
• SSR with Preact
• Fre

Comparison and tradeoffs

In this section I would like to compare goober, as objectively as I can, with the latest versions of two most well known css-in-js packages: styled-components and emotion.

I've used the following markers to reflect the state of each feature:

• ✅ Supported
• 🟡 Partially supported
• 🛑 Not supported

Here we go:

| Feature name | Goober | Styled Components | Emotion | | ---------------------- | ------- | ----------------- | ------- | | Base bundle size | 1.25 kB | 12.6 kB | 7.4 kB | | Framework agnostic | ✅ | 🛑 | ✅ *3 | | Render with target *1 | ✅ | 🛑 | 🛑 | | css api | ✅ | ✅ | ✅ | | css prop | ✅ | ✅ | ✅ | | styled | ✅ | ✅ | ✅ | | styled.<tag> | ✅ *2 | ✅ | ✅ | | default export | 🛑 | ✅ | ✅ | | as | ✅ | ✅ | ✅ | | .withComponent | 🛑 | ✅ | ✅ | | .attrs | 🛑 | ✅ | 🛑 | | shouldForwardProp | ✅ | ✅ | ✅ | | keyframes | ✅ | ✅ | ✅ | | Labels | 🛑 | 🛑 | ✅ | | ClassNames | 🛑 | 🛑 | ✅ | | Global styles | ✅ | ✅ | ✅ | | SSR | ✅ | ✅ | ✅ | | Theming | ✅ | ✅ | ✅ | | Tagged Templates | ✅ | ✅ | ✅ | | Object styles | ✅ | ✅ | ✅ | | Dynamic styles | ✅ | ✅ | ✅ |

Footnotes

• [1] goober can render in any dom target. Meaning you can use goober to define scoped styles in any context. Really useful for web-components.
• [2] Supported only via babel-plugin-transform-goober
• [3] Emotion has a framework-agnostic css function. See https://emotion.sh/docs/@emotion/css

SSR

You can get the critical CSS for SSR via extractCss. Take a look at this example: CodeSandbox: SSR with Preact and goober and read the full explanation for extractCSS and targets below.

Benchmarks

The results are included inside the build output as well.

Browser

Coming soon!

SSR

The benchmark is testing the following scenario:

import styled from '<packageName>';

// Create the dynamic styled component
const Foo = styled('div')((props) => ({
    opacity: props.counter > 0.5 ? 1 : 0,
    '@media (min-width: 1px)': {
        rule: 'all'
    },
    '&:hover': {
        another: 1,
        display: 'space'
    }
}));

// Serialize the component
renderToString(<Foo counter={Math.random()} />);

The results are:

goober x 200,437 ops/sec ±1.93% (87 runs sampled)
styled-components@5.2.1 x 12,650 ops/sec ±9.09% (48 runs sampled)
emotion@11.0.0 x 104,229 ops/sec ±2.06% (88 runs sampled)

Fastest is: goober

API

As you can see, goober supports most of the CSS syntax. If you find any issues, please submit a ticket, or open a PR with a fix.

styled(tagName: String | Function, forwardRef?: Function)

• @param {String|Function} tagName The name of the DOM element you'd like the styles to be applied to
• @param {Function} forwardRef Forward ref function. Usually React.forwardRef
• @returns {Function} Returns the tag template function.

import { styled } from 'goober';

const Btn = styled('button')`
    border-radius: 4px;
`;

Different ways of customizing the styles

Tagged templates functions

import { styled } from 'goober';

const Btn = styled('button')`
    border-radius: ${(props) => props.size}px;
`;

<Btn size={20} />;

Function that returns a string

import { styled } from 'goober';

const Btn = styled('button')(
    (props) => `
  border-radius: ${props.size}px;
`
);

<Btn size={20} />;

JSON/Object

import { styled } from 'goober';

const Btn = styled('button')((props) => ({
    borderRadius: props.size + 'px'
}));

<Btn size={20} />;

Arrays

import { styled } from 'goober';

const Btn = styled('button')([
    { color: 'tomato' },
    ({ isPrimary }) => ({ background: isPrimary ? 'cyan' : 'gray' })
]);

<Btn />; // This will render the `Button` with `background: gray;`
<Btn isPrimary />; // This will render the `Button` with `background: cyan;`

Forward ref function

As goober is JSX library agnostic, you need to pass in the forward ref function for the library you are using. Here's how you do it for React.

const Title = styled('h1', React.forwardRef)`
    font-weight: bold;
    color: dodgerblue;
`;

setup(pragma: Function, prefixer?: Function, theme?: Function, forwardProps?: Function)

The call to setup() should occur only once. It should be called in the entry file of your project.

Given the fact that react uses createElement for the transformed elements and preact uses h, setup should be cal