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.js
Copied
const Sentry = require("@sentry/nestjs");
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

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

  // Add Tracing by setting tracesSampleRate
  // We recommend adjusting this value in production
  tracesSampleRate: 1.0,

  // Set sampling rate for profiling
  // This is relative to tracesSampleRate
  profilesSampleRate: 1.0,
});

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:

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();

Afterwards, 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 {}

In case you are using a global catch-all exception filter (which is either a filter registered with app.useGlobalFilters() or a filter registered in your app module providers annotated with a @Catch() decorator without arguments), add a @WithSentry() decorator to the catch() method of this global error filter. This decorator will report all unexpected errors that are received by your global error filter to Sentry:

Copied
import { Catch, ExceptionFilter } from '@nestjs/common';
import { WithSentry } from '@sentry/nestjs';

@Catch()
export class YourCatchAllExceptionFilter implements ExceptionFilter {
  @WithSentry()
  catch(exception, host): void {
    // your implementation here
  }
}

In case you do not have a global catch-all exception filter, add the SentryGlobalFilter to the providers of your main module. This filter will report all unhandled errors to Sentry that are not caught by any other error filter. Important: The SentryGlobalFilter needs to be registered 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 {}

Note: In NestJS + GraphQL applications replace the SentryGlobalFilter with the SentryGlobalGraphQLFilter.

By default, exceptions with status code 4xx are not sent to Sentry. If you still want to capture these exceptions, you can do so manually with 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)
  }
}
Previous
Installation Methods
Next
ESM (MJS)
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").