USI CLI (@ubc.one/cli)

Unified Standard Instrument - A powerful CLI tool for generating structured frontend applications with a clear, maintainable architecture.

📋 Overview

USI CLI is a command-line tool developed by the @ubc.one team that helps developers create and maintain frontend applications following standardized architectural guidelines. It provides scaffolding, code generation, and project management commands to ensure consistency across your codebase.

🚀 Features

• Project Initialization - Bootstrap new applications from templates
• Context Generation - Create structured units and widgets
• Segment Generation - Generate individual components (UI, services, APIs, types, etc.)
• File Management - Move and remove files with automatic export updates
• Dry Run Mode - Preview changes before executing them
• Type-Safe - Full TypeScript support

📦 Installation

npm install -g @ubc.one/cli

🛠️ Commands

usi create-app <app-name>

Create a new frontend application from a template.

usi create-app my-awesome-app

Options:

• --dry-run - Preview what would be created without actually creating

Example:

usi create-app my-project --dry-run

usi generate (alias: g)

Generate various project structure elements.

Generate Unit Context

Create a new unit with all segments (ui, service, api, lib, type).

usi generate unit <name>
# or
usi g u <name>

Example:

usi g u user-profile

Generate Widget Context

Create a new widget with all segments.

usi generate widget <name>
# or
usi g w <name>

Example:

usi g w header-navigation

Generate Segments

Create individual segments within contexts.

usi generate segment <segment-type> <name> --context <context-name>
# or
usi g s <segment-type> <name> --context <context-name>

Available Segment Types:

UI Components:

• ui - Generate a UI component

Services:

• service - Generate a service file
• service/servitor - Generate a servitor function
• service/hook - Generate a React hook
• service/query - Generate a query hook
• service/mutation - Generate a mutation hook
• service/provider - Generate a provider component
• service/store - Generate a persistent store

API:

• api - Generate an API file
• api/interceptor - Generate an API client interceptor
• api/client - Generate an API client
• api/method - Generate an API method

Libraries:

• lib - Generate a library file
• lib/constant - Generate a library constant
• lib/util - Generate a library utility

Types:

• type - Generate a type file
• type/ui - Generate a UI type
• type/http - Generate an HTTP type
• type/util - Generate a utility type

Examples:

# Generate a UI component in the user-profile unit
usi g s ui profile-card --context user-profile

# Generate a hook in the shared layer
usi g s service/hook use-auth --context shared

# Generate an API method
usi g s api/method get-user-data --context user

Options:

• --context <context> - Specify the context name (e.g., user, shared)
• --dry-run - Preview what would be created

usi move <from> <to>

Move or rename files and directories with automatic export updates.

usi move src/old-path src/new-path

Options:

• --dry-run - Preview what would be moved

Example:

usi move units/user units/user-profile --dry-run

usi remove <path>

Remove files or directories and clean up exports from Public API.

usi remove units/old-feature

Options:

• --dry-run - Preview what would be removed

📁 Project Structure

USI CLI follows a layered architecture:

your-app/
├── shared/          # Shared components and utilities
│   ├── ui/
│   ├── service/
│   ├── api/
│   ├── lib/
│   └── type/
├── units/           # Business logic units
│   └── [unit-name]/
│       ├── ui/
│       ├── service/
│       ├── api/
│       ├── lib/
│       └── type/
├── widgets/         # Composite UI components
│   └── [widget-name]/
│       └── ...
├── pages/           # Page-level components (if applicable)
│   └── [page-name]/
│       └── ...
└── app/             # Application layer
    └── ...

🎯 Naming Conventions

• All names must be in kebab-case (e.g., user-profile, auth-form)
• Component names are automatically converted to PascalCase (e.g., UserProfile)
• Function/service names are automatically converted to camelCase (e.g., userProfile)

🔧 Development

Prerequisites

• Node.js 16+
• TypeScript

Build

npm run build

Development Mode

npm run dev

📝 Examples

Creating a Complete Feature

# 1. Create a new unit for user management
usi g u user-management

# 2. Generate a profile card UI component
usi g s ui profile-card --context user-management

# 3. Generate a service hook for fetching user data
usi g s service/hook use-user-data --context user-management

# 4. Generate an API method
usi g s api/method get-user --context user-management

# 5. Generate types
usi g s type/http user-response --context user-management

Working with Shared Components

# Generate a button component in shared
usi g s ui button --context shared

# Generate a utility function in shared
usi g s lib/util format-date --context shared

⚙️ Configuration

The CLI uses predefined configurations for:

• Template repository: https://github.com/UBC-software-development/react-router-template.git

🤝 Contributing

This tool is developed and maintained by the @ubc.one team. For issues, suggestions, or contributions, please contact the team.

📄 License

Copyright © @ubc.one team

🆘 Support

For help and documentation:

usi --help
usi generate --help
usi generate segment --help

Built with ❤️ by @ubc.one team