DocumentationBlocks LibraryGuidesGitHub

Migration Guide

Migrate your legacy Gatsby site to Reflexjs.

This guide is a work in progress. If you find any issues migrating your site, create an issue on GitHub. We will help you.


The most important change to note when migrating to Reflexjs is we are moving away from custom components.

All Reflexjs style props now works with JSX: div, p, button and form instead of Div, P, Button and Form.

To help you upgrade your site, we have created a Codemod. The CodeMod will migrate your @reflexjs/components to JSX with style props.


import { Div, H1, Button } from "@reflexjs/components"
export default function () {
return (
<Div d="flex">
<H1>This is a heading</H1>
<Button variant="primary lg">Button</Button>

Will be transformed to:

export default function () {
return (
<div display="flex">
<h1 variant="heading.h1">This is a heading</h1>
<button variant="button.primary.lg">Button</button>

Migration Guide#

  1. Install dependencies
npm install reflexjs gatsby-plugin-reflexjs babel-preset-gatsby
  1. Create a .babelrc file with the following:
"presets": ["babel-preset-gatsby", "reflexjs/babel"]
  1. Add gatsby-plugin-reflexjs to gatsby-config.js
module.exports = {
siteMetadata: {
title: "Reflexjs",
description: "Starter for Reflexjs.",
siteUrl: process.env.SITE_URL || "http://localhost:8000",
plugins: [`gatsby-plugin-reflexjs`],
  1. Move your theme.js file from src/@reflexjs/gatsby-theme-base/theme.js to src/gatsby-plugin-reflexjs/index.js.
import base from "@reflexjs/preset-base"
export default {
preset: base,
colors: {
primary: `#005ae0`,
  1. We are now ready to run the codemod. You can commit your changes before proceeding.

The codemod will migrate @reflexjs/components code to JSX with style props.

Run the following command from the root of your site:

npx @reflexjs/codemod to-reflexjs

Once the upgrade is done, you can run gatsby clean && gatsby develop to re-run your Gatsby server.


The following is a list of changes for migrating to Reflexjs. The codemod should upgrade most of the components for you. If anything is not working, refer to the list below:

  1. Rename all custom components to JSX.
- <Div bg="primary">
- <P>Hello World</P>
- </Div>
+ <div bg="primary">
+ <p>Hello World</p>
+ </div>
  1. Button and headings now use variant.
- <Button variant="primary">Primary</Button>
+ <button variant="button.primary">Primary</button>
- <Button variant="secondary lg">Secondary</Button>
+ <button variant="button.secondary.lg">Secondary</button>
- <H1>Heading One</H1>
+ <h1 variant="heading.h1">Heading One</h1>
  1. Rename Container to <div variant="container" />.
- <Container>Hello World</Container>
+ <div variant="container">Hello World</div>
  1. Add variant prop to input, textarea and select.
- <Input type="text" />
+ <input variant="input" type="text" />
- <Textarea></Textarea>
+ <textarea variant="textarea"></textarea>
- <Select>
- <Option>Option One</Option>
- </Select>
+ <select variant="select">
+ <option>Option One</option>
+ </select>
  1. Rename d prop to display.
- <Div d="flex" />
+ <div display="flex" />
- <Span d="block" />
+ <span display="block" />
  1. Replace hover and focus props with _hover and _focus:
- <Button hoverBg="secondary" hoverColor="white" />
+ <button _hover={{
+ bg: "secondary",
+ color: "white",
+ }} />
- <A focusBg="secondary" />
+ <a _focus={{
+ bg: "secondary",
+ }} />

Note: only _hover and _focus pseudo classes are supported. For other classes such as :before, use the sx prop.

":before": {
content: '""',

Future-proofing your site#

Reflexjs is, essentially, a styling library. In the future, we would probably drop support for custom components such as Flex and Grid.

Here are a few (optional) changes you can make to future-proof your site.

  1. Replace Flexbox and Flex with <div display="flex" />.
- <Flexbox>Hello World</Flexbox>
+ <div display="flex" justifyContent="center">Hello World</div>
- <Flex>Hello World</Flex>
+ <div display="flex" justifyContent="center">Hello World</div>
  1. Replace Grid with <div display="grid" />.
- <Grid col="2|4" />
+ <div display="grid" col="2|4" />

Note: We will continue supporting the Icon and VisuallyHidden components.

Theme Specification

© 2021 Reflexjs

DocumentationBlocks LibraryGuidesGitHub