Skip to content

Latest commit



100 lines (66 loc) · 3.58 KB

File metadata and controls

100 lines (66 loc) · 3.58 KB

Styletron v3 to v4 Migration Guide

Automated codemods

For convenience, there are automated codemod scripts for migrating:

npm i --no-package-lock --no-save styletron-codemods
npx babel-codemod --plugin styletron-codemods/transform-styled-composition src/**/**.js
npx babel-codemod --plugin styletron-codemods/transform-provider src/**/**.js
npx babel-codemod --plugin styletron-codemods/transform-styletron-client src/**/**.js
npx babel-codemod --plugin styletron-codemods/transform-styletron-server src/**/**.js

Replacing browser and server Styletron instances

The atomic rendering engine is now in a single package instead of being split into server/client packages. This both ensures that versions of coupled server and client code are in sync and opens the door for different rendering engines.

Updating client-side instance

The constructor has been changed to a single argument to match the server-side interface and making it easier to provide configuration without hydration.

- import StyletronClient from "styletron-client";
+ import {Client as StyletronClient} from "styletron-engine-atomic";

const ssrStyles = document.getElementsByClassName('_styletron_hydrate');

- const instance = new StyletronClient(ssrStyles, {prefix: '_'});
+ const instance = new StyletronClient({hydrate: ssrStyles, prefix: '_'});

Updating server-side instance

- import StyletronServer from "styletron-server";
+ import {Server as StyletronServer} from "styletron-engine-atomic";

const instance = new StyletronServer({prefix: '_'});

Updating the Styletron provider

The Styletron provider has been updated to match the new React 16 context API.

- import {StyletronProvider} from "styletron-react";
+ import {Provider as StyletronProvider} from "styletron-react";

const app = (
-  <StyletronProvider styletron={instance}>
+  <StyletronProvider value={instance}>
    <App />

Updating styled components

The API for styled components is largely the same, but with a few minor changes.

innerRef to $ref

- <MyStyledComponent innerRef="someStringRef" />;
+ <MyStyledComponent $ref="someStringRef" />;

$-prefixed props

To avoid warnings regarding unknown props, with styletron-react v3, props used for styling only could be namespaced under props.styleProps, which would automatically get removed. Unfortunately, this makes using these props in JSX much less convenient. Styletron v4 has a new convention where any props starting with a dollar sign ($) will never be passed through. So for any styling-only props, you can simply use a $ prefix.

const Foo = styled("div", props => ({
-  color: props.styleProps.danger ? "red" : "blue"
+  color: props.$danger ? "red" : "blue"

- <Foo styleProps={{danger: true}} />;
+ <Foo $danger />;

Composing styled components

Before, styled components could be composed with one another using the base styled function. Styletron v4 provivdes multiple, explicit composition HOCs including withStyle (equivalent to the old shallow merge behavior of styled), withStyleDeep, and withTransform.

Now there is no ambiguity with styled whether it is composition from an existing styled component or a new styled component is being created based on a regular component.

- import {styled} from "styletron-react";
+ import {styled, withStyle} from "styletron-react";

const Foo = styled("div", {color: "red"});

- const Bar = styled(Foo, {background: "green"});
+ const Bar = withStyle(Foo, {background: "green"});