Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TemporalModule
✓ import { TemporalModule } from 'nestjs-temporal';
✗ const TemporalModule = require('nestjs-temporal');
Main module for configuring Temporal client and worker within NestJS. CommonJS `require` is incorrect in a typical NestJS TypeScript setup.
Activities, Activity
✓ import { Activities, Activity } from 'nestjs-temporal';
✗ import Activities from 'nestjs-temporal';
Decorators for marking a NestJS provider as a Temporal activity collection (`@Activities`) and its methods as individual activities (`@Activity`). These are named exports.
InjectTemporalClient
✓ import { InjectTemporalClient } from 'nestjs-temporal';
✗ import { TemporalClient } from 'nestjs-temporal';
Decorator for injecting the `@temporalio/client`'s `WorkflowClient` into NestJS services or controllers. The symbol for the decorator is `InjectTemporalClient`, not `TemporalClient`.
WorkflowClient
✓ import { WorkflowClient } from '@temporalio/client';
✗ import { WorkflowClient } from 'nestjs-temporal';
The `WorkflowClient` class is imported directly from the `@temporalio/client` SDK, not from `nestjs-temporal`. `nestjs-temporal` provides the *injection mechanism* for it.
This quickstart demonstrates how to set up a basic NestJS application using `nestjs-temporal` to define and execute a Temporal workflow. It includes registering a Temporal worker and client, defining an activity service with a greeting activity, creating a simple workflow that calls the activity, and exposing an API endpoint to start the workflow.
/* src/main.ts */
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
async function bootstrap() {
const app = await NestFactory.create(AppModule);
await app.listen(3000);
}
bootstrap();
/* src/app.module.ts */
import { Module } from '@nestjs/common';
import { TemporalModule } from 'nestjs-temporal';
import { AppController } from './app.controller';
import { GreetingActivity } from './activities/greeting.activity';
@Module({
imports: [
TemporalModule.registerWorker({
workerOptions: {
taskQueue: 'default',
// Ensure this path is correct for your compiled JS output in production
workflowsPath: require.resolve('./temporal/example.workflow'),
},
}),
TemporalModule.registerClient(),
],
controllers: [AppController],
providers: [GreetingActivity],
})
export class AppModule {}
/* src/activities/greeting.activity.ts */
import { Injectable } from '@nestjs/common';
import { Activities, Activity } from 'nestjs-temporal';
@Injectable()
@Activities()
export class GreetingActivity {
@Activity()
async greeting(name: string): Promise<string> {
return 'Hello ' + name;
}
}
export interface IGreetingActivity {
greeting(name: string): Promise<string>;
}
/* src/temporal/example.workflow.ts */
import { proxyActivities } from '@temporalio/workflow';
import { IGreetingActivity } from '../activities/greeting.activity';
const { greeting } = proxyActivities<IGreetingActivity>({
startToCloseTimeout: '1 minute',
});
export async function example(name: string): Promise<string> {
return await greeting(name);
}
/* src/app.controller.ts */
import { Controller, Post, Get } from '@nestjs/common';
import { WorkflowClient } from '@temporalio/client';
import { InjectTemporalClient } from 'nestjs-temporal';
@Controller('temporal')
export class AppController {
constructor(
@InjectTemporalClient() private readonly temporalClient: WorkflowClient,
) {}
@Post('greet')
async startGreetingWorkflow() {
const workflowId = `greeting-workflow-${Date.now()}`;
const handle = await this.temporalClient.start('example', {
args: ['Temporal User'],
taskQueue: 'default',
workflowId,
});
console.log(`Started workflow ${workflowId}`);
return { workflowId: handle.workflowId, result: await handle.result() };
}
@Get('health')
getHealth() {
return { status: 'ok' };
}
}
Errors
Common errors & fixes
Error: WORKFLOW_CODE_LOAD_ERROR: Failed to load workflow from path:...
The `workflowsPath` specified in `TemporalModule.registerWorker` points to a non-existent or uncompiled file.
fixEnsure `workflowsPath` correctly references the compiled JavaScript file of your workflow (e.g., `dist/temporal/workflow.js`) and that the file exists in the specified location after build.
Nest can't resolve dependencies of the GreetingActivity (?). Please make sure that the argument at index [0] is available in the AppModule context.
A Temporal activity provider (e.g., `GreetingActivity`) was not properly registered as a NestJS provider.
fixAdd the activity class (e.g., `GreetingActivity`) to the `providers` array of the NestJS module where it is used, and ensure it has the `@Injectable()` decorator.
Error: Could not connect to Temporal server at 'localhost:7233'. Is the server running?
The `WorkflowClient` or `Worker` failed to establish a connection with the Temporal server, often due to the server being down, incorrect host/port, or network issues.
fixVerify that your Temporal server is running and accessible. Check the `connection` configuration in `TemporalModule.registerClient` or `registerWorker` options to ensure correct host and port.
Error: Workflow 'example' is not registered.
The worker connected to the Temporal server has not loaded the workflow definition for the 'example' workflow, or the `taskQueue` for the client and worker do not match.
fixConfirm that the `workflowsPath` in `TemporalModule.registerWorker` correctly points to the workflow file and that the workflow function (e.g., `example`) is exported. Also, ensure the `taskQueue` specified for both `TemporalModule.registerWorker` and `client.start` are identical.
Audit
Dependencies
@nestjs/commonrequiredCore NestJS dependency for modules, providers, and decorators.
@nestjs/corerequiredCore NestJS dependency for application bootstrapping and module resolution.
@temporalio/activityrequiredTemporal SDK component for defining activities.
@temporalio/clientrequiredTemporal SDK component for interacting with the Temporal service as a client.
@temporalio/commonrequiredTemporal SDK common types and utilities.
@temporalio/workerrequiredTemporal SDK component for running worker processes that execute workflows and activities.
@temporalio/workflowrequiredTemporal SDK component for defining workflow logic.