For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/introduction/supported-apps.md.

Supported Apps

tsdevstack supports multiple application types within a single monorepo.

App types

NestJS Services

Backend API services built with NestJS. These are the core of most tsdevstack projects.

npx tsdevstack add-service --name payments-service --type nestjs

Services get:

  • Auto-generated Kong gateway routes
  • OpenAPI documentation from decorators
  • Generated HTTP client libraries with DTOs
  • Database connections (Postgres, Redis)
  • Framework authentication

Workers

Workers process background jobs using BullMQ and Redis. They live inside a service's codebase and share its database access and dependencies, but run as their own process, which always runs.

A worker has three parts: a processor that handles jobs, a producer (any service code) that enqueues them, and a module that wires everything together.

Queue processors run only in workers, never inside a service. A service on GCP or Azure can scale to zero, and on GCP a service that does gets CPU only while it handles a request. A processor inside it would stop until the next request. A worker never stops.

A worker needs these files in its service. register-detached-worker (below) creates whichever are missing, and the two scripts; the processors are yours:

apps/auth-service/
├── tsconfig.worker.json   # Local build of the worker (see below)
└── src/
    ├── main.ts            # HTTP service entry point
    ├── app.module.ts      # Service module
    ├── worker.ts          # Worker entry point
    └── worker.module.ts   # Worker module (no HTTP, just processors)

And two scripts in the service's package.json:

"start-worker:dev": "nest start --entryFile worker --watch --path tsconfig.worker.json",
"start-worker": "node dist/worker.js"

worker.ts calls startWorker() from nest-common, which bootstraps a NestJS application context (no HTTP server) with a health endpoint for container orchestration:

// worker.ts
import { startWorker } from '@tsdevstack/nest-common';
import { WorkerModule } from './worker.module';

void startWorker(WorkerModule);
// worker.module.ts
@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true }),
    SecretsModule,
    ObservabilityModule.forRoot(),
    NotificationModule,
    BullConfigModule.forRoot(),
    BullModule.registerQueue({ name: 'notifications' }),
  ],
  providers: [NotificationProcessor],
})
export class WorkerModule {}

npm run dev starts every service and every worker. Locally the worker compiles into its own folder, so the worker and its service don't delete and rewrite each other's dist:

// tsconfig.worker.json
{
  "extends": "./tsconfig.build.json",
  "compilerOptions": {
    "outDir": "./node_modules/.cache/worker-dev"
  }
}

In the cloud, a worker runs once you register it as a detached worker. The framework then deploys a separate container from the same Docker image, with node dist/worker.js as the entrypoint:

npx tsdevstack register-detached-worker --name auth-worker --base-service auth-service

It also creates the worker's files and scripts that its service doesn't have yet. It never overwrites a file, and it lists what it created and what it left alone. A new worker.module.ts has no queues: register each queue there with BullModule.registerQueue and add its processor to providers.

Detached workers get their own Cloud Run / ECS / Container Apps instance with CPU always allocated. Like services, workers are configurable in infrastructure.json: you can set minInstances, maxInstances, cpu, and memory. Workers run at least 1 instance (they must always be running to poll Redis queues).

The auth template comes with a worker, auth-worker, which sends the auth service's emails.

Enqueueing jobs

Any service code can dispatch jobs by injecting a queue:

@InjectQueue('notifications') private notificationQueue: Queue

// Later:
await this.notificationQueue.add('send-email', { to, subject, html });

The queue name must be registered in both the producer's module and the worker's module.

Next.js Frontend

Server-rendered React applications built with Next.js.

npx tsdevstack add-service --name web-app --type nextjs

SPA Applications

Single-page applications built with any framework that uses Rsbuild.

npx tsdevstack add-service --name admin-dashboard --type spa

The framework executes the Rsbuild build after registering the app, so any Rsbuild-compatible setup works.

Monorepo structure

All apps live in a single monorepo:

my-project/
├── apps/
│   ├── auth-service/
│   │   └── src/
│   │       ├── app.module.ts
│   │       ├── main.ts
│   │       ├── worker.module.ts
│   │       └── worker.ts
│   ├── offers-service/
│   └── web-app/
├── packages/
│   ├── auth-service-client/   # Generated HTTP client + DTOs
│   └── offers-service-client/ # Generated HTTP client + DTOs
└── infrastructure/

Generated HTTP clients

When you build a NestJS service, tsdevstack generates a typed HTTP client package:

packages/
├── auth-service-client/       # Generated from auth-service
└── offers-service-client/     # Generated from offers-service

These clients have separate exports for different use cases:

In frontend apps - import as an HTTP client:

import { AuthServiceClient } from '@shared/auth-service-client';

const client = new AuthServiceClient();
const user = await client.users.getById(userId);

In NestJS services - import the HTTP client and/or the DTOs directly:

// Use as HTTP client for service-to-service calls
import { AuthServiceClient } from '@shared/auth-service-client';

// Or import DTOs for type-safe request/response handling
import { CreateUserDto, UserResponseDto } from '@shared/auth-service-client/dto';

This eliminates the need for separate shared type packages - all types flow from the OpenAPI spec.