react-preview

A command-line tool for generating previews of React components in a React project.

Purpose

This tool is intended to help develop a particular React component without needing to manually modify existing React files.

This was inspired by the SwiftUI preview tool available in XCode for previewing SwiftUI components.

Notes

This is currently only supported and tested on React projects created via create-react-app and TypeScript. This is still a work in progress with many details missing.

How it works

react-preview takes a preview file and creates a index.tsx file according to the specifications of the preview file. This file overwrites the current React project's src/index.tsx file. The original content of that file is saved inside a preview/temp directory under the filename <time>.tsx, where <time> == Date.now() at the time react-preview was executed.

With the index.tsx file written, react-preview runs npm run start, which if auto-generated by create-react-app, will cause react-scripts to be run and launch the React app. When the React project is stopped by hitting Ctrl+C, or some other process that interrupts it, the original content of index.tsx is written back.

Local Setup

Clone or download the repository. Open the project directory in a terminal and execute the following command:

# If you have yarn (preferred)
yarn run setup

# If you have npm only,
npm run setup-npm

After running the above command with no errors, you will be able to use the react-preview in any directory.

Usage

Begin by opening a React project. Create a preview environment by running react-preview init. This will create a preview directory, used hold data for react-preview, e.g. file contents.

Basic Usage

Create a preview.yaml file in the directory that contains a React component file. The preview.yaml file instructs react-preview how to load a preview of the component. The following shows a typical file setup where react-preview may be used:

// src/Components/MyComponent.tsx
export default function MyComponent() {
    return <div>
        <h1>Hello World</h1>
    </div>
}

# src/Components/preview.yaml
source: MyComponent.tsx

In the preview.yaml file, the value of the source key is the React component file to preview. The value may be an absolute path or a relative path to that file.

With this setup prepared, we can start the preview by running react-preview run <path to preview.yaml file>, which will set up the preview mode for that component. Alternatively, you could also start the preview by using just the directory path that contains the preview.yaml file; react-preview would simply look for preview.yaml file inside that directory.

Props

react-preview supports creating props by using the props field in the preview.yaml file. Suppose we had a React component that uses props, then it can be previewed via the following set of files.

// src/Components/MessageBox.tsx
export default function MessageBox(props: {
    message: string;
}) {
    return <div>
        <h1>{props.message}</h1>
    </div>
}

# src/Components/preview.yaml
source: MessageBox.tsx

props:
  message: Hello World

The preview props supports the standard values supported by YAML, e.g. strings, integers, floats, booleans, arrays, null, and objects. The preview prop also supports functions by declaring an object with type: function in the preview.yaml file. For a practical example, consider the following file set up:

// src/Components/ActionButton.tsx
export default function ActionButton(props: {
    action(): void;
}) {
    return <div onClick={props.action}>
        This is a clickable region.
    </div>
}

# src/Components/preview.yaml
source: ActionButton.tsx

props:
  action:
    type: function
    value: "() => alert('You clicked me!')"

Another way to represent functions is to use the specs field instead of value. With specs, you can define a function in terms of its function arguments, return values, and function body in between. Then, the function value can be alternatively declared as the following:

# src/Components/preview.yaml
source: ActionButton.tsx

props:
  action:
    type: function
    specs:
      body: "alert('You clicked me!')"

Re-compilation

While the preview is running, you can make changes to the preview file. Changing the preview file will make react-preview attempt to update the changes accordingly.

anthonyyangdev / react-preview