npm package: @hailer/create-app
Description: Scaffold a new Hailer app project.
Author: André Kaustell
Latest version: 2.0.2

# @hailer/create-app

Scaffold a new Hailer app project.

## Quick Start

```bash
npm create @hailer/app@latest
cd my-app
npm install
npm run dev
```

> **Node.js 20.19+ required** (Vite 8 dropped Node 18 support).

## Scaffolding

```bash
npm create @hailer/app@latest
```

### Non-interactive (for CI/CD and AI agents)

```bash
npm create @hailer/app@latest my-app-name --template react-ts
npx @hailer/create-app my-app-name --template react-ts
```

The `--template` (or `-t`) flag and project name skip all prompts.

### Other package managers

```bash
yarn create @hailer/app
pnpm create @hailer/app
bunx @hailer/create-app
```

Currently supported template: `react-ts`

## Development

1. Start the dev server: `npm run dev` (port 3000)
2. In Hailer, create a "Local Development" app pointing to `http://localhost:3000`
3. Open the app in Hailer — changes reload automatically

## Publishing

### First time — create and publish a new app

```bash
npm run publish-production -- --create --app-name "My App" --workspace <id> --user-api-key <key> --force
```

This creates the app in Hailer, publishes it, and writes the `appId` to `public/manifest.json` for future publishes. If `--app-name` or `--workspace` are omitted, the script will prompt interactively.

Find your workspace ID in Hailer workspace settings. Generate a user API key in your Hailer user settings.

### Subsequent publishes

```bash
npm run publish-production -- --user-api-key <key> --force
```

Or with email (prompts for password):

```bash
npm run publish-production -- --email user@mail.com
```

### Credential resolution order

1. `--user-api-key` or `--email` flags
2. `USER_API_KEY` or `HAILER_USER_API_KEY` environment variables
3. `HAILER_USER_API_KEY` from `~/.env` (used automatically by Hailer Studio)

### Environments

| Command | Target |
|---------|--------|
| `npm run publish-local` | Local (`https://api.hailer.local.gd`) |
| `npm run publish-development` | Development (`https://testapi.hailer.biz`) |
| `npm run publish-staging` | Staging (`https://api.hailer.biz`) |
| `npm run publish-production` | Production (`https://api.hailer.com`) |

### Marketplace

Add `--market` to publish to the Hailer marketplace. Requires `version` and `versionDescription` in `public/manifest.json`:

```json
{
    "appId": "...",
    "version": "1.0.0",
    "versionDescription": "Initial release"
}
```

```bash
npm run publish-production -- --market --user-api-key <key> --force
```

Bump the `version` (semver) for each subsequent marketplace publish.

### All publish options

| Flag | Description |
|------|-------------|
| `--email <email>` | Authenticate with email (prompts for password) |
| `--user-api-key <key>` | Authenticate with API key |
| `--create` | Create a new app before publishing |
| `--app-name <name>` | App name (requires `--create`) |
| `--workspace <id>` | Target workspace (requires `--create`) |
| `--market` | Publish to Hailer marketplace |
| `--force` | Skip confirmation prompt |
| `--yes` | Skip confirmation prompt (deprecated, use `--force`) |
| `--host <url>` | Override the target host URL |