Skip to content
This repository was archived by the owner on Apr 3, 2026. It is now read-only.

docs: Getting started guide for Vertz framework developers #43

@viniciusdacal

Description

@viniciusdacal

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

  • A developer can go from zero to running dev server by following the guide
  • All commands shown in the guide are tested and work
  • Known limitations are clearly documented with workarounds
  • Guide lives in a discoverable location (README or docs/)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions