@bemedev/app-cli

About

This library provides a command-line interface (CLI) for generating TypeScript typings from @bemedev/app-ts state machine configurations. It automatically extracts and generates type definitions from your machine files, offering a better development experience with improved autocompletion, type checking, and documentation.

This README contains essential information for installing, using, and contributing to the project.

Features

• Automatic Type Generation: Extracts TypeScript typings from .machine.ts files that use createMachine from @bemedev/app-ts
• Watch Mode: Monitors file changes and regenerates types automatically
• Flexible File Selection: Generate types for specific files or use glob patterns
• Strict Mode: Ensures all files follow the .machine.ts naming convention
• Easy Integration: Simple CLI commands that work with any Node.js project

Installation

Install as a development dependency in your project using @bemedev/app-ts:

pnpm add -D @bemedev/app-cli

Requirements

• Node.js >= 22
• Files must use @bemedev/app-ts with createMachine function
• Machine files should follow the .machine.ts naming convention

Usage (CLI)

The CLI provides two main commands:

app-typings generate

Generates typings from all .machine.ts files in your project:

app-typings generate

Options:

• --watch, -w: Watch for file changes and regenerate automatically
• --help, -h: Show help information

Aliases: gen

Examples:

# Generate types once
app-typings generate

# Generate types and watch for changes
app-typings generate --watch

# Using alias
app-typings gen -w

app-typings generateOne

Generates typings for specific files:

app-typings generateOne file1.machine.ts file2.machine.ts

Options:

• --watch, -w: Watch specified files for changes
• --strict, -s: Enable strict mode (all files must end with .machine.ts)
• --help, -h: Show help information

Aliases: genOne, genO

Examples:

# Generate types for specific files
app-typings generateOne src/user.machine.ts src/auth.machine.ts

# Watch specific files
app-typings generateOne src/user.machine.ts --watch

# Strict mode - ensures all files follow naming convention (Regex : "**/*.machine.ts")
app-typings generateOne src/user.machine.ts --strict

File Structure

The CLI looks for files with the following pattern:

• **/*.machine.ts - TypeScript machine files
• **/*.machine.tsx - TypeScript React machine files

Generated files will have the .gen.ts extension:

• user.machine.ts → user.machine.gen.ts
• auth.machine.ts → auth.machine.gen.ts

Integration with npm/pnpm Scripts

Add scripts to your package.json:

{
  "scripts": {
    "types:generate": "app-typings generate",
    "types:watch": "app-typings generate --watch",
    "types:build": "app-typings generateOne src/**/*.machine.ts"
  }
}

Then run:

pnpm run types:generate
pnpm run types:watch

Environment Variables

You can configure the CLI using environment variables:

• APP_TYPINGS_WATCH: Enable watch mode for generate command
• APP_TYPINGS_WATCH_ONE: Enable watch mode for generateOne command
• APP_TYPINGS_STRICT_ONE: Enable strict mode for generateOne command

Contribution

Contributions are welcome: bugs, PRs, improvement suggestions. Please open an issue or a PR targeting the dev branch.

Quick guide:

• Fork → new branch → PR to dev.
• Respect tests and linting (see pnpm test).

CHANGE_LOG

See the full changelog:
CHANGE_LOG

Author

chlbri ([email protected])

My GitHub

Links

• Documentation: https://github.com/chlbri/app-cli.git

License

MIT