@hank-repo/frontend-platform

Overview

@hank-repo/frontend-platform is the non-interactive CLI for creating and validating hank-repo React Hosts and Frontend Modules. It provides five commands: create-host, create-module, add-module, generate-api, and validate.

The package is a CLI only. It has no root JavaScript library export and must not be included in a browser runtime bundle.

Installation

Run an exact CLI version with pnpm dlx; no global installation is required:

pnpm dlx @hank-repo/frontend-platform@<exact-version> --help

Use an exact version in automation as well. Do not invoke an unpinned tag such as latest.

Quick Start

Create a customer Host with Identity and Language Management, install its frozen dependency graph, and start Vite:

pnpm dlx @hank-repo/frontend-platform@<exact-version> create-host customer-host --preset customer
cd customer-host
corepack pnpm install --frozen-lockfile
pnpm dev

While the development server is running, validate the generated Host from a second terminal:

cd customer-host
pnpm dlx @hank-repo/frontend-platform@<exact-version> validate --target .

The generated Host owns its shell, Router, adapters, application configuration, and business source. It starts as UNLICENSED; choose an approved license before distribution.

Features and Public API

| Command | Input | Result | | --- | --- | --- | | create-host <name> [--preset empty\|customer] [--target <directory>] | A new project name, optional preset, and optional output directory. empty is the default. | Creates a React Host with exact dependencies, a frozen lockfile, Vite discovery, Host runtime wiring, and customer-owned shell source. The customer preset includes IAM and LanguageManagement. | | create-module <name> [--package] [--target <directory>] | A lower-case kebab-case Module name. Without --package, --target identifies an existing Host. | Creates src/modules/<name> in a Host, or a publishable Module package when --package is present. | | add-module <package>@<exactVersion> [--target <host>] | One canonical exact-version package reference from a trusted scope. | Preflights the Registry artifact, installs it as an exact Host dependency, validates and builds the candidate, then updates only package.json and pnpm-lock.yaml. | | generate-api <module> [--target <host>] | One local Module directory name under src/modules. | Runs that Module's orval.config.ts only. It never scans other local Modules or installed package Modules. | | validate [--target <directory>] | A generated Host or publishable Module directory. | Validates workspace policy, exact versions or peer ranges, Manifest and exports, routes, locales, capabilities, runtime singleton ownership, and installed package boundaries. |

Complete command syntax:

frontend-platform create-host <name> [--preset empty|customer] [--target <directory>]
frontend-platform create-module <name> [--package] [--target <directory>]
frontend-platform add-module <package>@<exactVersion> [--target <host>]
frontend-platform generate-api <module> [--target <host>]
frontend-platform validate [--target <directory>]

Exit codes are stable: 0 means success, 1 means the operation or validation failed, and 2 means the command arguments are invalid.

To add a reviewed package Module to an existing Host:

pnpm dlx @hank-repo/frontend-platform@<exact-version> add-module @hank-repo/example-module@<exact-version> --target .

To create and generate an API client for one local Module:

pnpm dlx @hank-repo/frontend-platform@<exact-version> create-module order-management --target .

Set the generated Module's documented OpenAPI environment variable, then run code generation. For example, in PowerShell:

$env:FRONTEND_MODULE_ORDER_MANAGEMENT_OPENAPI_INPUT = "https://example.test/openapi.json"
pnpm api:generate order-management

On macOS or Linux:

FRONTEND_MODULE_ORDER_MANAGEMENT_OPENAPI_INPUT=https://example.test/openapi.json pnpm api:generate order-management

A publishable Module runs its own parameterless pnpm api:generate command instead.

Requirements

• Use the Node engine and exact pnpm version written to the generated project's package.json; Corepack is the supported pnpm launcher.
• The project Registry must be npmjs or an explicitly trusted HTTPS Registry. Provide private Registry credentials through NODE_AUTH_TOKEN, never in the project or command arguments.
• Generated Host dependencies and development dependencies are exact SemVer values. Publishable Module runtime dependencies are compatible peer ranges with exact compatible development versions.
• Generated projects use ordinary exact SemVer values and do not use local dependency protocols, repository paths, or a project .npmrc.
• Keep the generated pnpm-workspace.yaml contract limited to the root package, exact saves, strict peers, and approved build scripts.

Troubleshooting

• Exit code 2: check the command name, positional count, and whether --package or --preset is valid for that command.
• add-module rejects a package reference: use a canonical trusted-scope package name and a full exact SemVer; ranges, tags, local protocols, and untrusted scopes are rejected.
• Registry lookup or integrity validation fails: confirm the trusted HTTPS Registry, network access, package metadata, and NODE_AUTH_TOKEN. Non-404 Registry errors fail closed.
• generate-api cannot find the Module: pass the exact kebab-case directory under src/modules, set its OpenAPI environment variable, and replace any symlink or junction in the Host/Module/config path with ordinary directories and files.
• validate reports dependency or runtime ownership issues: restore exact Host dependencies, compatible Module peers, and one physical installation of every Host runtime package, then reinstall with the frozen lockfile.

License

This package is provided under the terms in LICENSE. Generated projects start as UNLICENSED and require their own approved license before distribution.