This guide explains how to use a React design system starter powered by:
As well as a few others tools preconfigured:
Run the following command:
npx create-turbo@latest -e design-system
pnpm build
- Build all packages, including the Storybook sitepnpm dev
- Run all packages locally and preview with Storybookpnpm lint
- Lint all packagespnpm changeset
- Generate a changesetpnpm clean
- Clean up all node_modules
and dist
folders (runs each package's clean script)Turborepo is a high-performance build system for JavaScript and TypeScript codebases. It was designed after the workflows used by massive software engineering organizations to ship code at scale. Turborepo abstracts the complex configuration needed for monorepos and provides fast, incremental builds with zero-configuration remote caching.
Using Turborepo simplifies managing your design system monorepo, as you can have a single lint, build, test, and release process for all packages. Learn more about how monorepos improve your development workflow.
This Turborepo includes the following packages and applications:
apps/docs
: Component documentation site with Storybookpackages/ui
: Core React componentspackages/utils
: Shared React utilitiespackages/typescript-config
: Shared tsconfig.json
s used throughout the Turborepopackages/eslint-config
: ESLint presetEach package and app is 100% TypeScript. Workspaces enables us to "hoist" dependencies that are shared between packages to the root package.json
. This means smaller node_modules
folders and a better local dev experience. To install a dependency for the entire monorepo, use the -w
workspaces flag with pnpm add
.
This example sets up your .gitignore
to exclude all generated files, other folders like node_modules
used to store your dependencies.
To make the core library code work across all browsers, we need to compile the raw TypeScript and React code to plain JavaScript. We can accomplish this with tsup
, which uses esbuild
to greatly improve performance.
Running pnpm build
from the root of the Turborepo will run the build
command defined in each package's package.json
file. Turborepo runs each build
in parallel and caches & hashes the output to speed up future builds.
For acme-core
, the build
command is the following:
tsup src/index.tsx --format esm,cjs --dts --external react
tsup
compiles src/index.tsx
, which exports all of the components in the design system, into both ES Modules and CommonJS formats as well as their TypeScript types. The package.json
for acme-core
then instructs the consumer to select the correct format:
{
"name": "@acme/core",
"version": "0.0.0",
"main": "./dist/index.js",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"sideEffects": false,
}
Run pnpm build
to confirm compilation is working correctly. You should see a folder acme-core/dist
which contains the compiled output.
acme-core
└── dist
├── index.d.ts <-- Types
├── index.js <-- CommonJS version
└── index.mjs <-- ES Modules version
Each file inside of acme-core/src
is a component inside our design system. For example:
import * as React from 'react';
export interface ButtonProps {
children: React.ReactNode;
}
export function Button(props: ButtonProps) {
return <button>{props.children}</button>;
}
Button.displayName = 'Button';
When adding a new file, ensure the component is also exported from the entry index.tsx
file:
import * as React from "react";
export { Button, type ButtonProps } from "./Button";
// Add new component exports here
Storybook provides us with an interactive UI playground for our components. This allows us to preview our components in the browser and instantly see changes when developing locally. This example preconfigures Storybook to:
stories/
folder@acme-core
for importsFor example, here's the included Story for our Button
component:
import { Button } from '@acme-core/src';
import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
<Meta title="Components/Button" component={Button} />
# Button
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec euismod, nisl eget consectetur tempor, nisl nunc egestas nisi, euismod aliquam nisl nunc euismod.
## Props
<Props of={Box} />
## Examples
<Preview>
<Story name="Default">
<Button>Hello</Button>
</Story>
</Preview>
This example includes a few helpful Storybook scripts:
pnpm dev
: Starts Storybook in dev mode with hot reloading at localhost:6006
pnpm build
: Builds the Storybook UI and generates the static HTML filespnpm preview-storybook
: Starts a local server to view the generated Storybook UIThis example uses Changesets to manage versions, create changelogs, and publish to npm. It's preconfigured so you can start publishing packages immediately.
You'll need to create an NPM_TOKEN
and GITHUB_TOKEN
and add it to your GitHub repository settings to enable access to npm. It's also worth installing the Changesets bot on your repository.
To generate your changelog, run pnpm changeset
locally:
space
to select the packages you want to include in the changeset
.space
to select the packages you want to bump versions for.changeset
folder with the summary and a list of the packages included.When you push your code to GitHub, the GitHub Action will run the release
script defined in the root package.json
:
turbo run build --filter=docs^... && changeset publish
Turborepo runs the build
script for all publishable packages (excluding docs) and publishes the packages to npm. By default, this example includes acme
as the npm organization. To change this, do the following:
packages/*
to replace acme
with your desired scopeacme
with your desired scopepnpm install
To publish packages to a private npm organization scope, remove the following from each of the package.json
's
- "publishConfig": {
- "access": "public"
- },
meaningless change to test