Quick Start

Initialize Proto UI and install components into your project

:::caution[Pre-release Stage] Proto UI is in its early public stage. This page describes the current onboarding path. Command behavior or generated file structure may still change before the v0 launch. :::

You can use the Proto UI CLI directly with npx. There is no need to install it globally in advance.

npx @proto.ui/cli --help

Run this in your project root:

npx @proto.ui/cli 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.

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 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 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 { Button } from '../proto-ui/components/react';

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

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 add react shadcn-toggle
npx @proto.ui/cli add react shadcn-dialog

Then keep using them from the same host entry:

import { Button, DialogRoot, Toggle } from '../proto-ui/components/react';

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

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

React components are exported from the React host entry:

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

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

import { ButtonElement } 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