Usage Guide

This guide provides detailed documentation for all available commands in @elliemae/pui-cli.

Build Commands
Development Commands
Testing Commands
Linting Commands
Documentation Commands
Utility Commands

Build Commands

`pui-cli build`

Builds your application for production.

Usage:

pui-cli build [options]

Options:

-p, --prod - Production build with optimizations

Examples:

# Build web application (development)
pui-cli build

# Build web application (production)
pui-cli build -p

Output:

Application builds go to build/ or dist/ directory
Creates optimized bundles with code splitting

What it does:

Bundles code using Webpack
Minifies JavaScript and CSS
Generates source maps
Optimizes assets
Creates production-ready build
Applies tree shaking for smaller bundles

`pui-cli buildCDN`

Builds the application for CDN deployment.

Usage:

pui-cli buildCDN

What it does:

Creates CDN-optimized builds
Generates proper asset paths for CDN
Optimizes bundle splitting

`pui-cli pack`

Packages your library for distribution with multiple output formats.

Usage:

pui-cli pack [options]

Options:

-p, --prod - Production build with minification
-t, --target <target> - Build target (default: browser, options: node, browser)

Examples:

# Build library (development)
pui-cli pack

# Build library (production)
pui-cli pack -p

# Build for Node.js target
pui-cli pack -p -t node

Output:

Creates dist/ directory with:
- dist/esm/ - ES Module format
- dist/cjs/ - CommonJS format
- dist/types/ - TypeScript declarations
- dist/umd/ - UMD format (browser)

What it does:

Builds library in multiple formats (ESM, CJS, UMD)
Generates TypeScript declaration files
Minifies code in production mode
Creates source maps
Validates package.json exports
Optimized for tree-shaking

Development Commands

`pui-cli start`

Starts the development server with hot module replacement.

Usage:

pui-cli start [options]

Options:

-p, --prod - Start in production mode
--port <number> - Specify port (default: 3000)
--open - Automatically open browser
--hot - Enable hot module replacement (default: true)

Examples:

# Start on default port (development)
pui-cli start

# Start in production mode
pui-cli start -p
# or
pnpm start:prod

# Start on custom port
pui-cli start --port 8080

# Start and open browser
pui-cli start --open

What it does:

Starts Webpack dev server
Enables hot module replacement
Serves static files
Provides mock API endpoints
Auto-reloads on file changes

Environment Variables:

PORT=3000
HOST=localhost
HTTPS=false

`pui-cli storybook`

Runs Storybook for component development and documentation.

Usage:

pui-cli storybook [options]

Options:

-b, --build - Build static storybook
--docs - Run in documentation mode
--port <number> - Specify port (default: 6006)

Examples:

# Start Storybook dev server
pui-cli storybook

# Start with documentation mode
pui-cli storybook --docs

# Build static Storybook
pui-cli storybook -b

# Build with documentation mode
pui-cli storybook -b --docs

# Run on custom port
pui-cli storybook --port 9000

What it does:

Starts Storybook development server
Provides interactive component playground
Generates component documentation
Useful for library development

Testing Commands

`pui-cli test`

Runs Jest tests with coverage reporting.

Usage:

pui-cli test [options]

Options:

-f, --fix - Update snapshots (-u)
-p, --prod - Run tests in production mode
--watch - Run tests in watch mode
--debug - Run tests in debug mode
--coverage - Generate coverage reports (default: true)
--passWithNoTests - Don't fail if no tests found
--bail - Stop on first test failure
--findRelatedTests - Run tests related to changed files

Examples:

# Run all tests with coverage
pui-cli test

# Run tests in production mode
pui-cli test -p

# Run in watch mode
pnpm test:watch

# Update snapshots
pui-cli test -f
# or
pnpm test:fix

# Debug tests
pui-cli test --debug
# or
pnpm test:debug

# Run only tests related to changed files (useful for pre-commit)
pui-cli test --coverage --passWithNoTests --bail --findRelatedTests

What it does:

Executes Jest test runner
Generates coverage reports in reports/ directory
Supports React Testing Library
Provides snapshot testing
Generates HTML coverage reports

Coverage Reports:

After running tests, view coverage at:

reports/index.html - Overall coverage report
reports/lcov-report/index.html - Detailed line coverage

`pui-cli vitest`

Runs Vitest for modern, fast testing.

Usage:

pui-cli vitest [options]

Options:

--watch - Run in watch mode
--ui - Open Vitest UI
--coverage - Generate coverage

Examples:

# Run tests
pui-cli vitest

# Run with UI
pui-cli vitest --ui

# Run in watch mode
pui-cli vitest --watch

# Generate coverage
pui-cli vitest --coverage

What it does:

Provides fast test execution with Vite
Supports ESM natively
Offers visual test UI
Compatible with Jest syntax

Linting Commands

`pui-cli lint`

Lints your codebase for code quality and style issues.

Usage:

pui-cli lint [options]

Options:

--fix - Automatically fix linting issues
--js - Lint JavaScript/TypeScript files only
--css - Lint CSS/SCSS files only
--commit - Lint commit messages
--debug - Show detailed error messages

Examples:

# Lint all files
pui-cli lint

# Auto-fix issues
pui-cli lint --fix

# Lint only JavaScript files
pui-cli lint --js

# Lint only CSS files
pui-cli lint --css

# Lint commit messages
pui-cli lint --commit

# Show debug information
pui-cli lint --debug

What it does:

Runs ESLint on JavaScript/TypeScript files
Runs Stylelint on CSS/SCSS files
Runs Commitlint on commit messages
Enforces code style consistency
Checks for common errors and anti-patterns

Linting Rules:

The CLI provides pre-configured rules for:

ESLint: React, TypeScript, Jest best practices
Stylelint: CSS best practices and conventions
Commitlint: Conventional Commits format

`pui-cli tscheck`

Type-checks TypeScript files without emitting output.

Usage:

pui-cli tscheck [options]

Options:

--files - Check specific files only
--watch - Watch mode for continuous type checking
--debug - Show detailed TypeScript errors

Examples:

# Check all types
pui-cli tscheck

# Check with file listing
pui-cli tscheck --files

# Watch for changes
pui-cli tscheck --watch

# Show detailed errors
pui-cli tscheck --debug

What it does:

Runs TypeScript compiler in check mode
Reports type errors
Doesn't emit JavaScript files
Useful for CI/CD pipelines

Documentation Commands

`pui-cli gendoc`

Generates API documentation from your code.

Usage:

pui-cli gendoc

What it does:

Generates TypeDoc documentation
Extracts JSDoc comments
Creates HTML documentation
Outputs to docs/api/ directory

Example JSDoc comments:

/**
 * Adds two numbers together
 * @param a - First number
 * @param b - Second number
 * @returns The sum of a and b
 * @example
 * ```ts
 * add(2, 3) // returns 5
 * ```
 */
export function add(a: number, b: number): number {
  return a + b;
}

Utility Commands

`pui-cli version`

Manages versioning for monorepo workspaces.

Usage:

pui-cli version [options]

Options:

--set <version> - Set specific version for all packages
--workspace - Update workspace package versions

Examples:

# Update versions in monorepo
pui-cli version --workspace

# Set specific version
pui-cli version --set 2.0.0

What it does:

Updates package.json versions
Maintains version consistency in monorepos
Updates dependency versions

`pui-cli codemod`

Runs code transformations using jscodeshift.

Usage:

pui-cli codemod <transform>

Arguments:

<transform> - Name of the transform to apply

What it does:

Applies automated code transformations
Useful for migrations
Batch code refactoring

Advanced Usage

Using pui-cli in npm scripts

package.json example:

{
  "scripts": {
    "dev": "pui-cli start",
    "build": "pui-cli build",
    "build:lib": "pui-cli build --service",
    "test": "pui-cli test --coverage",
    "test:watch": "pui-cli test --watch",
    "test:debug": "pui-cli test --debug",
    "lint": "pui-cli lint",
    "lint:fix": "pui-cli lint --fix",
    "lint:js": "pui-cli lint --js --fix",
    "lint:css": "pui-cli lint --css --fix",
    "typecheck": "pui-cli tscheck",
    "storybook": "pui-cli storybook",
    "storybook:build": "pui-cli storybook --build",
    "gendoc": "pui-cli gendoc",
    "pack": "pui-cli pack",
    "precommit": "lint-staged"
  }
}

CI/CD Integration

Jenkins example:

pipeline {
  agent any
  stages {
    stage('Install') {
      steps {
        sh 'pnpm install'
      }
    }
    stage('Lint') {
      steps {
        sh 'pnpm lint'
      }
    }
    stage('Type Check') {
      steps {
        sh 'pnpm tscheck'
      }
    }
    stage('Test') {
      steps {
        sh 'pnpm test'
      }
    }
    stage('Build') {
      steps {
        sh 'pnpm build'
      }
    }
  }
}

Using Exported Configurations

You can import and extend the CLI's configurations in your own config files:

ESLint:

import { eslintConfig } from '@elliemae/pui-cli';

export default [
  ...eslintConfig,
  {
    rules: {
      // Your custom rules
      'no-console': 'warn',
    },
  },
];

Prettier:

import { prettierConfig } from '@elliemae/pui-cli';

export default {
  ...prettierConfig,
  // Your custom overrides
  printWidth: 100,
};

Vitest:

import { defineConfig } from 'vitest/config';
import { vitestConfig } from '@elliemae/pui-cli/vitest';

export default defineConfig({
  ...vitestConfig,
  test: {
    ...vitestConfig.test,
    // Your custom test config
  },
});

Configuration Priority

The CLI follows this priority order for configuration:

Project-level configuration files
CLI's default configurations
Command-line arguments
Environment variables

Best Practices

Development Workflow

Start development server:
```
pnpm start
```
Run tests in watch mode (separate terminal):
```
pnpm test --watch
```
Type check (separate terminal):
```
pnpm tscheck --watch
```
Before committing:
```
pnpm lint:fix
pnpm test
pnpm typecheck
```

Library Development Workflow

Start Storybook:
```
pnpm storybook
```
Run tests in watch mode:
```
pnpm test --watch
```
Build library:
```
pnpm build --service
```
Test package:
```
pnpm pack
```

Performance Tips

Use --findRelatedTests to run only relevant tests
Enable --watch mode during development
Use --silent in CI to reduce output
Run lint --js and lint --css separately for faster feedback

Troubleshooting

Build Issues

Error: Module not found

# Clear cache and rebuild
rm -rf node_modules dist
pnpm install
pnpm build

Test Issues

Error: Tests timing out

# Increase timeout in jest.config
pui-cli test --debug

Linting Issues

Error: Too many linting errors

# Fix automatically
pnpm lint --fix

# Fix only JS
pnpm lint --js --fix

# Fix only CSS
pnpm lint --css --fix

Additional Resources

Need Help?

If you encounter issues or have questions:

Review the documentation
Contact the UI Platform team via ui-platform teams channel

Table of Contents​

Build Commands​

pui-cli build​

pui-cli buildCDN​

pui-cli pack​

Development Commands​

pui-cli start​

pui-cli storybook​

Testing Commands​

pui-cli test​

pui-cli vitest​

Linting Commands​

pui-cli lint​

pui-cli tscheck​

Documentation Commands​

pui-cli gendoc​

Utility Commands​

pui-cli version​

pui-cli codemod​

Advanced Usage​

Using pui-cli in npm scripts​

CI/CD Integration​

Using Exported Configurations​

Configuration Priority​

Best Practices​

Development Workflow​

Library Development Workflow​

Performance Tips​

Troubleshooting​

Build Issues​

Test Issues​

Linting Issues​

Additional Resources​

Need Help?​

Table of Contents

Build Commands

`pui-cli build`

`pui-cli buildCDN`

`pui-cli pack`

Development Commands

`pui-cli start`

`pui-cli storybook`

Testing Commands

`pui-cli test`

`pui-cli vitest`

Linting Commands

`pui-cli lint`

`pui-cli tscheck`

Documentation Commands

`pui-cli gendoc`

Utility Commands

`pui-cli version`

`pui-cli codemod`

Advanced Usage

Using pui-cli in npm scripts

CI/CD Integration

Using Exported Configurations

Configuration Priority

Best Practices

Development Workflow

Library Development Workflow

Performance Tips

Troubleshooting

Build Issues

Test Issues

Linting Issues

Additional Resources

Need Help?