# {{projectName}}

A SpecVerse **frontend-only** starter — React SPA that talks to an
external API. Use this for JAMstack apps, frontend-first development,
or any project where the backend lives somewhere else.

## Quick start

```bash
# 1. Generate code and install dependencies
npm run setup

# 2. Point the app at your API
#    Edit generated/code/.env and set VITE_API_BASE_URL

# 3. Start the dev server
npm run dev               # http://localhost:5173

# 4. (Optional) run the example end-to-end test
npm run test:e2e
```

## Project structure

```
{{projectName}}/
├── specs/
│   └── main.specly              # Your UI specification — edit this
├── manifests/
│   └── implementation.yaml      # Technology stack config
├── tests/
│   └── e2e/                     # Hand-written Playwright tests
│       ├── example.spec.ts
│       └── README.md
├── playwright.config.ts         # Playwright config for tests/e2e/
├── tsconfig.json                # TypeScript config (for tests/)
├── generated/
│   └── code/                    # Generated React app — do NOT edit by hand
│       ├── src/                 # Components, views, hooks
│       └── index.html           # HTML entry point
├── docs/                        # Generated docs and diagrams
├── CLAUDE.md                    # AI assistant guide
└── package.json
```

## Commands

| Command | Description |
|---|---|
| `npm run validate` | Validate the spec |
| `npm run infer` | Run AI inference (writes `specs/inferred.specly`) |
| `npm run build` | Validate + realize (regenerates `generated/code/`) |
| `npm run setup` | Build + install deps |
| `npm run dev` | Start the Vite dev server |
| `npm run start` | Build + preview the production bundle |
| `npm run test:e2e` | Run hand-written Playwright tests in `tests/e2e/` |
| `npm run gen:docs` | Generate documentation under `docs/` |
| `npm run gen:diagrams` | Generate Mermaid diagrams under `docs/diagrams/` |
| `npm run clean` | Remove `generated/code/` and `specs/inferred.specly` |

## API configuration

Point the SPA at your backend by setting environment variables in
`generated/code/.env`:

```env
VITE_API_BASE_URL=https://your-api.example.com
VITE_API_PREFIX=/api
```

`.env` is regenerated on `npm run build`, so commit your overrides
to `manifests/implementation.yaml` (under `environments.development.api`)
if you want them to persist across rebuilds.

## What ships in the starter spec

A `Product` model with list, detail, and form views. Replace it with
your domain — the realize engine generates React components from
whatever you put in `specs/main.specly`.

## Technology stack

| Layer | Technology |
|---|---|
| Framework | React 18 + TypeScript |
| Build tool | Vite |
| Data layer | React Query (via `@specverse/runtime`) |
| Styling | Tailwind CSS |
| Tests (auto-generated) | Playwright contract tests under `generated/code/tests/contract/` |
| Tests (hand-written) | Playwright behavioral tests under `tests/e2e/` |

## Prerequisites

- **Node.js 20+**
- **`@specverse/self`** installed globally:
  ```bash
  npm install -g @specverse/self
  ```

## Iterate

1. Edit `specs/main.specly`
2. `npm run validate`
3. `npm run build`
4. The Vite dev server hot-reloads automatically

## Learn more

- [SpecVerse User Guide](https://github.com/SpecVerse/specverse-self/blob/main/docs/guides/SPECVERSE-USER-GUIDE.md)