Higgsfield Websites

# Higgsfield website builder (CLI) — three product types, three flows

You drive the whole lifecycle through the **Higgsfield CLI** (`higgsfield website …`), then edit code on the local filesystem with `git` + `bun`. You are building ONE per-website Cloudflare Worker: a **React 19 + TanStack Start** app, **server-rendered (SSR)**, deployed as a single Worker at the product's own subdomain. The project lives in **`app/`** — run every `bun`/build command from there.

## The three types — and the REQUIRED `--type` on create

`higgsfield website create` requires `--type`, and it is the **USER'S choice** — when the request doesn't make it obvious, ask the user before creating (one question, up front):

- **`--type website`** — a standalone product with NO Higgsfield integration and **NO AI generation of any kind** (no image/video/audio/text generation — not via Higgsfield, and not via some other provider): no "Sign in with Higgsfield", no requests to Higgsfield, no fnf SDK. Every website gets a fully independent brand: own palette, type, and chrome from a design brief, custom Tailwind/CSS only — never import `@higgsfield/quanta/*` or use q-prefixed tokens anywhere, and no "Powered by / Built on Higgsfield" badges or mentions in page content. The user's brand is the only brand on the page. ```bash higgsfield website create --type website ``` - **`--type app`** — a product tightly integrated with Higgsfield: its users Sign in with Higgsfield and generate images/videos through the fnf SDK (the full auth + D1 contract applies). An app must look and feel like a Higgsfield product: UI built with **Quanta** (`references/quanta-design.md`) — and, for anything Quanta lacks, your own component built from Quanta primitives (never a third-party UI library) — starting from a standard app layout (`references/app-layouts.md`). Quanta and the app layouts are app-only — never applied to a `--type website` build. The independent-brand rule and the wow pipeline (`design-taste-frontend`, boards, wow catalog) are the website path; apps never get a custom brand — Quanta is the brand. ```bash higgsfield website create --type app ```

- **`--type game`** — a browser game: realtime multiplayer rooms on the game template, where the game itself is six pure functions in `app/src/logic.js` and the platform already owns sockets, rooms and persistence. Requires a **game genre** as `--category` (`arcade`, `puzzle`, `shooter`, …, from `higgsfield website categories`) and takes **no** `--template` — a game scaffolds from the only template it can use. Single-player counts: set `minPlayers: 1`. See `references/game-flow.md`. ```bash higgsfield website create --type game --category arcade ```

**Generation is ALWAYS an app.** Any product that generates images, video, audio, or other AI media runs on Higgsfield — build it as `--type app` (Sign in with Higgsfield, generation on the user's Higgsfield credits). NEVER offer the user an option to "bring your own image/video API" or plug in their own generation key for a website — that path does not exist. `--type website` is ONLY for sites with no generation and no tie to Higgsfield or any other generation service. (A website may still use ordinary non-generation third-party APIs — payments, maps, email — with the user's own keys; that is unrelated to this rule.)

Quick tells: "landing page / portfolio / marketing site / SaaS with its own users, no AI generation" → website. "generates images/video/audio, or anything with Higgsfield models, credits, or generation history" → app. "something you play — a game, multiplayer or single-player" → game.

Games moved onto this pipeline from a separate engine that is being retired. The `higgsfield game …` commands are gone: a game is created, deployed and published exactly like a website. Any doc saying otherwise is out of date.

## Always set a subdomain on create

`higgsfield website create` takes an optional `--subdomain` — it becomes the site's slug, so the live URL is `<subdomain>.<host>`. **Always set it:** pick one from the product's name or purpose; only omit it (which yields a random slug) if the user explicitly wants a random one. Rules for a good subdomain:

- **More than 4 characters** — short single words are reserved, so go a bit longer. - **Memorable** — derive it from the product name/purpose (e.g. `lumen-notes`, `pixelforge`), not a random string. - **Allowed characters only** — lowercase letters, digits, and single hyphens (DNS-safe). No spaces, underscores, uppercase, or leading/trailing hyphens.

A few reserved labels (e.g. `api`, `www`, `app`) and already-taken subdomains are rejected — if that happens, try a close variant.

## Prerequisites

1. If `higgsfield` is not on `$PATH`, install it: ```bash curl -fsSL https://raw.githubusercontent.com/higgsfield-ai/cli/main/install.sh | sh ``` 2. If `higgsfield account status` reports `Session expired` / `Not authenticated`,