Getting Started

Styletron is distributed through npmjs.com. It consists of a few packages. The basic React setup requires adding two of them:

yarn add styletron-engine-atomic styletron-react

Packages

styletron-engine-atomic

This package is all you need to start with Styletron. It is an implementation of the styletron-standard engine interface.

styletron-react

This package provides additional React bindings so you can easily create styled React components.

This package is an alternative implementation of the styletron-standard engine interface. The monolithic engine is a superset of the atomic engine - everything that works in the atomic engine will keep working with the monolithic engine. In comparison with the atomic engine:

class names are stable (hashes) in the monolithic engine, so components can be cross-referenced,
using the monolithic engine, you can mix longhand and shorthand properties,
media queries are not sorted, since the order is always respected,
it supports @supports.

These improvements are made possible by sacrificing the minimal CSS footprint the atomic engine strives for.

Types

Styletron is Flow typed by default. Do you use TypeScript?

yarn add @types/styletron-standard
yarn add @types/styletron-react
yarn add @types/styletron-engine-atomic

# we do not have typescript definitions for the monolithic engine yet
# are you interested in adding them?
# let us know at https://github.com/styletron/styletron/issues

With React

If you are using create-react-app, this is the section that applies to your application.

You need to wrap your application root with the StyletronProvider and pass an instance of Styletron into it. React context is used in the background to ensure that CSS rules are properly extracted and CSS classes created.

import { Provider as StyletronProvider, DebugEngine } from "styletron-react";
import { Client as Styletron } from "styletron-engine-atomic";

const debug =
  process.env.NODE_ENV === "production" ? void 0 : new DebugEngine();

// 1. Create a client engine instance
const engine = new Styletron();

// 2. Provide the engine to the app
// debug engine needs inlined source maps
React.render(
  <StyletronProvider value={engine} debug={debug} debugAfterHydration>
    <App />
  </StyletronProvider>
);

Server-side Rendering

Styletron also supports server-side rendering so you can generate the styles on the server and then "hydrate" the client. This can significantly improve the loading time of your application!

Extracting Server-rendered Styles

import { Provider as StyletronProvider } from "styletron-react";
import { Server as Styletron } from "styletron-engine-atomic";

// 1. Create a server engine instance
const engine = new Styletron();

// 2. Provide the engine to the app
const html = React.render(
  <StyletronProvider value={engine}>
    <App />
  </StyletronProvider>
);

// 3. Extract critical styles after SSR
const styles = engine.getStylesheetsHtml();
// → "<style ..."

Hydrating Server-rendered Styles

import {Provider as StyletronProvider} from "styletron-react";
import {Client as Styletron} from "styletron-engine-atomic";

- const engine = new Styletron();
+ const engine = new Styletron({
+  hydrate: document.getElementsByClassName("_styletron_hydrate_")
+ });

React.render(
  <StyletronProvider value={engine}>
    <App/>
  </StyletronProvider>
);

Using the monolithic engine

The setup is the same as with the atomic engine - the only difference is that we have to replace styletron-engine-atomic with styletron-engine-monolithic.

Add `styletron-engine-monolithic` as a dependency

yarn add styletron-engine-monolithic styletron-react

Add `styletron-engine-monolithic` to your project

import { Provider as StyletronProvider, DebugEngine } from "styletron-react";
import { Client as Styletron } from "styletron-engine-monolithic";

const debug =
  process.env.NODE_ENV === "production" ? void 0 : new DebugEngine();

// 1. Create a client engine instance
const engine = new Styletron();

// 2. Provide the engine to the app
// debug engine needs inlined source maps
React.render(
  <StyletronProvider value={engine} debug={debug} debugAfterHydration>
    <App />
  </StyletronProvider>
);

With Fusion.js

Fusion.js is a plugin-based universal web framework. Your application might already support Styletron out of the box! Check if fusion-plugin-styletron-react has been installed. If not, run

yarn add fusion-plugin-styletron-react styletron-react

import App from "fusion-react";
import Styletron from "fusion-plugin-styletron-react";
import root from "./components/root";

export default () => {
  const app = new App(root);
  app.register(Styletron);
  return app;
};

Then you can directly import and use styled function. src/root.js:

import { styled } from "fusion-plugin-styletron-react";

const Colored = styled("div", { color: "blue" });

function Home() {
  return <Colored>Welcome to Fusion.js!</Colored>;
}

export default Home;

With Next.js

Next.js is a popular React framework. There is an example Next.js + Styletron app. You can bootstrap a new project by:

yarn create next-app --example with-styletron with-styletron-app

Run the app:

yarn
yarn dev

With Gatsby

Gatsby is a fast modern site generator for React. There is a gatsby-plugin-styletron. First, add it to your Gatsby app:

yarn add gatsby-plugin-styletron

and edit gatsby-config.js:

module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-styletron",
      options: {
        // You can pass options to Styletron.
        // Prefix all generated classNames:
        prefix: "_",
      },
    },
  ],
};

That's it! Now you should be able to style your components and the styles should be server-side rendered (in production build). src/pages/index.js:

import React from "react";
import { useStyletron } from "styletron-react";

function Home() {
  const [css] = useStyletron();
  return (
    <div
      className={css({
        color: "blue",
      })}
    >
      Welcome to Gatsby!
    </div>
  );
}

export default Home;

With JavaScript

Do you use some other framework? Or no framework at all? You can directly use styletron-engine-atomic to render styles. Check the API documentation.

← Home Use with React →