Quickstart

Create and run a new Taser.js project in under a minute with create-taserjs. Choose your favorite server adapter, schema validator, ORM, and logger.

The quickest way to get started with Taser.js is using the official create-taserjs scaffolding tool. It generates a pre-configured, production-ready project with TypeScript, hot-reloading, route watching, and your choice of tools.

Prerequisites

Before creating a project, make sure your development environment meets these requirements:

Node.js: Version 20.19.0 or higher
Package Manager: npm, pnpm, yarn, or bun
TypeScript: Version 5.0 or higher

Create a New Project

Run the Scaffolding Command

Run the interactive initializer in your terminal:

pnpm create taserjs@latest

Choose Your Stack

The interactive wizard will guide you through selecting your preferred tools:

Project Name: Enter a directory name (for example, my-taser-api).
Host Framework:
- None (Standalone): Pure Taser.js with high-performance virtual routing and zero host overhead (default).
- Hono: Lightweight web standard framework for Node, Bun, Deno, and edge runtimes.
- Express: Battle-tested Node.js web framework with pass-through routing.
- Fastify: High-throughput Node.js framework with pass-through routing.
Deployment Target / Preset:
- Node Server (node-server, node-cluster): Standard Node.js environments (default: node-server).
- Standalone Vite (none): Direct vite build with production serve shim without Nitro.
- Serverless & Edge: cloudflare-module, vercel, aws-lambda, netlify.
- Runtimes: bun, deno-server, deno-deploy.
Runtime Override (Optional):
- Override runtime for self-hosted targets (node, bun, or preset default).
Database / ORM (Optional):
- Drizzle, Prisma, Kysely, or None (supports sqlite, postgres, or mysql drivers).
Logger (Optional):
- Pino, Winston, or standard Console.
Schema Validator (Optional):
- Zod: TypeScript-first schema declaration and validation.
- ArkType: TypeScript-native syntax with runtime performance.
- Valibot: Modular, lightweight, tree-shakeable schema library.

Non-Interactive Scaffolding

You can pass CLI flags directly for automated or CI environments:

pnpm create taserjs@latest my-api \
  --framework none \
  --preset node-server \
  --db drizzle:postgres \
  --validator zod \
  --logger pino \
  -y

CLI Flags Reference

Flag	Description	Values / Syntax	Default
`--framework`	Host server framework	`none`, `hono`, `express`, `fastify`	`none`
`--preset`, `-p`	Deployment preset (Nitro target or `none`)	`none`, `node-server`, `node-cluster`, `bun`, `deno-server`, `deno-deploy`, `cloudflare-module`, `vercel`, `aws-lambda`, `netlify`	`node-server`
`--runtime`	Explicit runtime override (for self-hosted presets)	`node`, `bun`, `deno`	Implied by preset
`--db`	Database ODM and optional driver (`odm:driver`)	`drizzle`, `prisma`, `kysely` (optionally `:postgres`, `:sqlite`, `:mysql`)	None (omitted = no database)
`--validator`	Schema validation library	`zod`, `arktype`, `valibot`	None
`--logger`	Structured logger integration	`pino`, `winston`	None
`-y`, `--yes`	Non-interactive mode using defaults for omitted flags	`boolean`	`false`
`--noInstall`	Skip automatic package installation	`boolean`	`false`
`--json` (with name)	Output scaffold result metadata as JSON	`boolean`	`false`
`--json` (without name)	Output capability catalog as JSON	`boolean`	`false`

Database Flag (`--db`) Semantics

The --db flag controls database ORM and driver installation. The behavior depends on whether the flag is omitted, passed without a driver suffix, or passed with a full odm:driver specification:

Invocation Syntax	ODM Configured	Driver Configured	Scaffolding Behavior
Omitted entirely	None	None	No database packages, schemas, or connection clients are installed or generated.
`--db drizzle`	`drizzle`	`sqlite` (default)	Defaults driver to `sqlite`. Generates SQLite schema and client files.
`--db prisma`	`prisma`	`sqlite` (default)	Defaults driver to `sqlite`. Generates SQLite Prisma schema.
`--db kysely`	`kysely`	`sqlite` (default)	Defaults driver to `sqlite`. Generates SQLite Kysely database client.
`--db drizzle:postgres`	`drizzle`	`postgres`	Installs PostgreSQL driver (`pg`) and generates PostgreSQL Drizzle schema.
`--db drizzle:mysql`	`drizzle`	`mysql`	Installs MySQL driver (`mysql2`) and generates MySQL Drizzle schema.

When --db is omitted, the scaffolded project does not include database dependencies or config files. When a database ODM is provided without a colon and driver suffix (for example, --db drizzle), create-taserjs automatically selects sqlite as the default driver.

JSON Flag (`--json`) Output Schemas

The --json flag operates in two distinct modes depending on whether a project name is supplied:

Mode	Command Example	Output Purpose	Output Destination
Scaffold Metadata	`pnpm create taserjs@latest my-api --json -y`	Emits resolved project configuration metadata	`stdout`
Capability Catalog	`pnpm create taserjs@latest --json`	Emits available frameworks, presets, runtimes, and add-ons	`stdout`

1. Scaffold Result Metadata (`--json` with Project Name)

When a project name is provided, --json suppresses terminal animations and prints the scaffolded project configuration as JSON:

pnpm create taserjs@latest my-api \
  --framework none \
  --preset node-server \
  --db drizzle:postgres \
  --validator zod \
  --logger pino \
  --json -y

Output (Scaffold Metadata JSON)

{
  "projectName": "my-api",
  "targetDir": "/path/to/my-api",
  "framework": "none",
  "preset": "node-server",
  "db": "drizzle",
  "driver": "postgres",
  "logger": "pino",
  "validator": "zod"
}

2. Capability Catalog (`--json` without Project Name)

When invoked without a project name, --json outputs the machine-readable capabilities catalog describing all supported frameworks, deployment presets, runtime environments, databases, loggers, and validators:

pnpm create taserjs@latest --json

Output (Capabilities Catalog JSON)

{
  "frameworks": [
    "none",
    "hono",
    "express",
    "fastify"
  ],
  "deployTargets": [
    "none",
    "node-server",
    "node-cluster",
    "bun",
    "deno-server",
    "deno-deploy",
    "cloudflare-module",
    "vercel",
    "aws-lambda",
    "netlify"
  ],
  "runtimes": [
    "node",
    "bun",
    "deno"
  ],
  "db": {
    "odms": [
      "drizzle",
      "prisma",
      "kysely"
    ],
    "drivers": [
      "sqlite",
      "postgres",
      "mysql"
    ],
    "defaultDriver": "sqlite"
  },
  "loggers": [
    "pino",
    "winston"
  ],
  "validators": [
    "zod",
    "arktype",
    "valibot"
  ]
}

Start the Development Server

Navigate to your new project directory, install dependencies, and start the development server:

cd my-taser-api
pnpm install
pnpm dev

The development server starts with Vite. Route changes inside src/routes/ are updated virtually with instant HMR and ambient TypeScript definitions written to .taser/types/.

Project Structure Overview

A freshly scaffolded Taser.js project contains a clean, modern layout:

package.json

tsconfig.json

vite.config.ts

taser.ts

context.ts

$.ts

/*

index.get.ts

/

health.get.ts

/health

Key Files Explained

vite.config.ts: Connects the taser() plugin from @taserjs/router-plugin/vite and nitro() for zero-config builds (or pure Vite in standalone none preset).
nitro.config.ts (conditional): Generated when targeting non-default deployment presets (e.g. cloudflare-module, vercel, aws-lambda, netlify). Omitted for default node-server and standalone none.
src/server.ts / src/server.node.ts (conditional): Generated when a host framework is configured (src/server.ts for Hono, src/server.node.ts for Express or Fastify).
src/taser.ts: Configures the createTaserApp() instance, error boundaries (.onError()), response validation, and context binding.
src/context.ts: Defines application singletons (database, logger, external services) and request-scoped context.
src/routes/: Contains your API endpoints (index.get.ts, health.get.ts) and root layout middleware ($.ts).
.taser/: Contains auto-generated ambient TypeScript types (.taser/types/) so your editor provides full route autocomplete.

Add Your First Route

To create a new endpoint, add a file in the src/routes/ directory.

Create src/routes/hello.get.ts:

src/routes/hello.get.ts

import { json } from "@taserjs/router/reply";
import { t } from "@taserjs/router";

export default t.get("/hello").handler(() => {
  return json({
    message: "Hello from Taser.js!",
    timestamp: new Date().toISOString(),
  });
});

Save the file. Vite hot-reloads the new route immediately without restarting the dev server.

Test your new endpoint in another terminal or browser:

curl http://localhost:3000/hello

Response:

{
  "message": "Hello from Taser.js!",
  "timestamp": "2026-08-25T00:00:00.000Z"
}

Automatic Boilerplate Generation

When you create a new empty route file (e.g. touch src/routes/users/$id.get.ts), Vite or npx taser generate automatically fills it with type-safe starter boilerplate.

Prerequisites

Create a New Project

Run the Scaffolding Command

Choose Your Stack

CLI Flags Reference

Database Flag (`--db`) Semantics

JSON Flag (`--json`) Output Schemas

1. Scaffold Result Metadata (`--json` with Project Name)

2. Capability Catalog (`--json` without Project Name)

Start the Development Server

Project Structure Overview

Key Files Explained

Add Your First Route

Next Steps

Manual Installation

Migration Guide

Core Concepts

File-Based Routing

Validation Guide

On this page