0.2 RC Trial

Verify the Proto UI onboarding flow with the exact 0.2.0-rc.1 release

:::caution[Prerelease trial] 0.2.0-rc.1 is now available from npm. Trial findings are not stable-version promises, and commands or generated structure may still change before 0.2.0. :::

You can use the Proto UI CLI directly with npx. There is no need to install it globally in advance. This page pins 0.2.0-rc.1 so trial results remain reproducible; the CLI pins Adapter and Prototype packages to its own exact version so historical release trains cannot be mixed in.

npx @proto.ui/cli@0.2.0-rc.1 --help

Run this in your project root:

npx @proto.ui/cli@0.2.0-rc.1 init

After initialization, a proto-ui/ folder will be created at the project root.

A typical structure looks like this:

your-project/
├── src/
├── proto-ui/
│   ├── adapters/
│   ├── prototypes/
│   ├── components/
│   │   ├── react/
│   │   │   └── index.ts
│   │   └── index.ts
│   └── config.json
├── package.json
└── ...

Where:

• config.json: project configuration read by later CLI commands
• components/: generated component entries you import from your app
• adapters/ and prototypes/: CLI-managed areas, not user-facing import surfaces

You usually do not need to maintain these files manually. The CLI manages them for you.

init generates Proto UI style preset files by default. Import the generated stylesheet once from your app entry:

import './styles/proto-ui-style.css';

Adjust the relative path if your app entry is not next to src/styles.

The generated Shadcn theme follows the system prefers-color-scheme when the application has not declared a theme. If the application manages its own theme, set data-theme="light" / data-theme="dark" on the root element, or use the compatible .light / .dark classes. An explicit theme overrides the system preference.

Once initialization is done, you can install Proto UI components one component at a time.

For example, to add a shadcn-button in a React project:

npx @proto.ui/cli@0.2.0-rc.1 add react shadcn-button

This command will:

1. Detect the host adapter you selected (react)
2. Check that the React runtime exists in your project
3. Install the corresponding adapter and prototype packages
4. Assemble everything locally
5. Generate a component entry point that your current project can use directly

If you want to inspect what will be generated without letting the CLI install dependencies, run:

npx @proto.ui/cli@0.2.0-rc.1 add react shadcn-button --no-install

This prints the Proto UI packages you still need to install and still generates the local component entry.

After installation, import the component from the generated host entry:

import { ShadcnButton } from '../proto-ui/components/react';

export function Demo() {
  return <ShadcnButton>Click me</ShadcnButton>;
}

The generated component preserves the Prototype’s declared props, event listeners, and ref/expose surface. In a TypeScript project, supported values such as variant="outline" receive completion while invalid variants and unknown props are rejected by the type checker.

The relative import is intentional. Projects do not share the same path aliases or directory depth, so the CLI does not assume that a bare specifier such as proto-ui/components is already configured.

Proto UI is adopted one component at a time.

You can continue with commands like:

npx @proto.ui/cli@0.2.0-rc.1 add react shadcn-toggle
npx @proto.ui/cli@0.2.0-rc.1 add react shadcn-dialog

Then keep using them from the same host entry:

import { ShadcnButton, ShadcnDialogRoot, ShadcnToggle } from '../proto-ui/components/react';

If the same project needs both React and Web Components, add them separately:

npx @proto.ui/cli@0.2.0-rc.1 add react shadcn-button
npx @proto.ui/cli@0.2.0-rc.1 add wc shadcn-button

React components are exported from the React host entry:

import { ShadcnButton } from '../proto-ui/components/react';

Web Component constructors are exported from the Web Component host entry:

import { ShadcnButtonElement } from '../proto-ui/components/wc';

proto-ui/components/index.ts also re-exports host-prefixed or explicit names to avoid naming conflicts when multiple hosts are used in the same project.

You can use Proto UI only in new features, or replace just one or two components in an existing project.

A more common way to start is:

1. Initialize Proto UI first
2. Install the simplest component first, such as Button
3. Try it in one local page or feature
4. Then decide whether to keep expanding

The current CLI onboarding path installs official prototype packages and generates local component facades.

It does not yet write shadcn styled prototype source into your project for direct editing. That direction is already planned, but it is not part of the first v0 onboarding path.

If you want to understand the most basic model behind it:

• Go to How It Works

If you want to decide whether it is worth introducing:

• Go to Why Proto UI

If you want to learn more about its underlying principles and boundaries:

• Go to Whitepaper