Installation

yarcl needs React 19 or newer. Its build plugin supports Vite, webpack, Rspack, Rollup and esbuild.

Automatic setup

Run the setup command from an existing React project:

pnpm

pnpm dlx @yarcl/react init

npm

npx @yarcl/react init

yarn

yarn dlx @yarcl/react init

bun

bunx @yarcl/react init

This installs @yarcl/react, detects and adds the matching build plugin, updates tsconfig.app.json or tsconfig.json, and creates src/yarcl.config.ts. Existing JSON comments and unrelated settings are preserved. Run the command again to verify or repair the setup.

Use --config <path> to choose a different config file, --bundler <name> when a project has more than one build config, or --skip-install to update the project without running its package manager.

Manual setup

1. Install the package.

   pnpm

   pnpm add @yarcl/react

   npm

   npm install @yarcl/react

   yarn

   yarn add @yarcl/react

   bun

   bun add @yarcl/react

2. Add the plugin for your build tool. It points the library at your config and generates the CSS.

   Vite

   vite.config.ts

   import react from '@vitejs/plugin-react';
   import { defineConfig } from 'vite';
   import yarcl from '@yarcl/react/vite';
   
   export default defineConfig({
     plugins: [react(), yarcl({ config: 'src/yarcl.config.ts' })],
   });

   webpack

   webpack.config.js

   const yarcl = require('@yarcl/react/webpack');
   
   module.exports = {
     plugins: [yarcl({ config: 'src/yarcl.config.ts' })],
   };

   Rspack

   rspack.config.ts

   import yarcl from '@yarcl/react/rspack';
   
   export default {
     plugins: [yarcl({ config: 'src/yarcl.config.ts' })],
   };

   Rollup

   rollup.config.ts

   import yarcl from '@yarcl/react/rollup';
   
   export default {
     plugins: [yarcl({ config: 'src/yarcl.config.ts' })],
   };

   esbuild

   esbuild.config.ts

   import { build } from 'esbuild';
   import yarcl from '@yarcl/react/esbuild';
   
   await build({
     plugins: [yarcl({ config: 'src/yarcl.config.ts' })],
   });

3. Point TypeScript at the same file, so the prop types come from your config.

   tsconfig.json

   {
     "compilerOptions": {
       "moduleResolution": "bundler",
       "paths": {
         "@yarcl/config": [
           "./src/yarcl.config.ts",
           "./node_modules/@yarcl/react/dist/yarcl.config.d.ts"
         ]
       }
     }
   }

   The second entry is a fallback: if your config file doesn’t exist, the types come from the library defaults. The plugin falls back the same way at runtime.

4. Create your config. Start from the library defaults and change what you need.

   src/yarcl.config.ts

   import { defineConfig } from '@yarcl/react/define';
   import defaults from '@yarcl/react/defaults';
   
   export default defineConfig({
     ...defaults,
     colors: {
       ...defaults.colors,
       brand: { light: '#2d4bb8', dark: '#8aa2ff' },
     },
     defaults: { ...defaults.defaults, color: 'brand' },
   });

5. Use the components. Importing from @yarcl/react also loads the generated CSS.

   src/App.tsx

   import { Button } from '@yarcl/react';
   
   export function App() {
     return <Button color="brand">It works</Button>;
   }

Page styles

Add yarcl-root to your body to let the design system style the page:

index.html

<body class="yarcl-root">
  <div id="root"></div>
</body>

For a section of an existing application, put it on that section instead:

<div className="yarcl-root">
  <App />
</div>

The class uses neutrals.bg for the background, neutrals.text for text, and typography.fonts.body for the font family. Font size, weight, line height and letter spacing follow the style named by defaults.textStyle. This supports your own style keys, such as copy, and does not depend on a style named body.

applyTheme updates these styles along with the components. The class inherits color-scheme: the generated tokens follow the operating system by default, and a mode forced on an ancestor continues to apply. To force a mode just for this section:

<div className="yarcl-root" style={{ colorScheme: 'dark' }}>
  <App />
</div>

Page styles are opt in. Without yarcl-root, your page keeps its own background and typography. Use your own CSS for layout, margins and viewport height, or to override the page defaults.

Keep both mappings in sync

The build plugin and the TypeScript paths entry must point at the same file. The plugin stops with a clear error if they differ. Re-run the setup command to repair the mapping, or see Build plugins for details.