CommonJS (CJS)

Learn about running Sentry in an CJS application.

Most node applications today are either written in CommonJS (CJS), or compiled to CJS before running them. CommonJS uses require() to load modules. Our recommended installation method when using CommonJS is to require the instrument.js file at the top of your application.

You need to create a file named instrument.js that imports and initializes Sentry:

instrument.ts
Copied
const Sentry = require("@sentry/nestjs");
//  profiling
const { nodeProfilingIntegration } = require("@sentry/profiling-node");
//  profiling

// Ensure to call this before requiring any other modules!
Sentry.init({
  dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
  //  profiling
  integrations: [
    // Add our Profiling integration
    nodeProfilingIntegration(),
  ],
  //  profiling
  //  performance

  // Set tracesSampleRate to 1.0 to capture 100%
  // of transactions for tracing.
  // We recommend adjusting this value in production
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#tracesSampleRate
  tracesSampleRate: 1.0,
  //  performance
  //  profiling

  // Set profilesSampleRate to 1.0 to profile 100%
  // of sampled transactions.
  // This is relative to tracesSampleRate
  // Learn more at
  // https://docs.sentry.io/platforms/javascript/guides/nestjs/configuration/options/#profilesSampleRate
  profilesSampleRate: 1.0,
  //  profiling
});

You need to require or import the instrument.js file before requiring any other modules in your application. This is necessary to ensure that Sentry can automatically instrument all modules in your application:

Make sure to import the instrument.ts file before any other modules:

main.ts
Copied
// Import this first!
import "./instrument";


// Now import other modules
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}

bootstrap();

Afterward, add the SentryModule as a root module to your main module:

app.module.ts
Copied
import { Module } from "@nestjs/common";

import { SentryModule } from "@sentry/nestjs/setup";

import { AppController } from "./app.controller";
import { AppService } from "./app.service";

@Module({
  imports: [

    SentryModule.forRoot(),

    // ...other modules
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

By default, Sentry only captures unhandled exceptions that aren't caught by an error filter. Additionally, HttpExceptions (including derivatives) aren't captured by default because they mostly act as control flow vehicles.

To make sure Sentry captures all your app's errors, configure error handling based on how your application manages exceptions:

If you have a global catch-all exception filter, add a @SentryExceptionCaptured() decorator to the filter's catch() method:

Copied
import { Catch, ExceptionFilter } from "@nestjs/common";

import { SentryExceptionCaptured } from "@sentry/nestjs";


@Catch()
export class YourCatchAllExceptionFilter implements ExceptionFilter {

  @SentryExceptionCaptured()

  catch(exception, host): void {
    // your implementation here
  }
}

If you don't have a global catch-all exception filter, add the SentryGlobalFilter to the providers of your main module, before any other exception filters:

Copied
import { Module } from "@nestjs/common";

import { APP_FILTER } from "@nestjs/core";
import { SentryGlobalFilter } from "@sentry/nestjs/setup";


@Module({
  providers: [

    {
      provide: APP_FILTER,
      useClass: SentryGlobalFilter,
    },

    // ..other providers
  ],
})
export class AppModule {}

If you have error filters for specific types of exceptions (for example, @Catch(HttpException)) and you want to report these errors to Sentry, you need to capture them in the catch() handler using Sentry.captureException():

Copied
import { ArgumentsHost, BadRequestException, Catch } from "@nestjs/common";
import { BaseExceptionFilter } from "@nestjs/core";
import { ExampleException } from "./example.exception";

import * as Sentry from "@sentry/nestjs";


@Catch(ExampleException)
export class ExampleExceptionFilter extends BaseExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {

    Sentry.captureException(exception);

    return super.catch(new BadRequestException(exception.message), host);
  }
}
Are you using Microservices?

If you're using @nestjs/microservices make sure to handle errors in RPC contexts correctly by providing your own RpcExceptionFilter (see Nest.js Microservices documentation). SentryGlobalFilter in a hybrid application doesn't extend BaseRpcExceptionFilter since this depends on @nestjs/microservices.

Use Sentry.captureException(exception) in your custom filter in case you want to send these errors to Sentry:

Copied
import { Catch, RpcExceptionFilter, ArgumentsHost } from "@nestjs/common";
import { Observable, throwError } from "rxjs";
import { RpcException } from "@nestjs/microservices";
import * as Sentry from "@sentry/nestjs";

@Catch(RpcException)
export class ExceptionFilter implements RpcExceptionFilter<RpcException> {
  catch(exception: RpcException, host: ArgumentsHost): Observable<any> {
    Sentry.captureException(exception); // optional
    return throwError(() => exception.getError());
  }
}
Previous
Installation Methods
Next
ESM (MJS)
Was this helpful?
Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").