Skip to content

NestJS SaaS Backend Adoption Roadmap ​

nestarc packages are independent — you can install any one without the others. But if you are seeing nestarc for the first time, do not start by trying to use the full SaaS package lineup. Start with the shape of your SaaS API, then add the packages that match the next operational problem you are solving.

If you are still deciding which capabilities belong in your own codebase, use the build-vs-buy decision guide before choosing an adoption stage.

StepGoalPackages
1SaaS API foundationtenancy, safe-response, pagination
2Data safetysoft-delete, idempotency
3Operational traceability and release controlaudit-log, api-keys, feature-flag
4Async eventsoutbox, inbox, jobs, webhook
5Privacy and compliancedata-subject
6Access controlrbac

This path is not a dependency graph. It is a product-building order: each step gives your backend a capability that teams usually need before the next layer becomes useful.

Step 1: SaaS API Foundation ​

Start here when you are building the first production-facing API surface.

Why first: Tenant boundaries, response consistency, and list endpoints shape almost every controller and service. Adding these early avoids breaking changes later.

What you get:

  • PostgreSQL RLS tenant isolation on all queries
  • Standardized { success, data, error, meta } responses
  • Cursor and offset pagination with filters and Swagger docs

Time to integrate: 15–30 minutes

Getting Started → · safe-response Quick Start → · pagination Quick Start →


Step 2: Data Safety ​

Add these before user actions can accidentally create duplicate or unrecoverable data changes.

Why second: Once users can create, update, and delete records, you need protection against accidental deletion and retry storms.

What you get:

  • Soft-delete filtering, restore, purge, and cascade behavior
  • Idempotency-Key handling for non-idempotent writes
  • Response replay for safe retries

Time to integrate: 15–30 minutes


Step 3: Operational Traceability and Release Control ​

Add these when real users, operators, support workflows, or external clients enter the system.

Why third: Production systems need to answer who changed what, which machine client made a request, and whether a feature should be enabled for a tenant.

What you get:

  • Transaction-first create, update, and delete audit records with an explicit legacy best-effort mode
  • Tenant-scoped API keys with scopes, live/test isolation, zero-downtime rotation, and optional IP allowlists
  • DB-backed feature flags with tenant overrides and rollout controls

Time to integrate: 30–60 minutes

Upgrade an existing soft-delete installation

If Step 2 was installed with soft-delete 0.7.5 or earlier, upgrade it to 0.7.6 before adding audit-log 0.8.0. The version-pinned lifecycle recipe uses tenancy 0.16.4, audit-log 0.8.0, and soft-delete 0.7.6 with strict peer validation. Soft-delete 0.7.6 excludes audit-log 0.9.0; keep the lifecycle recipe on 0.8.0.

Standalone audit-log 0.9.0 provides managed manual transactions and opt-in validation, operation diagnostics, and SQL Server history queries. Automatic Prisma tracking remains PostgreSQL-only. Version 0.9.0 also adds optional atomic Outbox delivery for new PostgreSQL audit events.

Audit Trail Guide → · Customer API Keys Walkthrough → · Feature Flags Guide →


Step 4: Async Events ​

Add these when work needs to leave the request lifecycle.

Why fourth: Event delivery, background work, and customer webhooks are much easier to reason about once your core data and operational controls are in place.

What you get:

  • Transactional outbox for reliable domain events
  • Transactional inbox for incoming event deduplication and atomic database processing
  • Tenant-aware jobs with in-memory fairness, durable BullMQ retry/dedupe, and first-party outbox publishing
  • Outbound webhook delivery with signing, retry, circuit breaker, and delivery logs

Time to integrate: 30–90 minutes, depending on adapters and infrastructure

bash
npm install @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]

Including Inbox 0.2.0 requires NestJS 11.2.8+ within 11.x and Prisma 7.10.1+ within 7.x. Follow the Inbox installation guide for its SQL schema and peers. This combined install pairs Outbox 0.4.1 with Jobs 0.4.2. Keep Outbox polling enabled and stop its poller before closing Jobs; follow the Outbox integration guide.

outbox Docs → · inbox Docs → · jobs Docs → · webhook Docs →

The combined command follows the supported Jobs/Outbox bridge versions. Add only the packages your application needs, and use each package's installation page for standalone setup and required peers.

Including Inbox 0.2.0 requires NestJS ^11.2.8 and Prisma ^7.10.1 across this composition. Inbox records incoming events before transport acknowledgment, then commits handler writes and completion together; Outbox records outgoing events alongside business writes. Follow Inbox installation and its retry, replay, and retention guidance for the receiving side.

Async Delivery Reference Workflow →


Step 5: Privacy and Compliance ​

Add this when customers can request exports or erasure, or when your data model needs explicit retention policies.

Why fifth: Data-subject workflows need a clear model of what data exists, what can be deleted, what must be retained, and which events should be emitted after completion.

What you get:

  • Export and erase request lifecycle
  • Per-entity delete, anonymize, retain, and mixed policies
  • Legal retention tracking and outbox fan-out

Time to integrate: 30–60 minutes for a small model, longer for large domain models

Policy Model →


Step 6: Access Control ​

Add this when your app has multiple roles, machine clients, service accounts, or resource-scoped permissions.

Why sixth: Authorization policy changes often lag behind core data-model work. Add RBAC once you know which tenant, global, and resource-scoped operations should be allowed.

What you get:

  • Tenant-aware roles and permission checks
  • Typed permission contracts and fail-closed configuration defaults
  • Route guards and service-level authorization APIs
  • Optional Prisma/PostgreSQL storage
  • Audit-log and policy-change integration hooks
  • Scenario and matrix testing helpers for allow/deny coverage

Time to integrate: 30–60 minutes for a small role model, longer if migrating an existing permission system

bash
npm install @nestarc/[email protected]

rbac Docs →

Production Access-Control Recipe → · Guards & Permissions →


Prisma Extension Order ​

For tenant-scoped deletion and audit evidence, use tenancy 0.16.4, audit-log 0.8.0, and soft-delete 0.7.6. This combination requires Node.js ^22.23.4 || ^24.22.1 and NestJS 10/11. Soft-delete 0.7.6 adds audit-log 0.8.0 compatibility while preserving earlier supported versions.

bash
npm install --save-exact --strict-peer-deps @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]
  1. Create an ordinary client with the per-query tenancy extension for tenant-scoped queries.
  2. Derive a separate lifecycle client from the same base Prisma client. Apply audit-log first with consistency: 'atomic-required', tenantRequired: true, and a tenantResolver that returns the authorized tenant. Apply soft-delete second with auditLifecycle: 'atomic-required'. Give that client to SoftDeleteModule for restore and purge.
  3. Let audit-log open the transaction and pass it tenancyTransactionCallback(tenancyService, work). The callback binds the tenant to that connection before performing any business work. Keep one authorized tenant throughout the transaction.

For example, inside an authorized request, with the lifecycle client and generated Prisma types from the extension chaining guide:

typescript
import { tenancyTransactionCallback } from '@nestarc/tenancy';
import type { AuditTransactionMethods } from '@nestarc/audit-log';
import type { Prisma } from './generated/prisma/client';

const owner = lifecycleClient as unknown as Pick<
  AuditTransactionMethods<Prisma.TransactionClient>, 'withAuditTransaction'
>;
await owner.withAuditTransaction(tenancyTransactionCallback(
  tenancyService,
  async (tx: Prisma.TransactionClient) => tx.user.delete({ where: { id: userId } }),
));

Configure the audit model list, table mappings and batch caps for every soft-delete model and cascade child. The full NestJS wiring includes those settings, the provider token, and restore and purge examples. The 0.7.6 PostgreSQL regression checks tenant isolation, committed deletes and restores, permanent deletion, and rollback after user or audit failures, including caught audit failures.

All Packages at a Glance ​

PackageAdoption StepRequires Code Changes?Depends On
tenancyStep 1Yes (module + Prisma extension)—
safe-responseStep 1Yes (module registration)—
paginationStep 1Yes (decorators on routes)Optional: safe-response
soft-deleteStep 2Yes (schema + Prisma extension)Optional: audit-log, tenancy, @nestjs/event-emitter
idempotencyStep 2Yes (interceptor + decorator)Optional: ioredis or pg; @types/pg for PostgreSQL TypeScript consumers
audit-logStep 3Yes (audit table + manual event or audited transaction)Optional: tenancy; outbox for PostgreSQL delivery
api-keysStep 3Yes (guards + scopes)Optional: Prisma
feature-flagStep 3Yes (decorators on routes)Optional: tenancy
outboxStep 4Yes (module + event handlers)Optional: tenancy
inboxStep 4Yes (SQL schema + handlers + transport acknowledgment)Prisma 7.10.1+, PostgreSQL; optional: tenancy
jobsStep 4Yes (handlers + backend)Optional: BullMQ, outbox
webhookStep 4Yes (module + event publishing)Optional: tenancy
data-subjectStep 5Yes (policies + adapters)Optional: outbox
rbacStep 6Yes (guards + roles)Optional: Prisma, tenancy, api-keys

Tooling ​

@nestarc/mcp-guard is published under the same npm scope, but is not part of the SaaS package adoption path. It statically scans MCP servers and MCP client configuration files before you connect them to AI coding tools. See mcp-guard.

Documentation site: MIT License. Check each package for its license.