The Sugarcoat CLI provides a powerful way to integrate our design system into your projects. You can choose between two installation approaches based on your needs:

• PnP (Plug-and-Play): Install components as NPM dependencies
• Custom: Copy component source code directly into your project (like shadcn/ui)

Quick Start

Get started with Sugarcoat in under 2 minutes:

1# 1. Run the interactive setup wizard
2npx @sugarcoat/cli setup
3
4# 2. Start using components
5import { Button, Card } from '@/sugarcoat/ui'
6
7# 3. Add more components as needed
8npx @sugarcoat/cli add select input accordion
9

The setup wizard will detect your project type and guide you through the optimal configuration.

Installation

Install the Sugarcoat CLI globally or use it with npx:

1# Install globally
2npm install -g @sugarcoat/cli
3
4# Or use with npx (recommended)
5npx @sugarcoat/cli --help
6

Commands

sugarcoat setup

🎉 New! Interactive setup wizard for Sugarcoat. This is the recommended way to get started with Sugarcoat.

1# Interactive setup wizard
2npx @sugarcoat/cli setup
3
4# Quick setup with presets
5npx @sugarcoat/cli setup --preset nextjs
6npx @sugarcoat/cli setup --preset vite
7
8# Skip prompts and use defaults
9npx @sugarcoat/cli setup --yes
10
11# Reset existing configuration
12npx @sugarcoat/cli setup --reset
13

What the setup wizard does:

• Detects your project framework (Next.js, Vite, etc.)
• Recommends the best setup mode (PnP vs Custom)
• Configures TypeScript paths automatically
• Installs required dependencies
• Sets up Panda CSS (Custom mode)
• Adds starter components
• Verifies setup with built-in diagnostics

Available presets:

• nextjs - Optimized for Next.js projects
• vite - Optimized for Vite projects
• default - Generic setup for any React project

sugarcoat init (Legacy)

Initialize Sugarcoat in your project. This command sets up the necessary configuration files and dependencies.

Note: This command is deprecated. Use sugarcoat setup instead for a better experience.

1npx @sugarcoat/cli init pnp
2

sugarcoat add

Add a component to your project. The CLI will handle dependencies and file placement automatically.

1# Add a single component
2npx @sugarcoat/cli add button
3
4# Add multiple components
5npx @sugarcoat/cli add button card input
6

What this does:

• Fetches component source code from registry
• Installs required dependencies (like @radix-ui packages)
• Resolves and installs utility files (lib, types)
• Processes import paths based on your configuration
• Updates component tracking in sugarcoat.json

sugarcoat list

List all available components in the registry.

1npx @sugarcoat/cli list
2

sugarcoat generate

Generate design system files (Custom mode only).

1# Generate all design system files
2npx @sugarcoat/cli generate all
3
4# Generate specific type
5npx @sugarcoat/cli generate tokens    # Generate design tokens
6npx @sugarcoat/cli generate css       # Generate CSS files
7

sugarcoat sync

Sync configuration files and ensure everything is up-to-date.

1npx @sugarcoat/cli sync
2

sugarcoat doctor

Run comprehensive diagnostics to check your Sugarcoat setup and identify potential issues.

1npx @sugarcoat/cli doctor
2

What this checks:

• Configuration file validity
• TypeScript path mapping
• Required dependencies
• Directory structure
• Panda CSS setup (Custom mode)
• Installed component files

Output example:

Configuration

The CLI uses a sugarcoat.json file to manage your project configuration:

1{
2  "$schema": "http://localhost:3001/schema.json",
3  "version": "0.1.0",
4  "setupType": "custom",
5  "components": ["button", "card", "input"],
6  "paths": {
7    "alias": "@/sugarcoat",
8    "base": "./src/sugarcoat",
9    "ui": "./src/sugarcoat/ui",
10    "lib": "./src/sugarcoat/lib",
11    "types": "./src/sugarcoat/types",
12    "designSystem": "./src/sugarcoat/design-system"
13  }
14}
15

Configuration Options

TypeScript Integration

The CLI automatically configures TypeScript paths in your tsconfig.json:

1{
2  "compilerOptions": {
3    "baseUrl": "./src",
4    "paths": {
5      "@/*": ["*"],
6      "@/sugarcoat/*": ["sugarcoat/*"]
7    }
8  }
9}
10

This allows you to import components using clean, consistent paths:

1import { Button, Card } from '@/sugarcoat/ui/Button'
2import { createStyleContext } from '@/sugarcoat/lib/style.context'
3import type { GenericElementProps } from '@/sugarcoat/types/general'
4

Project Structure

After initialization, your project will have this structure:

1import { Button } from '@/sugarcoat/ui/Button'
2

Troubleshooting

Common Issues

Setup problems:

• Run npx @sugarcoat/cli setup --reset to start fresh
• Use npx @sugarcoat/cli doctor to diagnose issues
• Check that you have a valid package.json in your project

Import errors after adding components:

• Run npx @sugarcoat/cli setup to reconfigure paths
• Ensure TypeScript paths are configured correctly
• Restart your TypeScript language server
• Check that sugarcoat.json paths match your project structure

Panda CSS not generating files (Custom mode):

• Verify panda.config.mjs exists and is valid
• Run npx @sugarcoat/cli generate all manually
• Check that @pandacss/dev is installed

Component styles not applying:

• Ensure CSS files are imported in your app
• Check that Panda CSS generation completed successfully
• Verify component recipes are included in your config

Getting Help

1# Run diagnostics to check your setup
2npx @sugarcoat/cli doctor
3
4# Get general help
5npx @sugarcoat/cli --help
6
7# Get help for specific commands
8npx @sugarcoat/cli setup --help
9npx @sugarcoat/cli add --help
10

Migration

From PnP to Custom

1. Run npx @sugarcoat/cli init custom in your project
2. Choose your theme colors
3. Re-add your components: npx @sugarcoat/cli add [component-list]
4. Update your imports to use the new paths
5. Remove the old @sugarcoat/design-system dependency

From Custom to PnP

1. Run npx @sugarcoat/cli init pnp in your project
2. Remove local component files from src/sugarcoat
3. Update your imports to use @sugarcoat/design-system
4. Remove Panda CSS configuration files

Examples

Quick Start (Recommended)

1# Interactive setup wizard
2npx @sugarcoat/cli setup
3
4# The wizard will guide you through:
5# - Framework detection
6# - Mode selection (PnP vs Custom)
7# - Component selection
8# - Automatic configuration
9

Framework-Specific Setup

1# Next.js optimized setup
2npx @sugarcoat/cli setup --preset nextjs
3
4# Vite optimized setup  
5npx @sugarcoat/cli setup --preset vite
6
7# Skip prompts with defaults
8npx @sugarcoat/cli setup --yes
9

Basic Setup (Legacy)

1# Initialize with custom mode
2npx @sugarcoat/cli init custom
3
4# Add core components
5npx @sugarcoat/cli add button card input select
6
7# Start using components
8

1import { Button, Card } from '@/sugarcoat/ui'
2
3export default function App() {
4  return (
5    <Card>
6      <Card.Header title="Welcome" />
7      <Card.Content>
8        Get started with Sugarcoat components
9      </Card.Content>
10      <Card.Footer>
11        <Button>Get Started</Button>
12      </Card.Footer>
13    </Card>
14  )
15}
16

Advanced Customization (Custom Mode)

1// Customize component styling
2import { Button } from '@/sugarcoat/ui'
3import { css } from '@/sugarcoat/design-system/css'
4
5export default function CustomButton() {
6  return (
7    <Button 
8      className={css({
9        bg: 'gradient-to-r from-purple-500 to-pink-500',
10        _hover: { transform: 'scale(1.05)' }
11      })}
12    >
13      Custom Styled Button
14    </Button>
15  )
16}
17

The Sugarcoat CLI makes it easy to get started with our design system while providing the flexibility to customize and extend components as your project grows.