Installation

Prerequisites

Before you begin, make sure you have the following:

• Node.js v22 or later — download

Quick start

The fastest way to start a new Stratal project is with create-stratal:

npm

npm create stratal@latest my-app

yarn

yarn create stratal my-app

pnpm

pnpm create stratal my-app

The CLI will prompt you to pick a template and package manager, then scaffold the project and install all dependencies.

To skip the interactive picker, pass the --template flag directly:

npm create stratal@latest my-app --template hello-world

The generated project (hello-world template) looks like this:

my-app/
├── src/
│   ├── app.module.ts
│   ├── hello.controller.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── wrangler.jsonc

Start the dev server:

cd my-app
npm run dev

Head to Your First Worker for a walkthrough of the generated code.

Add to an existing project

If you already have a project and want to add Stratal to it, follow the steps below.

Install dependencies

Install Stratal:

npm

npm install stratal reflect-metadata

yarn

yarn add stratal reflect-metadata

pnpm

pnpm add stratal reflect-metadata

Then install the dev dependencies:

npm

npm install -D typescript wrangler @cloudflare/workers-types

yarn

yarn add -D typescript wrangler @cloudflare/workers-types

pnpm

pnpm add -D typescript wrangler @cloudflare/workers-types

TypeScript configuration

Create a tsconfig.json in the project root. Stratal uses TypeScript decorators, so both experimentalDecorators and emitDecoratorMetadata must be enabled:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "moduleResolution": "bundler",
    "strict": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "types": ["@cloudflare/workers-types/2023-07-01"]
  },
  "include": ["src/**/*"]
}

Wrangler configuration

Create a wrangler.jsonc file to configure how Cloudflare deploys your worker:

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2026-02-25",
  "compatibility_flags": ["nodejs_compat"],
  "vars": {
    "ENVIRONMENT": "development"
  },
  "kv_namespaces": [
    { "binding": "CACHE", "id": "<your-kv-namespace-id>" }
  ]
}

Key settings:

• main — points to your worker entry file.
• nodejs_compat — required so Stratal can use Node.js APIs.
• ENVIRONMENT — a variable Stratal reads at runtime.
• CACHE — a KV namespace binding used by Stratal’s built-in caching layer. You can create one with npx wrangler kv namespace create CACHE and paste the returned id into the config.

Verify the setup

Add a dev script to your package.json:

{
  "scripts": {
    "dev": "wrangler dev"
  }
}

Create the source directory:

mkdir src

Your project should now look like this:

my-worker/
├── src/
├── package.json
├── tsconfig.json
└── wrangler.jsonc

Everything is in place. Head to Your First Worker to create the entry point and build your first route.