CommonJS (CJS)
Learn about running Sentry in an CJS application.
Are you unsure if you should use this installation method? Review our installation methods.
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.mjsimport * as Sentry from "@sentry/nestjs";
import { nodeProfilingIntegration } from '@sentry/profiling-node';
// Ensure to call this before importing 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// 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.tsimport { 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 {}
If you're 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 @SentryExceptionCaptured() decorator to the filter's catch() method. This decorator will report all unexpected errors that are received by your global error filter to Sentry:
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
}
}
By default, only unhandled exceptions that are not caught by an error filter are reported to Sentry. HttpExceptions (including derivatives) are also not captured by default because they mostly act as control flow vehicles.
Note that @SentryExceptionCaptured() was called @WithSentry in SDK versions 8.38.0 and prior.
If you don't have a global catch-all exception filter, add the SentryGlobalFilter to the providers of your main module. This filter will report any unhandled errors that aren't caught by other error filters to Sentry. Important: The SentryGlobalFilter needs to be registered before any other exception filters.
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: If you have a NestJS + GraphQL application and you are using the @sentry/nestjs SDK version 8.38.0 or earlier, replace the SentryGlobalFilter with the SentryGlobalGenericFilter. In SDK versions 8.39.0 and above, the SentryGlobalGenericFilter is deprecated because the SentryGlobalFilter will handle GraphQL contexts automatically.
If you have error filters for specific types of exceptions (for example @Catch(HttpException), or any other @Catch(...) with arguments) and you want to capture errors caught by these filters, capture the errors in the catch() handler with Sentry.captureException():
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)
}
}
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").