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.

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
  1. Install pui-cli:
pnpm add -D @elliemae/pui-cli
  1. 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"
  }
}
  1. 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"]
}
  1. 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
  1. Create .husky/pre-commit:
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

npx lint-staged
  1. 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​

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