In8Sync Spherical CLI

A command-line tool for creating and building external React components that you can use inside the Spherical UI Builder.

All components are built for the Puck editor, so you need to get familiar with this library first, since all components need to follow the same structure and configuration requirements.

Installation

# Install globally
npm install -g @in8sync/spherical-cli

# Or use with npx
npx spherical-cli --help

Commands

init <project-name>

Initialize a new external components project with a Vite + React setup.

spherical-cli init my-components
cd my-components

This creates:

my-components/
├── package.json
├── vite.config.js
├── components.json
└── src/
    └── ExternalButton.jsx

build

Build the components using Vite. Must be run inside a project directory.

cd my-components
spherical-cli build

This will build your components and put them in the dist/ folder. You then need to upload them through the client admin dashboard, and they will be available for you to use in the Spherical UI Builder.

Project Structure

The generated project follows this structure:

• package.json - Project dependencies and scripts
• vite.config.js - Vite configuration for building ES modules
• components.json - List of available components (you must add new components here)
• src/ - Source directory for components
  • ExternalButton.jsx - Example button component

Important: Every time you add new components, you need to add them to the components.json file.

Usage

1. Initialize a project:

   spherical-cli init my-project
   cd my-project

2. Develop your components:

   • Edit files in src/
   • Add new components to components.json

3. Build for production:

   spherical-cli build

4. Deploy your components:

   • Upload the dist/ folder contents through the admin dashboard
   • Components will be available in the Spherical UI Builder

Component Development

Each component should:

• Export a default React component
• Export a puckConfig object with Puck editor configuration

For more details on configuration options and available fields, see the Puck documentation.

Remember: Every new component must be added to the components.json file to be recognized by the system.