create-unisphere-project

CLI tool to quickly create a new Unisphere workspace from a template.

Installation

No installation required. Use npx to run directly:

npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false

Or install globally:

npm install -g @unisphere/create-unisphere-project
create-unisphere-project --company-name=acme --experience-name=video --is-internal-product=false

Usage

All flags are required. The CLI is non-interactive and will fail with a clear error message if any required flag is missing.

Required Flags

• --company-name: The company name (letters, hyphens, and spaces only)
• --experience-name: The experience name (letters, hyphens, and spaces only)
• --is-internal-product: Whether this is an internal product (true or false)

Optional Flags

• --cwd: The working directory where the project will be created (default: current directory)
• --verbose: Output debug logs

Examples

Create an external product workspace

npx @unisphere/create-unisphere-project \
  --company-name=acme \
  --experience-name=video \
  --is-internal-product=false

This creates a directory named unisphere-video in the current directory.

Create an internal product workspace

npx @unisphere/create-unisphere-project \
  --company-name="My Company" \
  --experience-name="analytics dashboard" \
  --is-internal-product=true

This creates a directory named unisphere-analytics-dashboard in the current directory.

Create in a specific directory

npx @unisphere/create-unisphere-project \
  --company-name=acme \
  --experience-name=video \
  --is-internal-product=false \
  --cwd=/path/to/parent/directory

What Gets Created

The CLI creates a complete Nx monorepo workspace with:

• Pre-configured Nx workspace with Unisphere plugin
• Types packages for shared TypeScript definitions
• Example runtime and visual (for external products)
• Development application for testing
• Documentation site with getting started guide
• CI/CD workflows for GitHub Actions
• Pre-commit hooks with linting and formatting
• Dependency management with npm workspaces

Project Structure

unisphere-{experience-name}/
├── packages/
│   ├── runtimes/           # Runtime packages
│   ├── applications/       # Development applications
│   ├── shared/            # Shared libraries
│   └── types/             # TypeScript type definitions
├── unisphere/
│   └── documentation/     # Documentation sites
├── .github/
│   └── workflows/         # CI/CD workflows
├── nx.json                # Nx workspace configuration
├── package.json           # Root package configuration
└── README.md              # Project documentation

Naming Conventions

Company Name

• Letters, hyphens, and spaces allowed
• Will be normalized to lowercase with hyphens
• Used for package scopes: @{company-name}/package-name

Experience Name

• Letters, hyphens, and spaces allowed
• Will be normalized to lowercase with hyphens
• "unisphere" prefix automatically added if missing
• Used for repository name: unisphere-{experience-name}

Examples

| Input | Normalized | Repository Name | |-------|-----------|-----------------| | Video Player | video-player | unisphere-video-player | | My Analytics | my-analytics | unisphere-my-analytics | | Unisphere CRM | crm | unisphere-crm |

Error Messages

The CLI provides clear error messages when required flags are missing:

$ npx @unisphere/create-unisphere-project

Error: --company-name is required

$ npx @unisphere/create-unisphere-project --company-name=acme

Error: --experience-name is required

$ npx @unisphere/create-unisphere-project --company-name=acme --experience-name=video

Error: --is-internal-product is required

Migration from Interactive CLI

If you're upgrading from an older version that had interactive prompts, you now need to provide all flags explicitly. See the Migration Guide for details.

Development

Building

npm run build -- create-unisphere-project

Testing Locally

Use the hidden --nxplugin-path flag to test with a local plugin:

npx @unisphere/create-unisphere-project \
  --company-name=test \
  --experience-name=test \
  --is-internal-product=false \
  --nxplugin-path=/path/to/local/plugin

Requirements

• Node.js >= 18
• npm >= 9

Support

For issues and questions:

• GitHub Issues: https://github.com/kaltura/unisphere-nx/issues
• Documentation: See generated workspace README.md

License

See the root LICENSE file for details.