A monorepo containing a CLI tool and registry server for Polkadot UI components, similar to shadcn/ui but specifically designed for Web3 development. For a list of available components visit polkadot-ui.com

This project consists of two main packages:

• CLI (packages/cli) - The polkadot-ui command-line tool for installing components
• Registry (packages/registry) - Next.js server that hosts the component registry and documentation

Install Polkadot components in your project:

# List available components
npx polkadot-ui list

# Add a component to your project
npx polkadot-ui add address-input

# You can also use pnpm or bun
pnpm dlx polkadot-ui add address-input
bunx polkadot-ui add address-input

1. Clone and install dependencies:

   git clone https://github.com/Polkadot-UI-Initiative/polkadot-ui
   cd dot-ui
   pnpm install

2. Start the registry server:

   pnpm dev
   # Registry server runs at http://localhost:3000

3. Test CLI with local registry:

   cd <some_random_project>
   npm run dev -- list --dev
   npm run dev -- add address-input --dev

dot-ui/
├── packages/
│   ├── cli/                    # CLI package
│   │   ├── bin/polkadot-ui.js    # CLI executable
│   │   └── package.json       # Published to npm as "polkadot-ui"
│   └── registry/              # Registry server (@dot-ui/registry)
│       ├── app/               # Next.js app directory
│       ├── registry/          # Component definitions
│       ├── public/            # Static assets (serves registry.json)
│       └── package.json       # Registry server package
├── package.json               # Root workspace config
├── pnpm-workspace.yaml        # Workspace definition
└── README.md

Root level:

pnpm dev              # Start registry server
pnpm build            # Build all packages
pnpm build:cli        # Build CLI only
pnpm build:registry   # Build registry only

CLI development:

cd packages/cli
npm run dev -- --help          # Show CLI help
npm run dev -- list            # List from production registry
npm run dev -- list --dev      # List from localhost:3000
npm run dev -- add address-input --dev  # Install from local registry

Registry development:

cd packages/registry
pnpm dev              # Start Next.js dev server
pnpm build            # Build for production
pnpm registry:build   # Build component registry
pnpm registry:copy    # Copy registry.json to public/

1. Production: CLI fetches from https://polkadot-ui.com
2. Development: With --dev flag, CLI uses http://localhost:3000

1. CLI fetches available components from /registry.json
2. User selects a component to install
3. CLI downloads component files from /r/{component-name}.json
4. Files are written to user's project with proper imports

Components are defined in /registry/polkadot-ui/ with:

• Components: React components (.tsx files)
• Hooks: Custom hooks for Polkadot integration
• Types: TypeScript type definitions
• Providers: Context providers for chain connections

1. Create component structure:

   registry/polkadot-ui/blocks/my-component/
   ├── components/
   │   └── my-component.tsx
   ├── hooks/
   │   └── use-my-component.ts
   └── types/
       └── my-component.types.ts
   

2. Register in registry.json:

   {
     "name": "my-component",
     "type": "registry:component",
     "title": "My Component",
     "description": "Component description",
     "files": [...]
   }

   See the shadcn [registry-item-schema] for more details on how to structure files and other options. (https://ui.shadcn.com/docs/registry/registry-item-json)

3. Build and test:

   cd packages/registry
   pnpm registry:build
   pnpm registry:copy

• Use polkadot-api (papi) or dedot for chain interactions
• Follow React Server Component patterns where possible
• Include TypeScript types for all props and returns
• Provide comprehensive JSDoc documentation
• Test with multiple Polkadot chains (Polkadot, Kusama, Asset Hub, etc.)

The CLI is published to npm as polkadot-ui:

cd packages/cli
npm version patch
npm publish

The registry server is deployed to Vercel and serves:

• Component documentation at the root
• Registry API at /registry.json
• Component files at /r/{component}.json

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-component
3. Make your changes and test locally
4. Submit a pull request

To help improve the CLI experience, Dot UI collects anonymous usage telemetry by default. This data helps us understand how the CLI is being used and identify areas for improvement.

The telemetry system tracks:

• Component installation events (success/failure)
• Project initialization events
• Framework type (Next.js or Vite)
• TypeScript and Tailwind CSS usage
• Package manager used (npm, pnpm, yarn, bun)
• Operation duration (for performance improvements)
• CLI version
• Error messages (truncated to protect sensitive data)

• No personal information is collected (no usernames, project names, or file paths)
• No code or component content is transmitted
• Data is only used in aggregate to improve the CLI
• Telemetry fails silently and will never break your CLI operations

You can disable telemetry in several ways:

Environment variable (recommended):

export POLKA_UI_DISABLE_TELEMETRY=true

Per-command using dev flag:

npx polkadot-ui add button --dev

Permanently in your shell profile:

# Add to ~/.bashrc, ~/.zshrc, etc.
export POLKA_UI_DISABLE_TELEMETRY=true

Telemetry is automatically disabled when using the --dev flag for local development.

MIT License - see LICENSE file for details.