Quick Start

Use Node.js 24+ and pnpm 11.11.0:

pnpm dlx @velajs/cli@latest new my-api
cd my-api
pnpm install
pnpm typecheck
pnpm build
pnpm dev

In another terminal:

curl http://localhost:8787
# {"message":"Hello from Vela!"}

Local development runs in Wrangler's local Workers runtime. It requires no Cloudflare login, database, authentication setup, Studio, or live-query service. If port 8787 is occupied, run pnpm dev --port 8788.

Constructor injection

The generated controller receives an AppService through its constructor:

import { Controller, Get } from '@velajs/vela';
import { AppService } from './app.service.js';

@Controller('/')
export class AppController {
  constructor(private readonly appService: AppService) {}

  @Get()
  getHello() {
    return { message: this.appService.getHello() };
  }
}

Edit the greeting in src/app.service.ts and repeat the request. Wrangler rebuilds the source and returns the updated service result.

The root module registers both classes. src/worker.ts exports createCloudflareWorker(AppModule, { envToken: ENV }), which initializes the application for each native Workers environment.

Decorator compilation

TypeScript 7 checks the source. SWC compiles legacy decorators and emits constructor parameter metadata using .swcrc. Wrangler loads the compiled JavaScript in dist/worker.js; its custom build runs SWC during local development and deployment.

Keep this build configuration when adding services. Typechecking alone does not emit the runtime metadata needed for constructor injection.

Project creation behavior

vela new my-api creates files without installing dependencies or initializing Git. Use a lowercase name starting with a letter, with letters, digits, and single hyphens, up to 63 characters. Run the command from the parent directory.

The destination may be new or an empty directory. Nonempty directories, files, symlinks, paths, scoped names, and reserved device names are rejected. There is no overwrite option.

Deploy

When you are ready to publish to your Cloudflare account:

pnpm exec wrangler login
pnpm run deploy

Use pnpm run deploy because pnpm deploy is pnpm's own workspace command.

Continue with project structure and API options. Module, controller, service, and resource generators are follow-up work; vela new currently creates one minimal Workers starter.