Migration Guide

Notes#

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.

Example:

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>
    </Div>
  )
}
 
Copy

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>
    </div>
  )
}
 
Copy

Migration Guide#

1. Install dependencies

npm install reflexjs gatsby-plugin-reflexjs babel-preset-gatsby
 
Copy

2. Create a .babelrc file with the following:

{
  "presets": ["babel-preset-gatsby", "reflexjs/babel"]
}
 
Copy

3. 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`], 
}
 
Copy

4. Move your theme.js file from src/@reflexjs/gatsby-theme-base/theme.js to src/gatsby-plugin-reflexjs/index.js.

src/gatsby-plugin-reflexjs/index.js
import base from "@reflexjs/preset-base"
export default {
  preset: base,
  colors: {
    primary: `#005ae0`,
  },
}
 
Copy

5. 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
 
Copy

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

Changes#

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

2. 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>
 
Copy

3. Rename Container to <div variant="container" />.

- <Container>Hello World</Container>
+ <div variant="container">Hello World</div>
 
Copy

4. 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>
 
Copy

5. Rename d prop to display.

- <Div d="flex" />
+ <div display="flex" />
- <Span d="block" />
+ <span display="block" />
 
Copy

6. 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",
+ }} />
 
Copy

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

<div
  sx={{
    ":before": {
      content: '""',
    },
  }}
/>
 
Copy

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

2. Replace Grid with <div display="grid" />.

- <Grid col="2|4" />
+ <div display="grid" col="2|4" />
 
Copy

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