From 1e2766b002bc43d244ed17b58de058d653f652e3 Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Mon, 18 May 2026 15:02:41 -0300 Subject: [PATCH 1/7] Create CNAME --- CNAME | 1 + 1 file changed, 1 insertion(+) create mode 100644 CNAME diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..62c4181 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +nest-native.dev \ No newline at end of file From 6b6b78e9a856d4682ca19bb9506e946342030426 Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Tue, 19 May 2026 00:55:04 -0300 Subject: [PATCH 2/7] Delete CNAME --- CNAME | 1 - 1 file changed, 1 deletion(-) delete mode 100644 CNAME diff --git a/CNAME b/CNAME deleted file mode 100644 index 62c4181..0000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -nest-native.dev \ No newline at end of file From 65cdb7841c1ff9167256dfe9fd0243ca65bffc23 Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Tue, 19 May 2026 00:55:22 -0300 Subject: [PATCH 3/7] Create CNAME --- CNAME | 1 + 1 file changed, 1 insertion(+) create mode 100644 CNAME diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..62c4181 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +nest-native.dev \ No newline at end of file From 68b358bd6b051e697726d015d8464a63604891ce Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Tue, 19 May 2026 01:08:39 -0300 Subject: [PATCH 4/7] Delete CNAME --- CNAME | 1 - 1 file changed, 1 deletion(-) delete mode 100644 CNAME diff --git a/CNAME b/CNAME deleted file mode 100644 index 62c4181..0000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -nest-native.dev \ No newline at end of file From ba3dc96756cfd8ac82b89eacb6aa1bd5e3424ac1 Mon Sep 17 00:00:00 2001 From: Rodrigo Nogueira Date: Tue, 19 May 2026 01:08:56 -0300 Subject: [PATCH 5/7] Create CNAME --- CNAME | 1 + 1 file changed, 1 insertion(+) create mode 100644 CNAME diff --git a/CNAME b/CNAME new file mode 100644 index 0000000..62c4181 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +nest-native.dev \ No newline at end of file From 0a1a42df6e741009483113e3cce8e84e1795b9be Mon Sep 17 00:00:00 2001 From: rodrigobnogueira Date: Sat, 23 May 2026 13:10:45 -0300 Subject: [PATCH 6/7] docs: remove prisma exploration from landing page --- index.html | 20 ++------------------ 1 file changed, 2 insertions(+), 18 deletions(-) diff --git a/index.html b/index.html index a5078a9..48e7160 100644 --- a/index.html +++ b/index.html @@ -121,22 +121,6 @@

nest-trpc-native

-
-
-

Exploration

-

nest-prisma-native

-

- A feasibility track for a thin, Prisma-respecting Nest - integration focused on clients, repositories, transactions, - testing, and error mapping. -

-
-
- - GitHub - -
-
@@ -154,8 +138,8 @@

Feel native. Stay honest.

It should also respect the tool it integrates. Drizzle should still feel SQL-first. tRPC should still preserve end-to-end type safety. - Future Prisma work should keep the generated client visible and - trusted. + Future integrations should only exist when they solve a real gap + without hiding the underlying tool.

  • No unnecessary runtime dependencies.
    • From d3c8d311ffc2f4cad7d387b54818a880018e716e Mon Sep 17 00:00:00 2001 From: rodrigobnogueira Date: Sat, 23 May 2026 18:50:11 -0300 Subject: [PATCH 7/7] docs: add cross-project idea briefs --- ideas/01-production-reference-app.md | 99 +++++++++++++++++++++ ideas/02-transactional-outbox.md | 126 +++++++++++++++++++++++++++ ideas/03-create-nest-native-app.md | 107 +++++++++++++++++++++++ 3 files changed, 332 insertions(+) create mode 100644 ideas/01-production-reference-app.md create mode 100644 ideas/02-transactional-outbox.md create mode 100644 ideas/03-create-nest-native-app.md diff --git a/ideas/01-production-reference-app.md b/ideas/01-production-reference-app.md new file mode 100644 index 0000000..b69d43b --- /dev/null +++ b/ideas/01-production-reference-app.md @@ -0,0 +1,99 @@ +# Production Reference App + +**Project type:** New project. + +**Suggested repository:** `nest-native/reference-app` or `nest-native/nest-native-reference` + +## Summary + +Build a real production-shaped application that uses the Nest Native libraries +together, especially `nest-drizzle-native` and `nest-trpc-native`. + +The goal is not another small sample. The goal is a credible reference app that +answers the question maintainers and teams actually ask: + +> Can I trust this stack in a serious NestJS application? + +## Community Pain + +Most library samples are too small. They prove an API call, but not the +operational shape of a real backend: + +- feature modules +- auth and authorization +- request-scoped context +- transactions across services +- database migrations +- health checks +- tests with real database behavior +- deployment steps +- typed client consumption +- production documentation + +Developers can understand a library API and still hesitate because they cannot +see how the pieces behave together in an application. + +## Proposed App Shape + +A compact but realistic SaaS-style application: + +- accounts or organizations +- users and memberships +- roles or permissions +- projects/tasks/tickets +- audit log or activity feed +- transactional workflows +- admin-only endpoints +- typed frontend or typed client smoke checks + +The app should avoid demo-only gimmicks. It should feel like a small backend a +team could adapt. + +## Libraries Demonstrated + +- `nest-drizzle-native` for database registration, repositories, transactions, + migrations, named clients if needed, and testing utilities +- `nest-trpc-native` for decorator-first routers, procedures, enhancers, typed + client generation, and Nest dependency injection +- standard NestJS guards, pipes, interceptors, filters, request scope, and + lifecycle hooks + +## What It Should Prove + +- A transaction can span multiple services without passing `tx` through every + method. +- DTO validation and tRPC/Zod style validation can coexist without making one + mandatory everywhere. +- Repository classes remain thin homes for query code, not an Active Record + rewrite. +- Health/readiness, migrations, CI, and release checks have a clear production + path. +- The typed client story remains ergonomic. + +## Suggested Milestones + +1. Scaffold a minimal Nest app with Drizzle and tRPC. +2. Add database schema, migrations, and seed data. +3. Add auth context and request-scoped user/tenant providers. +4. Add core modules: users, organizations, projects, audit log. +5. Add transactional workflow: invite user, create project, record audit event. +6. Add tests: unit, integration, real DB, typed client checks. +7. Add deployment documentation and Docker/Kubernetes examples. +8. Add a README that explains architecture decisions without becoming a book. + +## Success Criteria + +- A new user can clone the app, run tests, and understand the architecture in + under an hour. +- The app reveals real improvements or gaps in the existing libraries. +- Any library fixes discovered are handled in separate PRs, not mixed into the + reference app. + +## Why This Is Worth Doing + +This is probably the highest-value next step. It strengthens both existing +libraries and creates a proof artifact for the whole Nest Native philosophy. + +It also protects us from building unnecessary APIs. If the reference app feels +good with the current libraries, avoid adding helpers. If it feels repetitive in +specific places, those are the right candidates for future API design. diff --git a/ideas/02-transactional-outbox.md b/ideas/02-transactional-outbox.md new file mode 100644 index 0000000..b8c69da --- /dev/null +++ b/ideas/02-transactional-outbox.md @@ -0,0 +1,126 @@ +# Transactional Outbox Pattern + +**Project type:** New project, with integration samples in existing projects. + +**Possible future project:** `nest-native/nest-outbox-native` + +**Integration targets:** `nest-drizzle-native`, `nest-trpc-native`, and ordinary +NestJS applications. + +## Summary + +Explore a Nest-native transactional outbox package for reliable side-effect +orchestration. + +This goes beyond `nest-drizzle-native` scope. The Drizzle library can prove the +database transaction foundation, and the tRPC library can prove a typed +mutation boundary, but outbox processing itself is a separate concern. + +## Community Pain + +Backend teams often need to perform a database write and then trigger a side +effect: + +- publish an event +- send an email +- enqueue a job +- sync data to another system +- call a webhook + +The dangerous version is: + +1. write to the database +2. send the message immediately +3. later discover the transaction rolled back + +Or the opposite: + +1. commit the database change +2. crash before sending the message + +The transactional outbox pattern solves this by writing the side effect intent +inside the same transaction, then processing it after commit. + +## Why It Fits Nest Native + +The outbox pattern fits the broader Nest Native philosophy because it connects +several production concerns without hiding them: + +- tRPC or REST receives the typed application command +- `@Transactional()` owns the workflow boundary +- repositories write domain rows and outbox rows in the same transaction +- a worker processes committed outbox records +- retries and idempotency are explicit +- no side effects happen before the database commit is durable + +## Proposed First Proof + +Start with a small proof app or reference-app slice, not a new package API: + +- `nest-trpc-native` exposes a mutation +- `nest-drizzle-native` persists the domain row and outbox row +- an app-owned worker processes committed events +- tests prove rollback safety and retry behavior + +Scenario: + +- create an account +- insert an outbox event in the same transaction +- simulate rollback and prove no event is processed +- commit and prove the event is picked up +- mark event processed +- retry failed events safely + +## Minimal Schema + +- `accounts` +- `outbox_events` + +Outbox fields: + +- `id` +- `topic` +- `payload` +- `status` +- `attempts` +- `available_at` +- `processed_at` +- `created_at` + +## Documentation Topics + +- why not publish inside the transaction method +- how to keep payloads safe and versioned +- idempotency keys +- retry strategy +- worker ownership +- poison message handling +- observability +- when a queue is still needed + +## Possible Public API + +Only after proof-first validation: + +- `OutboxModule` +- `OutboxRepository` +- `OutboxProcessor` +- `@OutboxHandler('topic')` +- retry and idempotency helpers + +But this should not be rushed. A premature package could become too opinionated +about queues, retries, serialization, and deployment. + +## Success Criteria + +- The proof proves rollback safety with a real database. +- The docs explain the pattern without pretending the library owns every queue + strategy. +- The implementation remains small enough that application teams can adapt it + before a reusable package exists. + +## Why This Is Worth Doing + +This solves a real production problem that sits between database transactions, +API boundaries, workers, and side effects. It deserves its own project if the +proof shows enough repeated shape to justify a package. diff --git a/ideas/03-create-nest-native-app.md b/ideas/03-create-nest-native-app.md new file mode 100644 index 0000000..c695039 --- /dev/null +++ b/ideas/03-create-nest-native-app.md @@ -0,0 +1,107 @@ +# Create Nest Native App + +**Project type:** New project, later. + +**Suggested repository:** `nest-native/create-nest-native-app` + +## Summary + +Build a project generator or CLI that scaffolds production-minded Nest Native +applications. + +This should not be the next immediate project. It becomes valuable after the +reference app and more samples prove which architecture choices are stable. + +## Community Pain + +Starting a serious Nest app involves many decisions: + +- database integration +- transaction pattern +- migrations +- validation style +- OpenAPI or tRPC +- testing +- CI +- deployment +- health checks +- package manager +- folder structure + +Most starters are either too minimal or too opinionated. A Nest Native +generator could give users a curated, production-shaped starting point. + +## Possible User Flow + +```bash +npm create nest-native-app +``` + +Prompts: + +- project name +- package manager +- database driver +- Drizzle only, tRPC only, or both +- REST/OpenAPI, tRPC, or mixed +- class-validator DTOs or Zod opt-in +- include Docker/deployment files +- include GitHub Actions CI +- include example auth/context + +## First Template + +Start with one strong template instead of many weak ones: + +- NestJS 11 +- Node 20+ +- `nest-drizzle-native` +- SQLite/libSQL local development +- optional PostgreSQL production recipe +- migrations +- health checks +- tests +- CI + +Add tRPC only after the Drizzle-only template feels excellent. + +## What It Should Generate + +- `src/app.module.ts` +- database module +- schema/migrations folder +- health endpoints +- one feature module with repository/service/controller or router +- test setup +- CI workflow +- README with exact commands +- deployment notes + +## Risks + +- CLI maintenance can become expensive. +- Too many options can make the generated app inconsistent. +- Templates can drift from library best practices. +- Users may expect the CLI to solve application architecture decisions that + should remain app-owned. + +## Readiness Criteria + +Do not start this until: + +- the production reference app exists +- core samples are stable +- docs have settled +- common project structure decisions are clear +- release and update process for templates is understood + +## Success Criteria + +- A new user can generate an app and run tests in minutes. +- Generated code looks like something we would maintain ourselves. +- The template reinforces Nest Native philosophy instead of hiding it. + +## Why This Is Worth Doing + +If the ecosystem grows, a generator can dramatically reduce onboarding +friction. But it should come after the architecture is proven, not before.