Installation & Setup

Prerequisites#

Before installing Sugarcoat, ensure you have:

• Node.js 18.0 or higher
• npm, pnpm, or yarn package manager
• An existing JavaScript/TypeScript project with package.json

Installing the CLI#

You can use the CLI directly with npx without installing it globally:

npx @sugarcoat/cli init

Or install it globally for convenience:

# npm
npm install -g @sugarcoat/cli
 
# pnpm
pnpm add -g @sugarcoat/cli
 
# yarn
yarn global add @sugarcoat/cli

Initializing a Project#

Run the init command in your project root:

sugarcoat init

The interactive setup will guide you through:

1. Brand Color - Choose your primary brand color (e.g., iris, blue, teal)
2. Accent Color - Choose a secondary accent color
3. Gray Scale - Choose your neutral gray scale (e.g., slate, gray, mauve)

Non-Interactive Setup#

Skip prompts and use defaults with the -y flag:

sugarcoat init -y

Force overwrite existing configuration:

sugarcoat init --force

Install Dependencies#

After initialization, install the required dependencies:

# npm
npm install @sugarcoat/preset @sugarcoat/core @sugarcoat/postcss @pandacss/dev
 
# pnpm
pnpm add @sugarcoat/preset @sugarcoat/core @sugarcoat/postcss @pandacss/dev
 
# yarn
yarn add @sugarcoat/preset @sugarcoat/core @sugarcoat/postcss @pandacss/dev

Generate CSS Artifacts#

Generate the CSS artifacts from your configuration:

sugarcoat codegen

This creates the following in .sugarcoat/generated/:

• CSS utility functions (css, cx, cva)
• Design tokens
• Component recipes
• Layout patterns
• styles.css with extracted styles

Configure Your Project#

1. Import Styles#

Import the generated CSS in your app's entry point:

// app/layout.tsx (Next.js) or main.tsx (Vite)
import "./.sugarcoat/generated/styles.css";

2. Update TypeScript Paths#

Add the path alias to your tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@/.sugarcoat": ["./.sugarcoat/generated"],
      "@/.sugarcoat/*": ["./.sugarcoat/generated/*"]
    }
  }
}

3. Configure PostCSS#

The init command creates a postcss.config.js. Verify it includes:

module.exports = {
  plugins: {
    "@sugarcoat/postcss": {},
    autoprefixer: {},
  },
};

Verify Your Setup#

Run the doctor command to verify everything is configured correctly:

sugarcoat doctor

This checks:

• Configuration files exist
• Dependencies are installed
• TypeScript paths are configured
• PostCSS is set up
• Generated artifacts exist

Development Workflow#

For development, run codegen in watch mode alongside your dev server:

# Terminal 1: Run codegen watch
sugarcoat dev
 
# Terminal 2: Run your dev server
npm run dev

The dev command watches for file changes and regenerates CSS automatically.

Next Steps#

• Add components from the registry
• Configure your theme in sugarcoat.config.ts
• Browse available components