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

Starting with

  1. React
  2. Fusion.js
  3. Next.js
  4. Gatsby
  5. Vanilla JS

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
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>
);

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

Register the plugin in src/main.js:

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 { styled } from "styletron-react";

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

function Home() {
  return <Colored>Welcome to Gatsby!</Colored>;
}

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.