Enterprise-ready Temporal.io workflow orchestration for NestJS — auto-discovery, declarative decorators, typed workflow proxies, and built-in monitoring.
| Feature | What it gives you |
|---|---|
| 🔌 Seamless NestJS Integration | Native decorators + dependency injection — no boilerplate glue code |
| 🔍 Auto-Discovery | @Activity()/@ActivityMethod() classes are found and registered automatically |
| 🛡️ Type Safety | Typed workflow proxy (IWorkflowProxy<T>) — start/signal/query args and return types inferred from your workflow function |
| ❤️ Health Monitoring | Built-in /health endpoint plus programmatic getHealth()/getStatistics() |
| 🧩 Modular Architecture | Use client-only, worker-only, activity-only, schedules-only, or the full stack |
| 🧪 Testable | Fakes, activity harness, time-skipping test environment and history replay under nestjs-temporal-core/testing |
| 🏭 Production Grade | Connection pooling, multi-worker support, graceful shutdown, TLS for Temporal Cloud |
npm install nestjs-temporal-core @temporalio/client @temporalio/worker @temporalio/workflow @temporalio/common
npm install @nestjs/common @nestjs/core reflect-metadata rxjs # peer dependencies// app.module.ts
import { Module } from '@nestjs/common';
import { TemporalModule } from 'nestjs-temporal-core';
import { PaymentActivity } from './activities/payment.activity';
@Module({
imports: [
TemporalModule.register({
connection: { address: 'localhost:7233', namespace: 'default' },
taskQueue: 'my-task-queue',
worker: {
workflowsPath: require.resolve('./workflows'),
activityClasses: [PaymentActivity],
autoStart: true,
},
}),
],
providers: [PaymentActivity],
})
export class AppModule {}Inject TemporalService anywhere to start/signal/query workflows. Don't forget app.enableShutdownHooks() in main.ts for graceful cleanup.
👉 Activities, workflows, and full service examples: Getting Started guide.
This README covers only the basics. The documentation site has everything else — a landing page, guides, config reference, and a generated API reference (source in website/docs):
| Guide | Covers |
|---|---|
| For AI coding agents | Decision table, file layout, exact patterns, common errors; also llms.txt |
| Getting Started | Installation, quick start, module variants |
| Configuration | Basic/multi-worker/async/TLS setup, full options reference |
| Core Concepts | Activities, workflows, signals/queries, updates, typed workflow proxy |
| Advanced Configuration | Interceptors, gRPC compression, worker versioning, standalone activities, schedule lifecycle |
| Advanced Usage | Activity retry policies, workflow testing |
| Best Practices | Do's and don'ts for workflows, activities, config, error handling, testing |
| Testing | Fakes, activity harness, test environment with time skipping, history replay |
| Error Handling | TemporalClientError, opt-in errorMapping, @NonRetryable() |
| Bundling | workflowsPath, cached autoBundle, prebuilt bundles, Docker/Nx recipes |
| Observability | SDK logs, correlation ids, OpenTelemetry, metrics |
| Security | Payload encryption, TLS checks, health hardening |
| Health Monitoring | Built-in health module, custom health checks |
| Troubleshooting | Common issues, debug mode, getting help |
| Migration Guide | Upgrading across versions and SDK bumps, and moving from nestjs-temporal |
| API Reference | Generated from source (TSDoc) |
Node.js >= 20.3.0 • NestJS 9–12 • Temporal Server >= 1.20.0
NestJS 12 is ESM-only. Loading it from this package's CommonJS build needs Node 20.19+ or 22.12+ (require(esm)). If you test with Jest, see Testing with NestJS 12. The optional nestjs-temporal-core/terminus entry needs @nestjs/terminus 11 or 12.
(on Node 16/18, pin @temporalio/* to ^1.15.0 and stay on this package's previous minor)
Contributions welcome — see CONTRIBUTING.md. Questions or bugs: GitHub Issues • Discussions • Changelog.
MIT © — see LICENSE.
⭐ Star us on GitHub if you find this project helpful!
