# frontend-cli

`frontend-cli` is a development and build tool for creating Orchard front-ends.

## Usage

Always prefix commands with your package manager (`pnpm`, `npm`, or `yarn`) to ensure the CLI runs in the correct working directory:

```
pnpm frontend <command> [options]
```

## Commands

Commands are provided by plugins. Every command accepts `--debug` for verbose output.

---

### `init`

Checks for available updates to `@theorchard` and `@orchard` packages. Also runs automatically before `dev`.

```
pnpm frontend init [--debug]
```

| Option    | Description              |
| --------- | ------------------------ |
| `--debug` | Output debug information |

---

### `build`

Builds production bundles (Vite plugin).

```
pnpm frontend build [options]
```

| Option                 | Default           | Description                                             |
| ---------------------- | ----------------- | ------------------------------------------------------- |
| `--no-legacy`          | —                 | Do not produce legacy bundles to support older browsers |
| `--public-path <path>` | `CDN_URL` env var | Path to the location where the bundles are hosted       |
| `-a, --analyze`        | —                 | Analyze bundle output                                   |
| `--debug`              | —                 | Output debug information                                |

---

### `dev` / `start`

Starts the development server (Vite plugin). `start` is an alias for `dev`.

```
pnpm frontend dev [options]
pnpm frontend start [options]
```

| Option                      | Default | Description                               |
| --------------------------- | ------- | ----------------------------------------- |
| `--clear`                   | —       | Clear cache before run                    |
| `--html, --htmlFile <name>` | —       | HTML file to load                         |
| `--open`                    | —       | Open browser on start                     |
| `--https`                   | —       | Use HTTPS                                 |
| `--port <port>`             | `8080`  | Server port (overrides `CLI_SERVER_PORT`) |
| `--debug`                   | —       | Output debug information                  |

---

### `preview`

Previews a production build locally (Vite plugin).

```
pnpm frontend preview [options]
```

| Option    | Description              |
| --------- | ------------------------ |
| `--open`  | Open browser on start    |
| `--debug` | Output debug information |

---

### `i18n:sync`

Uploads compiled translations to POEditor, then downloads all translations (i18n plugin).

```
pnpm frontend i18n:sync [--debug]
```

| Option    | Description              |
| --------- | ------------------------ |
| `--debug` | Output debug information |

Configuration is read from `frontend.json` or a cosmiconfig source (see [POEditor support](docs/locales.md)).

---

### `i18n:download`

Downloads translations from POEditor without uploading local terms (i18n plugin).

```
pnpm frontend i18n:download [--debug]
```

| Option    | Description              |
| --------- | ------------------------ |
| `--debug` | Output debug information |

---

### `i18n:watch`

Watches i18n input paths and recompiles translations on changes (i18n plugin).

```
pnpm frontend i18n:watch [--debug]
```

| Option    | Description              |
| --------- | ------------------------ |
| `--debug` | Output debug information |

---

## Plugin Configuration

Commands are loaded from plugins defined in `frontend.json`. Default plugins when no `plugins` key is present: `["i18n", "webpack"]`.

To use the Vite plugin, set the `plugins` array in your `frontend.json`:

```json
{
    "plugins": ["i18n", "vite"]
}
```

---

## Environment Variables

Variables are loaded and merged in this order: environment → `.env` → `.env.[NODE_ENV]`.

| Variable              | Default                     | Description                                    |
| --------------------- | --------------------------- | ---------------------------------------------- |
| `CDN_URL`             | `https://cdn.theorchard.io` | Base URL for CDN-hosted static assets          |
| `CLI_SERVER_PORT`     | `8080`                      | Port used when running the dev server          |
| `CLI_SERVER_HOST`     | `localhost`                 | Host used when running the dev server          |
| `POEDITOR_PROJECT_ID` | —                           | Project ID for the associated POEditor project |
| `POEDITOR_API_TOKEN`  | —                           | API token for accessing the POEditor account   |

---

## Further Reading

-   [Using the CLI](docs/usage.md)
-   [Using environment variables](docs/configuration.md)
-   [POEditor support](docs/locales.md)