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.
Recommended Adoption Path
| Step | Goal | Packages |
|---|---|---|
| 1 | SaaS API foundation | tenancy, safe-response, pagination |
| 2 | Data safety | soft-delete, idempotency |
| 3 | Operational traceability and release control | audit-log, api-keys, feature-flag |
| 4 | Async events | outbox, inbox, jobs, webhook |
| 5 | Privacy and compliance | data-subject |
| 6 | Access control | rbac |
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
npm install @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]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
npm install @nestarc/[email protected] @nestarc/[email protected]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.
npm install @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]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
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.
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
npm install @nestarc/[email protected]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
npm install @nestarc/[email protected]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.
npm install --save-exact --strict-peer-deps @nestarc/[email protected] @nestarc/[email protected] @nestarc/[email protected]- Create an ordinary client with the per-query tenancy extension for tenant-scoped queries.
- Derive a separate lifecycle client from the same base Prisma client. Apply audit-log first with
consistency: 'atomic-required',tenantRequired: true, and atenantResolverthat returns the authorized tenant. Apply soft-delete second withauditLifecycle: 'atomic-required'. Give that client toSoftDeleteModulefor restore and purge. - 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:
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
| Package | Adoption Step | Requires Code Changes? | Depends On |
|---|---|---|---|
| tenancy | Step 1 | Yes (module + Prisma extension) | — |
| safe-response | Step 1 | Yes (module registration) | — |
| pagination | Step 1 | Yes (decorators on routes) | Optional: safe-response |
| soft-delete | Step 2 | Yes (schema + Prisma extension) | Optional: audit-log, tenancy, @nestjs/event-emitter |
| idempotency | Step 2 | Yes (interceptor + decorator) | Optional: ioredis or pg; @types/pg for PostgreSQL TypeScript consumers |
| audit-log | Step 3 | Yes (audit table + manual event or audited transaction) | Optional: tenancy; outbox for PostgreSQL delivery |
| api-keys | Step 3 | Yes (guards + scopes) | Optional: Prisma |
| feature-flag | Step 3 | Yes (decorators on routes) | Optional: tenancy |
| outbox | Step 4 | Yes (module + event handlers) | Optional: tenancy |
| inbox | Step 4 | Yes (SQL schema + handlers + transport acknowledgment) | Prisma 7.10.1+, PostgreSQL; optional: tenancy |
| jobs | Step 4 | Yes (handlers + backend) | Optional: BullMQ, outbox |
| webhook | Step 4 | Yes (module + event publishing) | Optional: tenancy |
| data-subject | Step 5 | Yes (policies + adapters) | Optional: outbox |
| rbac | Step 6 | Yes (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.