Skip to main content

# Usage Guide

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

## Table of Contents​

- Build Commands
- Development Commands
- Testing Commands
- Linting Commands
- Documentation Commands
- Utility Commands
- Framework Chunk Splitting

## 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:

1. Project-level configuration files
2. CLI's default configurations
3. Command-line arguments
4. Environment variables

## Best Practices​

### Development Workflow​

1. Start development server:

       pnpm start

2. Run tests in watch mode (separate terminal):

       pnpm test --watch

3. Type check (separate terminal):

       pnpm tscheck --watch

4. Before committing:

       pnpm lint:fix
       pnpm test
       pnpm typecheck

### Library Development Workflow​

1. Start Storybook:

       pnpm storybook

2. Run tests in watch mode:

       pnpm test --watch

3. Build library:

       pnpm build --service

4. 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

### Framework Chunk Splitting​

`pui-cli` supports an opt-in framework chunk that separates React core libraries into a dedicated bundle. Because the framework changes far less frequently than other vendor dependencies, this improves long-term browser caching and reduces the amount of JavaScript users re-download on routine releases.

How it works

When enabled, the production (and dev) Webpack build creates three vendor-level chunks instead of two:

Chunk | Contents
--- | ---
`emui.js` | `@elliemae/*` packages (design system, SDK, diagnostics, etc.)
`framework.js` | `react`, `react-dom`, `scheduler`, `react-router`, `react-router-dom`, `history`, `react-is`
`vendors.js` | Everything else from `node_modules`

Without the flag, the default two-chunk layout is preserved (`emui.js` + `vendors.js`).

Enabling the flag

Add the following to your application's `.env` file:

    SPLIT_FRAMEWORK_CHUNK=true

The flag is read at build time. No changes to `pui-cli` itself are needed.

Required application updates

After enabling the flag you must update three places in your application to include `framework.js` in the script loading order.

1. `index-app-loader.html`

If your application uses `pui-app-loader`, update the `bodyScripts` array to include `framework.js` before `vendors.js`:

    emuiAppLoader.load({
      appId: 'loanapp',
      headScripts: [],
      bodyScripts: ['runtime~app.js', 'framework.js', 'vendors.js', 'emui.js', 'app.js'],
      styles: ['vendors.css', 'emui.css'],
      isJsModule: true,
    });

2. `app.config.json` — `microFrontendApps` file lists

Any microapp built with the framework chunk enabled must list `framework.js` in its `development.files` and `production.files` arrays. The host app's `app.config.json` must reflect this so that `app-bridge` loads the scripts in the correct order.

Development example:

    {
      "microFrontendApps": {
        "myapp": {
          "name": "My App",
          "hostUrl": "./myapp",
          "development": {
            "files": [
              "https://cdn.mortgagetech.q1.ice.com/pui-diagnostics@3",
              "https://cdn.mortgagetech.q1.ice.com/pui-logrocket@1",
              "js/global.js",
              "framework.js",
              "emui.js",
              "vendors.js",
              "app.js"
            ]
          }
        }
      }
    }

Production example:

    {
      "microFrontendApps": {
        "myapp": {
          "name": "My App",
          "hostUrl": "./myapp",
          "production": {
            "files": [
              "https://cdn.mortgagetech.q1.ice.com/pui-diagnostics@3",
              "https://cdn.mortgagetech.q1.ice.com/pui-logrocket@1",
              "js/global.js",
              "runtime~app.js",
              "framework.js",
              "emui.js",
              "vendors.js",
              "app.js",
              "emui.css",
              "vendors.css"
            ]
          }
        }
      }
    }

> Load order matters. `framework.js` must appear before `vendors.js` and `emui.js` because both depend on React.

3. Verify the build output

After enabling the flag, run a production build and confirm the new chunk appears:

    pnpm build
    ls build/latest/js/framework.*.js

You should see a hashed file like `framework.abc123.js` alongside the existing `emui`, `vendors`, and `app` chunks.

Disabling the flag

Remove `SPLIT_FRAMEWORK_CHUNK=true` from `.env` (or set it to `false`), then reverse the file-list changes above — remove `framework.js` from `index-app-loader.html` and `app.config.json`. The build will revert to the default two-chunk layout.

## 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​

- Getting Started Guide
- API Documentation
- Migration Guide
- GitHub Repository

## Need Help?​

If you encounter issues or have questions:

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