create-brightsy-component-lib

CLI tool to scaffold and deploy Brightsy component library projects.

Installation

# Use directly with npx (recommended)
npx create-brightsy-component-lib

# Or install globally
npm install -g create-brightsy-component-lib

# Or install locally in a project
npm install --save-dev create-brightsy-component-lib

Usage

Create a Project

# Create a new component library
npx create-brightsy-component-lib my-components

# Create a custom application
npx create-brightsy-component-lib my-app --template app

Authentication

The CLI uses OAuth for secure authentication (no API keys needed):

# Login - opens browser for OAuth flow
npx create-brightsy-component-lib login

# Check who you're logged in as
npx create-brightsy-component-lib whoami

# Logout
npx create-brightsy-component-lib logout

Credentials are stored securely in ~/.brightsy/config.json with restricted permissions.

Deploy to Brightsy

# Deploy (will prompt for login if needed)
npx create-brightsy-component-lib deploy

# Deploy with options
npx create-brightsy-component-lib deploy \
  --env-name production \
  --version 1.0.0

# Deploy and register with existing library
npx create-brightsy-component-lib deploy \
  --lib-id your-library-uuid \
  --env-name production

Commands

login

Authenticate with Brightsy using OAuth 2.1 with PKCE:

• Opens your browser for secure login
• Stores tokens locally
• Supports multiple accounts (prompts if you have more than one)

logout

Remove stored credentials.

whoami

Show current authenticated account and token status.

deploy

Deploy the library:

1. Builds the library (if not already built)
2. Uploads to Brightsy file storage
3. Optionally registers the environment with a library

| Option | Description | Default | |--------|-------------|---------| | -e, --endpoint | API endpoint | https://brightsy.ai | | -l, --lib-id | Library ID to register environment | (optional) | | -n, --env-name | Environment name | production | | -v, --version | Version to deploy | From package.json |

Deployment Flow

Login (OAuth - one time)
    ↓
Build library (npm run build)
    ↓
Upload to Brightsy Files (libs/{name}/{version}/index.js)
    ↓
Get public URL (https://files.brightsy.ai/...)
    ↓
(Optional) Register library environment with URL

Templates

Component Library (default)

Creates a project with:

• Multiple components for the page builder
• Example HelloWorld component
• Puck configurations
• LLM instructions

my-components/
  src/
    components/
      HelloWorld/
        HelloWorld.tsx
        HelloWorld.config.ts
        HelloWorld.llm.ts
        index.ts
    index.tsx
  vite.config.ts
  tsconfig.json
  package.json
  README.md

Custom Application

Creates a project with:

• Single App component that IS the entire application
• Handles its own routing and state
• Minimal page builder config

my-app/
  src/
    App/
      App.tsx
      App.config.ts
      App.llm.ts
      index.ts
    index.tsx
  vite.config.ts
  tsconfig.json
  package.json
  README.md

Development

After scaffolding:

cd my-components
npm install
npm run dev

Building

npm run build

Output goes to dist/ ready for deployment.

Complete Workflow

# 1. Create the project
npx create-brightsy-component-lib my-components
cd my-components
npm install

# 2. Develop components
npm run dev

# 3. Login (one-time)
npx create-brightsy-component-lib login

# 4. Build and deploy
npm run build
npx create-brightsy-component-lib deploy

# 5. Register via MCP (if not using --lib-id)
# MCP: create_lib --name "My Components"
# MCP: create_lib_env --lib_id xxx --name production --module_url <returned-url>
# MCP: assign_lib_to_page_type --page_type_id xxx --lib_id xxx

License

MIT