create-tealina

The scaffold for Tealina. It generates a Node API service that compiles and starts right away, where files are routes, and handler type annotations are the single source of truth for routes, documentation, and client types.

pnpm create tealina my-app
npm create tealina@latest my-app
bun create tealina my-app

Arguments

Argument	Purpose
--template express|fastify|koa	Skip framework selection
--web	Also generate packages/web, a minimal Vite frontend
--integrate	Write INTEGRATION.md at the project root, an integration playbook for AI assistants

When both a project name and --template are given, the scaffold is fully non-interactive:

pnpm create tealina my-app --template fastify --web

If the target directory is not empty, the scaffold asks whether to delete it; for non-interactive runs, use a new or empty directory.

Environment Requirements

• Node ≥ 22 (defaults to 24, which is what the generated project's .nvmrc records).
• TypeScript >=5.6.2 <7. The generated tealina command needs the TypeScript Compiler API; the current latest version of TypeScript 7, 7.0.2, does not yet provide that API and is not supported.
• pnpm 12.x for pnpm install — the generated package.json declares engines.pnpm, and pnpm-workspace.yaml uses allowBuilds, which earlier pnpm versions ignore. The scaffold itself does not install dependencies; it only prints the command for the first run.

Generated Contents

my-app/
  package.json            scripts delegate to the three backend packages
  pnpm-workspace.yaml     backend/* and packages/*
  INTEGRATION.md          only with --integrate, an integration playbook for AI assistants
  backend/
    core/                 contract layer
    api-v1/               one API version
    server/               host
  packages/web/           only with --web

• For the responsibilities of core, api-v1, and server, see Project Structure.
• Default endpoints: GET /health, POST /login (public), POST /article (requires authentication, with a request body and a typed response).
• No frontend by default; --web creates packages/web.
• No database or Prisma layer by default.
• Error handling and 404 handling are not included; unknown routes and thrown errors go to the framework's default behavior.
• The INTEGRATION.md written by --integrate covers two integration shapes: mounting only core + api-v1 onto an existing Express/Fastify/Koa instance, or merging all three backend packages into an existing monorepo. It is not part of the runtime and can be deleted once the merge is done. For the full explanation, see Integrating into an Existing Project.

Root Scripts

Command	Purpose
pnpm dev	Build core and api-v1, then start all watchers in parallel
pnpm build	Build all packages
pnpm start	Run the compiled server
pnpm check	Format, lint, and type-check (Vite+)
pnpm fmt / pnpm lint	Run only half of check
pnpm -F api-v1 run create <method> <path>	Create a handler stub
pnpm -F api-v1 align	Rebuild the generated index.*
pnpm -F api-v1 gdoc	Regenerate API documentation

Each package exposes its own subset: core has dev / build, server additionally has start, and web (with --web) has dev / build / preview.

Toolchain of the Generated Project

The generated pnpm-workspace.yaml comes with its own dependency catalog, aliasing vite to the @voidzero-dev/vite-plus-core that matches vite-plus 1.3.0. This is the project's own version pin; upgrading the global vp does not change it.

Before Deployment

• After pnpm -F server build, run with pnpm start.
• The documentation JSON file is generated by gdoc and is not edited by hand; when a page reports the file is missing, run gdoc first.
• The auth guard is a placeholder implementation; replace the TODO in backend/core/src/access/verifyToken.ts.