Skip to main content

# PUI CLI Documentation

Welcome to the ICE MT UI Platform CLI documentation. This CLI tool provides a comprehensive set of commands for building, testing, and maintaining UI applications and libraries.

## Quick Links​

- GitHub Repository
- Build Job
- SonarQube Report
- Usage Guide - Detailed command reference and examples
- API Documentation - Generated API docs from source code
- SSL Certificate Setup - HTTPS certificate configuration

## Features​

- 🚀 Modern Build Tools - Webpack and Vite integration
- 🧪 Testing - Jest and Vitest support with coverage
- 🎨 Linting - ESLint, Prettier, and Stylelint configurations
- 📝 TypeScript - Full TypeScript support
- 📚 Storybook - Component development and documentation
- 🔧 Development Server - Hot module replacement
- 📦 Library Support - Build both applications and libraries
- 🎯 Monorepo Support - Workspace version management

## Getting Started​

This guide will help you get started with `@elliemae/pui-cli`, a command-line interface tool for building and managing UI applications and libraries.

### Prerequisites​

Before you begin, ensure you have the following installed:

- Node.js: Version 20
- pnpm: Version 8 (recommended package manager)

### Installation​

#### For New Projects​

Install the CLI as a development dependency in your project:

    pnpm add -D @elliemae/pui-cli

### Quick Start​

#### Setting Up a New Application​

1. Create a package.json if you don't have one:

    pnpm init

2. Install pui-cli:

    pnpm add -D @elliemae/pui-cli

3. Add scripts to your package.json:

For applications:

    {
      "scripts": {
        "start": "pui-cli start",
        "start:prod": "pui-cli start -p",
        "build": "pui-cli build",
        "test": "pui-cli test",
        "vitest": "pui-cli vitest",
        "test:fix": "pui-cli test -f",
        "test:debug": "pui-cli test --debug",
        "lint": "pui-cli lint",
        "lint:fix": "pui-cli lint --fix",
        "lint:staged": "lint-staged",
        "tscheck": "pui-cli tscheck --files",
        "storybook": "pui-cli storybook",
        "storybook:docs": "pui-cli storybook --docs",
        "storybook:build": "pui-cli storybook -b",
        "gendoc": "pui-cli gendoc"
      }
    }

For libraries:

    {
      "scripts": {
        "build": "pui-cli pack -p",
        "build:dev": "pui-cli pack",
        "test": "pui-cli test",
        "test:fix": "pui-cli test -f",
        "lint": "pui-cli lint",
        "lint:fix": "pui-cli lint --fix",
        "tscheck": "pui-cli tscheck --files"
      }
    }

4. Create a TypeScript configuration (`tsconfig.json`):

For applications:

    {
      "extends": "@elliemae/pui-cli/app.tsconfig.json",
      "compilerOptions": {
        "outDir": "dist/types",
        "baseUrl": ".",
        "paths": {}
      },
      "include": [
        "app/**/*",
        "wdio.config.mjs",
        "vitest.config.ts",
        "docusaurus.config.ts"
      ],
      "exclude": ["node_modules", "**/*.spec.ts"]
    }

For libraries:

    {
      "extends": "@elliemae/pui-cli/library.tsconfig.json",
      "compilerOptions": {
        "outDir": "dist/types",
        "declarationDir": "dist/types",
        "baseUrl": "."
      },
      "include": ["lib/**/*", "./docusaurus.config.ts"],
      "exclude": ["node_modules"]
    }

5. Create your source structure:

For applications:

    your-project/
    ├── app/
    │   ├── index.tsx          # Entry point
    │   ├── route/             # Routes
    │   ├── view/              # Components
    │   ├── data/              # Redux slices
    │   ├── api/               # RTK Query APIs
    │   ├── sideeffect/        # Redux Sagas
    │   ├── utils/             # Utilities
    │   └── app.config.json    # App configuration
    ├── public/                # Static assets
    ├── package.json
    └── tsconfig.json

For libraries:

    your-project/
    ├── lib/
    │   ├── index.ts          # Entry point
    │   ├── components/       # Components
    │   ├── utils/            # Utilities
    │   └── __tests__/        # Tests
    ├── stories/              # Storybook stories (optional)
    ├── package.json
    └── tsconfig.json

## Project Structure​

### Application Structure​

    your-app/
    ├── app/                   # Application source code
    │   ├── index.tsx         # Entry point
    │   ├── route/            # Route definitions
    │   ├── view/             # UI components
    │   ├── data/             # Redux slices (state)
    │   ├── api/              # RTK Query API definitions
    │   ├── sideeffect/       # Redux Sagas
    │   ├── utils/            # Utility functions
    │   ├── tests/            # Test files
    │   └── app.config.json   # App configuration
    ├── public/               # Static assets
    ├── e2e/                  # E2E tests (optional)
    ├── docs/                 # Docusaurus docs (optional)
    ├── package.json
    └── tsconfig.json

### Library Structure​

    your-library/
    ├── lib/                   # Library source code
    │   ├── index.ts          # Entry point
    │   ├── components/       # Components
    │   └── __tests__/        # Test files
    ├── stories/              # Storybook stories
    ├── package.json
    └── tsconfig.json

## Configuration Files​

### Prettier Configuration​

Create `prettier.config.cjs`:

    const { prettierConfig } = require('@elliemae/pui-cli');
    module.exports = prettierConfig;

### Stylelint Configuration​

Create `stylelint.config.cjs`:

    const { stylelintConfig } = require('@elliemae/pui-cli');
    module.exports = stylelintConfig;

### Commitlint Configuration​

Create `commitlint.config.cjs`:

    const { commitlintConfig } = require('@elliemae/pui-cli');
    module.exports = commitlintConfig;

### Lint-staged Configuration​

Create `lint-staged.config.mjs`:

    import { lintStagedConfig } from '@elliemae/pui-cli';
    export default lintStagedConfig;

### Babel Configuration (Optional)​

Create `babel.config.cjs` for custom Babel configuration:

    const { babelConfig } = require('@elliemae/pui-cli');
    module.exports = babelConfig;

## Git Hooks Setup​

To enable pre-commit hooks with Husky:

1. Install Husky:

    pnpm add -D husky
    npx husky init

2. Create `.husky/pre-commit`:

    #!/bin/sh
    . "$(dirname "$0")/_/husky.sh"

    npx lint-staged

3. Make it executable:

    chmod +x .husky/pre-commit

## Additional Configuration Files​

### Jest Configuration​

For custom Jest configuration, create `jest.config.cjs`:

    const { jestConfig } = require('@elliemae/pui-cli');
    module.exports = jestConfig;

## Environment Variables​

Create a `.env` file in your project root for environment-specific configuration:

    PORT=3000
    NODE_ENV=development

## Running Your First Build​

### Start Development Server​

    # Start development server
    pnpm start

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

This will:

- Start webpack dev server
- Enable hot module replacement
- Serve your application (default: http://localhost:3000)
- Watch for file changes

### Build for Production​

    # Build application
    pnpm build

    # Build library
    pui-cli pack -p

    # Build library for development (no minification)
    pui-cli pack

This will:

- Create an optimized production build
- Output files to the `dist/` or `build/` directory
- Generate source maps
- Minify and bundle your code
- For libraries: Generate ESM, CJS, and type declarations

### Run Tests​

    # Run Jest tests
    pnpm test

    # Run tests with auto-fix
    pnpm test:fix

    # Debug tests
    pnpm test:debug

    # Watch mode
    pnpm test:watch

### Linting and Type Checking​

    # Lint code
    pnpm lint

    # Auto-fix lint issues
    pnpm lint:fix

    # Type check
    pnpm tscheck

    # Lint staged files only
    pnpm lint:staged

### Storybook​

    # Run Storybook dev server
    pnpm storybook

    # Run with docs mode
    pnpm storybook:docs

    # Build static Storybook
    pnpm storybook:build

## Next Steps​

- Read the Usage Guide for detailed command documentation
- Check out the API Documentation for library exports
- Review the Migration Guide if upgrading from an older version

## Troubleshooting​

### Common Issues​

Port already in use:

    # Change the port in your .env file
    PORT=3001

Module not found errors:

    # Clear node_modules and reinstall
    rm -rf node_modules
    pnpm install

Build fails with TypeScript errors:

    # Run type checking separately to see detailed errors
    pnpm tscheck

HTTPS certificate warnings:

If you see "Not Secure" or certificate warnings when using HTTPS in development:

- See the SSL Certificate Setup Guide for detailed instructions
- You need to trust the self-signed CA certificate on your system
- Platform-specific instructions available for macOS, Windows, and Firefox

## Getting Help​

If you encounter issues:

1. Review the documentation in the `docs/` folder
2. Reach out to the ui-platform teams channel