Description
We need a developer guide that explains how to use the vtz runtime with the Vertz framework today. This is the entry point for any developer wanting to build a Vertz application.
The guide should cover the full workflow from project setup to running the dev server, without assuming prior knowledge of the runtime internals.
Sections Needed
1. Project Setup
- Minimal `package.json` structure
- Required dependencies (`@vertz/ui`, etc.)
- Directory structure (`src/`, `public/`, entry file conventions)
2. Running the Dev Server
- `vtz dev` command and flags (`--port`, `--host`, `--open`, `--no-typecheck`)
- What happens on startup (compilation, type checking, dependency pre-bundling)
- Entry file auto-detection (`entry-client.ts` > `main.tsx` > `index.tsx` > `app.tsx`)
3. Writing Components
- Vertz signal-based reactivity basics
- Using `css()` for styling
- Component file conventions
4. HMR and Fast Refresh
- How it works (automatic, no config needed)
- What triggers hot update vs full reload
- Status indicator (green/yellow/red dot)
5. Static Assets
- Serving files from `public/` directory
- Referencing assets by URL path
6. Configuration
- `.vertzrc` file (autoInstall, trustScripts, extraWatchPaths, plugin)
- TypeScript configuration (tsconfig.json)
- Type checker options (`--tsconfig`, `--typecheck-binary`)
7. Package Management
- `vtz install`, `vtz add`, `vtz remove`
- Auto-install during dev
- Trust scripts for postinstall
8. Testing
- `vtz test` command
- `vertz.config.ts` for test configuration
- Coverage, reporters, watch mode
9. Known Limitations
- CSS file imports not yet supported (use `css()` API)
- Asset imports not yet supported (reference from `public/`)
- `import.meta.env` not yet supported (use `process.env` on server side)
- Path aliases not yet supported
Acceptance Criteria
Description
We need a developer guide that explains how to use the vtz runtime with the Vertz framework today. This is the entry point for any developer wanting to build a Vertz application.
The guide should cover the full workflow from project setup to running the dev server, without assuming prior knowledge of the runtime internals.
Sections Needed
1. Project Setup
2. Running the Dev Server
3. Writing Components
4. HMR and Fast Refresh
5. Static Assets
6. Configuration
7. Package Management
8. Testing
9. Known Limitations
Acceptance Criteria