Project setup

1. Copy the source into your project root or a subdirectory, e.g. ./novu-source/.

2. Install workspace dependencies from the repo root:

   cd novu-source
   pnpm install
   

3. Wire TypeScript paths in your consuming project's tsconfig.json:

   {
     "extends": "./novu-source/tsconfig.json",
     "compilerOptions": {
       "paths": {
         "@novu/application-generic": ["./novu-source/libs/application-generic/src/index.ts"],
         "@novu/shared": ["./novu-source/libs/shared/src/index.ts"]
       }
     }
   }
   

4. Set required environment variables (copy from apps/api/.env.example if present):

   MONGO_URL=mongodb://localhost:27017/novu
   REDIS_HOST=localhost
   REDIS_PORT=6379
   JWT_SECRET=your-jwt-secret
   NODE_ENV=development
   PORT=3000
   

5. Build and run the API:

   cd novu-source
   pnpm nx serve api
   # or for production build:
   pnpm nx build api && node apps/api/dist/main.js
   

6. Use individual use-case modules by importing directly from their index files (see Public API below) without running the full server.

Public API

bootstrap

// apps/api/src/bootstrap.ts
declare function bootstrap(): Promise<void>;

Bootstraps the NestJS application and starts the HTTP server on the configured PORT. Call this only when running the full API server. It wires all NestJS modules, middleware, and database connections before listening.

BuildActiveSubscribersChart / BuildActiveSubscribersChartCommand

// apps/api/src/app/activity/usecases/build-active-subscribers-chart/index.ts
export { BuildActiveSubscribersChartCommand } from './build-active-subscribers-chart.command';
export { BuildActiveSubscribersChart } from './build-active-subscribers-chart.usecase';

A NestJS injectable use-case that computes a chart dataset of active subscribers over a time range. BuildActiveSubscribersChartCommand is the CQRS command carrying the organization/environment context. Use it when building analytics dashboards that need subscriber activity histograms.

BuildDeliveryTrendChart / BuildDeliveryTrendChartCommand

// apps/api/src/app/activity/usecases/build-delivery-trend-chart/index.ts
export { BuildDeliveryTrendChartCommand } from './build-delivery-trend-chart.command';
export { BuildDeliveryTrendChart } from './build-delivery-trend-chart.usecase';

A use-case that aggregates notification delivery success/failure counts over time, producing trend data suitable for time-series charts. Use it to expose delivery health metrics to operations teams or to drive alerting logic on delivery degradation.

BuildAvgMessagesPerSubscriberChart / BuildAvgMessagesPerSubscriberChartCommand

// apps/api/src/app/activity/usecases/build-avg-messages-per-subscriber-chart/index.ts
export { BuildAvgMessagesPerSubscriberChartCommand } from './build-avg-messages-per-subscriber-chart.command';
export { BuildAvgMessagesPerSubscriberChart } from './build-avg-messages-per-subscriber-chart.usecase';

Calculates the average number of messages sent per subscriber within a given window, returning chart-ready data. Useful for capacity planning and identifying subscriber engagement outliers.

Working examples

Scenario - Standalone use-case execution in an existing NestJS module

Import and execute a chart use-case directly inside your own NestJS service without running the full Novu API server.

import { Module, Injectable } from '@nestjs/common';
import {
  BuildActiveSubscribersChart,
  BuildActiveSubscribersChartCommand,
} from './novu-source/apps/api/src/app/activity/usecases/build-active-subscribers-chart';

@Injectable()
export class AnalyticsService {
  constructor(private readonly buildChart: BuildActiveSubscribersChart) {}

  async getActiveSubscriberChart(organizationId: string, environmentId: string) {
    const command = BuildActiveSubscribersChartCommand.create({
      organizationId,
      environmentId,
    });
    return this.buildChart.execute(command);
  }
}

@Module({
  providers: [BuildActiveSubscribersChart, AnalyticsService],
  exports: [AnalyticsService],
})
export class AnalyticsModule {}

Scenario - Delivery trend chart for an operations dashboard

Fetch delivery trend data and expose it via an Express route, showing how to bridge NestJS use-cases with a plain Express handler.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module'; // your existing NestJS module
import {
  BuildDeliveryTrendChart,
  BuildDeliveryTrendChartCommand,
} from './novu-source/apps/api/src/app/activity/usecases/build-delivery-trend-chart';

async function fetchDeliveryTrend(orgId: string, envId: string) {
  const app = await NestFactory.createApplicationContext(AppModule);
  const useCase = app.get(BuildDeliveryTrendChart);

  const command = BuildDeliveryTrendChartCommand.create({
    organizationId: orgId,
    environmentId: envId,
  });

  const result = await useCase.execute(command);
  await app.close();
  return result;
}

fetchDeliveryTrend('org_123', 'env_456').then(console.log);

Scenario - Average messages per subscriber metric in a scheduled job

Run the avg-messages use-case in a cron job to record daily metrics into your own time-series store.

import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import {
  BuildAvgMessagesPerSubscriberChart,
  BuildAvgMessagesPerSubscriberChartCommand,
} from './novu-source/apps/api/src/app/activity/usecases/build-avg-messages-per-subscriber-chart';

@Injectable()
export class MetricsScheduler {
  private readonly logger = new Logger(MetricsScheduler.name);

  constructor(private readonly buildAvgChart: BuildAvgMessagesPerSubscriberChart) {}

  @Cron(CronExpression.EVERY_DAY_AT_MIDNIGHT)
  async recordDailyMetrics() {
    const command = BuildAvgMessagesPerSubscriberChartCommand.create({
      organizationId: process.env.ORG_ID!,
      environmentId: process.env.ENV_ID!,
    });
    const data = await this.buildAvgChart.execute(command);
    this.logger.log('Daily avg messages per subscriber recorded', data);
    // persist `data` to your metrics store
  }
}

File walkthrough

• .agents/ - Skill markdown files that teach AI agents email best practices and React Email patterns; not runtime code.
• .claude/ / .cursor/ - IDE-specific agent configuration; irrelevant to runtime but useful for developer tooling.
• .devcontainer/ - Defines a reproducible dev environment via Docker Compose; use it with VS Code Remote Containers or Codespaces.
• .github/ - All CI/CD automation: test workflows, release pipelines, and Dependabot/Renovate configs.
• apps/ - Runnable applications; apps/api is the primary NestJS backend with all route controllers, use-cases, and modules.
• docker/ - docker-compose files to start MongoDB, Redis, and other infrastructure dependencies locally.
• enterprise/ - Git submodule for closed-source enterprise features; will be empty without access credentials.
• libs/ - Shared internal libraries (application-generic, shared, dal, testing, etc.) consumed across all apps and packages.
• packages/ - Independently published npm packages (@novu/js, @novu/react, channel provider adapters).
• playground/ - Minimal test apps for rapid manual verification of SDK and UI components.
• scripts/ - Repo maintenance scripts (migrations, codegen, release helpers).
• nx.json - Nx build orchestration: task caching, affected graph, and pipeline definitions.
• pnpm-workspace.yaml - Declares all workspace package globs for pnpm.
• tsconfig.json - Root compilerOptions baseline; all packages extend this.
• biome.json - Unified linting and formatting rules replacing ESLint + Prettier for most packages.

Common pitfalls and fixes

• enterprise/ submodule is empty - Run git submodule update --init --recursive only if you have access; otherwise exclude it from your build to avoid missing-module errors.
• pnpm version mismatch - The repo pins pnpm via packageManager in package.json; run corepack enable && corepack prepare to activate the correct version automatically.
• reflect-metadata not imported - NestJS decorators require import 'reflect-metadata' as the very first import in your entry file; omitting it causes silent decorator failures.
• MongoDB connection string format - Mongoose in this codebase expects a full URI in MONGO_URL; passing just a hostname will throw a parse error at boot.
• Nx cache stale after branch switch - Run pnpm nx reset to clear the local Nx build cache when switching between feature branches that alter libs/.
• ESM/CJS interop in libs/ - Several internal libraries ship dual CJS/ESM output; if your bundler resolves the wrong condition, add "moduleResolution": "bundler" to your tsconfig.json or set "type": "module" explicitly in the consuming package.

Vibe-coding prompt template

I have the Novu open-source notification infrastructure monorepo located at `./novu-source/`.
I also have `USAGE.md` in the same directory explaining the real exports and setup steps.

My existing project is a Node.js/TypeScript NestJS application. Please help me integrate Novu step-by-step:

1. Read `USAGE.md` and `novu-source/apps/api/src/app/activity/usecases/` to understand available use-cases.
2. Add the required dependencies from `USAGE.md` to my `package.json`.
3. Update my `tsconfig.json` with path aliases so I can import from `novu-source/libs/` cleanly.
4. Create a new `NotificationAnalyticsModule` in my project that provides:
   - `BuildActiveSubscribersChart`
   - `BuildDeliveryTrendChart`
   - `BuildAvgMessagesPerSubscriberChart`
5. Create a `NotificationAnalyticsController` with GET endpoints that call each use-case and return JSON.
6. Wire the required environment variables (MONGO_URL, REDIS_HOST, JWT_SECRET) into my `.env`.
7. Show me how to run the integration with `pnpm nx serve api` and test each endpoint with curl.

Use only the real exports from `USAGE.md`. Do not invent new class names or module paths.

License and credit

Novu is released under the MIT License (see source/LICENSE). The upstream project is maintained by the Novu team and community at github.com/novuhq/novu. The upstream npm package namespace is @novu/* (e.g. @novu/js, @novu/react).

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

完全なインストールガイドと統合プロンプトは購入後に解放されます。

Self-Hosted Newsletter and Mailing List Manager

PHP, Laravel & Business Scripts

無料