The bcrypt package requires native build tooling. Ensure node-gyp, Python 3, and a C++ compiler (GCC on Linux, Xcode CLT on macOS, MSVC on Windows) are available before running npm install.

Project setup

1. Copy source - Place the contents of source/ into your project root or a subdirectory (e.g., ./seerr/). The server entry point is server/index.ts.

2. Configure TypeScript path aliases - The server code uses @server/* aliases. Merge the following into your tsconfig.json:

   {
     "compilerOptions": {
       "baseUrl": ".",
       "paths": {
         "@server/*": ["server/*"],
         "@app/*": ["src/*"]
       },
       "experimentalDecorators": true,
       "emitDecoratorMetadata": true
     }
   }
   

3. Configure Babel module-alias (for Jest / runtime) - Update babel.config.js module-resolver to include the same aliases.

4. Set environment variables:

   NODE_ENV=production
   PORT=5055
   CONFIG_DIRECTORY=/app/config       # SQLite DB and settings.json location
   LOG_LEVEL=info
   

5. Database - SQLite is used via TypeORM. The data source is initialized in server/datasource.ts. No external database setup is required for development; production runs migrations automatically on start.

6. Start the server:

   npx ts-node -r tsconfig-paths/register server/index.ts
   # or after build:
   node dist/server/index.js
   

Public API

Notification (enum)

export enum Notification {
  NONE               = 0,
  MEDIA_PENDING      = 2,
  MEDIA_APPROVED     = 4,
  MEDIA_AVAILABLE    = 8,
  MEDIA_FAILED       = 16,
  TEST_NOTIFICATION  = 32,
  MEDIA_DECLINED     = 64,
  MEDIA_AUTO_APPROVED = 128,
  ISSUE_CREATED      = 256,
  ISSUE_COMMENT      = 512,
  ISSUE_RESOLVED     = 1024,
  ISSUE_REOPENED     = 2048,
  MEDIA_AUTO_REQUESTED = 4096,
}

Use this enum when registering which events a notification agent should respond to, or when checking a user's notification preferences as a bitmask.

hasNotificationType

export const hasNotificationType = (
  types: Notification | Notification[],
  value: number
): boolean;

Checks whether a bitmask value includes any of the specified types. Pass a single Notification or an array; the function combines them and performs a bitwise test. TEST_NOTIFICATION is always implicitly included.

PreparedEmail

class PreparedEmail extends Email {
  public constructor(
    settings: NotificationAgentEmail,
    pgpKey?: string
  );
}

Constructs a fully configured email-templates instance with SMTP transport derived from NotificationAgentEmail settings. Pass an ASCII-armored OpenPGP public key as pgpKey to enable encrypted outbound email. Use this when building a custom notification agent or sending transactional email outside the built-in agents.

SortOptions (type)

export type SortOptions =
  | 'popularity.asc'   | 'popularity.desc'
  | 'release_date.asc' | 'release_date.desc'
  | 'vote_average.asc' | 'vote_average.desc'
  | 'first_air_date.asc' | 'first_air_date.desc'
  // ... full union in server/api/themoviedb/index.ts

Pass as the sortBy parameter to TMDB discover endpoints. Provides type-safe sort direction strings compatible with the TMDB v3 API.

Working examples

Scenario - Check if a user's notification bitmask includes a specific event

A user record stores notification preferences as a numeric bitmask. Before dispatching, verify the user actually wants the notification type.

import {
  Notification,
  hasNotificationType,
} from './server/lib/notifications/index';

const userNotificationTypes = Notification.MEDIA_APPROVED | Notification.MEDIA_AVAILABLE;

const shouldNotify = hasNotificationType(
  [Notification.MEDIA_APPROVED, Notification.MEDIA_DECLINED],
  userNotificationTypes
);

if (shouldNotify) {
  console.log('Dispatching approval/decline notification to user.');
}

Scenario - Send a custom email using PreparedEmail

Use PreparedEmail to deliver a templated transactional email with SMTP settings sourced from getSettings().

import PreparedEmail from './server/lib/email/index';
import { getSettings } from './server/lib/settings';

async function sendWelcomeEmail(recipientEmail: string) {
  const settings = getSettings().load();
  const emailAgent = settings.notifications.agents.email;

  const email = new PreparedEmail(emailAgent.options);

  await email.send({
    template: 'welcome',          // maps to a template directory under server/templates/
    message: { to: recipientEmail },
    locals: {
      applicationUrl: settings.main.applicationUrl,
      applicationTitle: settings.main.applicationTitle,
    },
  });
}

Scenario - Register a custom notification agent

Extend the notification manager with a bespoke agent that posts to an internal webhook.

import type {
  NotificationAgent,
  NotificationPayload,
} from './server/lib/notifications/agents/agent';
import notificationManager, {
  Notification,
} from './server/lib/notifications/index';

class InternalWebhookAgent implements NotificationAgent {
  public shouldSend(): boolean {
    return true;
  }

  public async send(
    type: Notification,
    payload: NotificationPayload
  ): Promise<boolean> {
    const res = await fetch('https://internal.example.com/hook', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ type, payload }),
    });
    return res.ok;
  }
}

// Register before app.prepare() in server/index.ts
notificationManager.registerAgents([new InternalWebhookAgent()]);

File walkthrough

• .github/ - GitHub Actions workflows for CI, release, Cypress, and CodeQL scanning; also houses issue/PR templates.
• .vscode/ - Shared workspace settings and extension recommendations for consistent developer experience.
• cypress/ - E2E tests; support/index.ts declares custom commands (login, loginAsAdmin, loginAsUser) on the Cypress global namespace.
• docs/ - Full GitBook documentation tree covering installation, reverse proxy, notification channel setup, and FAQ.
• public/ - Next.js static directory: logo SVG, preview JPEG, and any other public assets served at /.
• server/ - Core backend. Subdirectories: api/ (Plex, TMDB, Radarr, Sonarr clients), entity/ (TypeORM entities), job/ (cron scheduler), lib/ (notifications, settings, cache, email), middleware/, routes/, utils/.
• snap/ - Snapcraft YAML for distributing as a Linux snap package.
• src/ - Next.js frontend: React pages, components, hooks, i18n message catalogs.
• babel.config.js - Transpilation config shared between Next.js and Jest.
• cypress.config.ts - Base URL and spec patterns for the Cypress runner.
• next.config.js - Custom webpack config, environment variable exposure, and image domain allow-listing.
• overseerr-api.yml - OpenAPI 3.0 spec; mounted by Express and served as Swagger UI at /api-docs.
• tailwind.config.js - Design system: custom colors, fonts, and content paths for PurgeCSS.
• tsconfig.json - Compiler options including path aliases, decorator support, and strict mode settings.

Common pitfalls and fixes

• bcrypt native build failure - Install node-gyp globally (npm i -g node-gyp) and ensure Python 3 and a C++ build toolchain are on PATH before npm install.
• @server/* path aliases not resolved at runtime - Register tsconfig-paths before starting the server: node -r tsconfig-paths/register dist/server/index.js; or use tsconfig-paths-webpack-plugin in your custom webpack config.
• emitDecoratorMetadata missing - TypeORM entities use decorators; tsconfig.json must have both "experimentalDecorators": true and "emitDecoratorMetadata": true or entity relations will silently break.
• CSRF errors on API routes - The server mounts csurf middleware; API clients must forward the XSRF-TOKEN cookie value as the X-CSRF-Token header, or exempt paths explicitly in server/index.ts.
• SQLite file not found on first run - CONFIG_DIRECTORY must exist and be writable before startup; the TypeORM data source constructs the DB path from this env var.
• connect-typeorm session store version mismatch - Import from connect-typeorm/out (not the package root) as shown in server/index.ts; the package does not expose a CJS default at the top level in older versions.

Vibe-coding prompt template

I have dropped the Overseerr / Seerr source into my project at `./source/`.
I have read `USAGE.md` and understand the architecture.
The upstream npm package is `user@example.com`.

Please help me integrate this source into my existing Express + TypeScript project step by step:

1. Audit my existing `tsconfig.json` and merge the `@server/*` path aliases from `source/tsconfig.json`.
2. Wire `source/server/index.ts` as the server entry point, or show me how to import only the notification subsystem (`source/server/lib/notifications/index.ts`) into my app.
3. Register the TypeORM data source from `source/server/datasource.ts` alongside my existing DB setup, avoiding conflicts.
4. Add a custom notification agent that sends events to my Slack workspace, using the `Notification` enum and `NotificationPayload` interface visible in `source/server/lib/notifications/index.ts`.
5. Show me how to call `hasNotificationType` to gate dispatching on user preferences.
6. List any environment variables I must set before the server starts.

Use only exports and APIs documented in `USAGE.md`. Do not invent new modules.

License and credit

Overseerr is released under the MIT License - see source/LICENSE for the full text. The upstream project lives at https://github.com/sct/overseerr (npm: user@example.com). Per the README, active development has moved to Seerr; consult the Seerr migration guide for continued support.

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

The full install guide and integration prompts unlock after purchase.