opinionated-nextjs-patterns

Files (55)

• AGENTS.md
• SKILL.md
• _template.md · assets/templates/
• metadata.json
• _sections.md · references/
• arch-app-vs-packages-boundary.md · references/
• arch-config-driven-navigation.md · references/
• arch-data-access-adapter.md · references/
• arch-feature-package-layout.md · references/
• arch-import-via-package-exports.md · references/
• arch-policy-engine-for-business-rules.md · references/
• arch-provider-gateway-pattern.md · references/
• auth-gate-admin-client.md · references/
• auth-mfa-in-middleware.md · references/
• auth-server-only-imports.md · references/
• auth-trust-rls-no-duplicate-checks.md · references/
• auth-use-require-user.md · references/
• auth-use-sql-policy-helpers.md · references/
• auth-use-standard-server-client.md · references/
• client-pass-server-data-as-props.md · references/
• client-realtime-cleanup-subscription.md · references/
• client-stable-query-keys.md · references/
• client-use-action-hook.md · references/
• client-use-client-at-leaves.md · references/
• client-use-supabase-with-react-query.md · references/
• mutate-enhance-route-handler.md · references/
• mutate-revalidate-path-after-write.md · references/
• mutate-thin-action-service-holds-logic.md · references/
• mutate-use-getlogger-not-console.md · references/
• mutate-use-safe-action-clients.md · references/
• mutate-webhook-verify-signature.md · references/
• mutate-zod-schema-separate-file.md · references/
• proxy-redirect-auth-at-boundary.md · references/
• proxy-secure-headers-flagged.md · references/
• proxy-set-correlation-id.md · references/
• proxy-single-pipeline.md · references/
• proxy-url-pattern-matching.md · references/
• server-cache-workspace-loaders.md · references/
• server-fetch-in-server-components.md · references/
• server-promise-all-parallel-loads.md · references/
• server-redirect-on-missing-workspace.md · references/
• server-services-receive-client.md · references/
• server-use-feature-api-factories.md · references/
• server-use-tables-generic-for-types.md · references/
• tenant-account-id-on-product-tables.md · references/
• tenant-accounts-as-tenant-root.md · references/
• tenant-never-edit-generated-types.md · references/
• tenant-slug-in-team-urls.md · references/
• tenant-storage-paths-include-account-id.md · references/
• ui-base-ui-render-not-aschild.md · references/
• ui-form-message-per-field.md · references/
• ui-kit-ui-package-imports.md · references/
• ui-rhf-zod-no-generics.md · references/
• ui-semantic-tailwind-tokens.md · references/
• ui-trans-for-display-text.md · references/

SKILL.md (first lines)

# Opinionated Next.js 16 Patterns

Implementation-pattern reference for **Next.js 16 (App Router)** codebases that want a single, opinionated architecture. Contains **50 rules across 8 categories**, prioritised by execution-lifecycle cascade impact — authorization and (optional) tenant modeling first, then the request boundary, server fetching, mutations, client boundaries, architecture, and UI conventions.

The rules are **backend-agnostic in principle but use Supabase as the concrete example**. Each rule teaches the transferable idea (e.g. "authorize at the data layer", "read through a typed repository"); where the backend genuinely matters, a `*Transferable:*` note explains the pattern for other stores (Drizzle, Prisma). The structure is a **Turbo monorepo** with `@app/*` packages you own — built on canonical libraries (`next-safe-action`, `@supabase/ssr`, `@tanstack/react-query`, `react-hook-form` + `zod`, `shadcn/ui`, `next-intl`, `pino`), not a vendored starter kit.

## When to Apply

Reach for these rules when:

- **Writing new code** — pages, layouts, server actions, route handlers, `proxy.ts`, feature packages, client components, hooks, the data-access package, SQL/migrations, forms.
- **Reviewing a PR** — authorization slips (privileged client without a guard, missing `'server-only'`), waterfalls (sequential awaits, client-fetching server data), drift (hand-edited generated types, deep package imports, hardcoded i18n strings).
- **Refactoring** — moving code between `apps/web` and `packages/*`, splitting actions and services, lifting `'use client'` boundaries, replacing raw queries with a typed data-access factory, swapping a backend behind the data-access package.
- **Designing a feature** — choosing the right client (request-scoped vs privileged vs browser), deciding action vs route handler, planning the form/server-action contract, scoping a tenant (if multi-tenant).
- **Onboarding** — understanding *why* the codebase looks the way it does, with concrete, transferable examples.

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Authorization & Data-Layer Access | **CRITICAL** | `auth-` |
| 2 | Multi-Tenancy *(optional, SaaS only)* | **CRITICAL** | `tenant-` |
| 3 | Request Boundary (Proxy) | **HIGH** | `proxy-` |
| 4 | Server-Side Data Loading | **HIGH** | `server-` |
| 5 | Mutations: Actions & Route Handlers | **HIGH** | `mutate-` |
| 6 | Client/Server Boundaries | **MEDIUM-HIGH** | `client-` |
| 7 | Architecture & Services | **MEDIUM** | `arch-` |
| 8 | Forms & UI Conventions | **MEDIUM** | `ui-` |

## Quick Reference

### 1. Authorization & Data-Layer Access (CRITICAL)

- [`auth-use-standard-server-client`](references/auth-use-standard-server-client.md) — Use the request-scoped, auth-bound client; never default to the privileged one.
- [`auth-gate-admin-client`](references/auth-gate-admin-client.md) — Authorize *before* constructing the service-role client.
- [`auth-trust-rls-no-duplicate-checks`](references/auth-trust-rls-no-duplicate-checks.md) — Authorize once at the data layer; don't re-check in app code.
- [`auth-use-sql-policy-helpers`](references/auth-use-sql-policy-helpers.md) — Centralize scoping predicates in reusable SQL policy helpers.
- [`auth-use-require-user`](references/auth-use-require-user.md) — Centralize the auth gate in one `requireUser()` helper.
- [`auth-server-only-imports`](references/auth-server-only-imports.md) — Mark privileged modules with `import 'server-only'`.
- [`auth-mfa-in-middleware`](references/auth-mfa-in-middleware.md) — Enforce MFA at the `proxy.ts` boundary, not per-page.

### 2. Multi-Tenancy (CRITICAL — optional, SaaS only)

- [`tenant-accounts-as-tenant-root`](references/tenant-accounts-as-tenant-root.md) — One tenant-root table both personal and team workspaces reference.
- [`tenant-account-id-on-product-tables`](references/tenant-account-id-on-product-tables.md) — Tenant key + index + scoping policy on every product table.
- [`tenant-slug-in-team-urls`](references/tenant-slug-in-team-urls.md) — Use a human-readable slug in team URLs, not the UUID.
- [`tenant-storage-paths-include-account-id`](references/tenant-storage-paths-include-account-id.md) — Namespace object-storage paths by tenant id.
- [`tenant-never-edit-generated-types`](references/tenant-never-edit-generated-types.md) — Treat generated DB types as build output; regenerate, never hand-edit.

### 3. Request Boundary: Proxy (HIGH)

- [`proxy-single-pipeline`](references/proxy-single-pipeline.md) — Compose the whole request pipeline in one `proxy.ts`.
- [`proxy-redirect-auth-at-boundary`](references/proxy-redirect-auth-at-boundary.md) — Perform auth redirects at the proxy, not in pages.
- [`proxy-url-pattern-matching`](references/proxy-url-pattern-matching.md) — Match proxy routes with `URLPattern`, not string comparisons.
- [`proxy-set-correlation-id`](references/proxy-set-correlation-id.md) — Set a correlation ID at the request boundary.
- [`proxy-secure-headers-flagged`](references/proxy-secure-headers-flagged.md) — Apply strict CSP headers behind an environment flag.

### 4. Server-Side Data Loading (HIGH)

- [`server-cache-workspace-loaders`](references/server-cache-workspace-loaders.md) — Wrap per-request loaders with `cache()` from React.
- [`server-promise-all-parallel-loads`](references/server-promise-all-parallel-loads.md) — Load independent data in parallel with `Promise.all`.
- [`server-use-feature-api-factories`](references/server-use-feature-api-factories.md) — Read through a typed data-access factory, not raw `from('table')`.
- [`server-redirect-on-missing-workspace`](references/server-redirect-on-missing-workspace.md) — Redirect from the loader when workspace state is invalid.
- [`server-fetch-in-server-components`](references/server-fetch-in-server-components.md) — Fetch initial data in server components, not on the client.
- [`server-use-tables-generic-for-types`](references/server-use-tables-generic-for-types.md) — Use generated row types, not hand-written interfaces.
- [`server-services-receive-client`](references/server-services-receive-client.md) — Services receive the data client as a constructor argument.

### 5. Mutations: Actions & Route Handlers (HIGH)

- [`mutate-use-safe-action-clients`](references/mutate-use-safe-action-clients.md) — Route mutations through a typed action client you build on next-safe-action.
- [`mutate-zod-schema-separate-file`](references/mutate-zod-schema-separate-file.md) — Put Zod schemas in their own `*.schema.ts` shared by client and server.
- [`mutate-thin-action-service-holds-logic`](references/mutate-thin-action-service-holds-logic.md) — Keep the action thin; put business logic in a service.
- [`mutate-use-getlogger-not-console`](references/mutate-use-getlogger-not-console.md) — Log through a structured logger you own, not `console.log`.
- [`mutate-revalidate-path-after-write`](references/mutate-revalidate-path-after-write.md) — Call `revalidatePath()` after a successful write.
- [`mutate-enhance-route-handler`](references/mutate-enhance-route-handler.md) — Wrap route handlers in a typed handler that owns auth and validation.
- [`mutate-webhook-verify-signature`](references/mutate-webhook-verify-signature.md) — Webhook routes skip user-auth and verify the provider signature.

### 6. Client/Server Boundaries (MEDIUM-HIGH)

- [`client-use-client-at-leaves`](references/client-use-client-at-leaves.md) — Mark `'use client'` at leaf components, not page roots.
- [`client-pass-server-data-as-props`](references/client-pass-server-data-as-props.md) — Pass server data to client components as props, don't refetch.
- [`client-use-supabase-with-react-query`](references/client-use-supabase-with-react-query.md) — Pair a memoized browser client with TanStack Query for client reads.
- [`client-realtime-cleanup-subscription`](references/client-realtime-cleanup-subscription.md) — Tear down any subscription or event source in the `useEffect` return.
- [`client-use-action-hook`](references/client-use-action-hook.md) — Call server actions with `useAction` from `next-safe-action/hooks`.
- [`client-stable-query-keys`](references/client-stable-query-keys.md) — Use stable, hierarchical query keys.

### 7. Architecture & Services (MEDIUM)

- [`arch-app-vs-packages-boundary`](references/arch-app-vs-packages-boundary.md) — Reusable capabilities in `packages/`, product-specific code in `apps/web`.
- [`arch-data-access-adapter`](references/arch-data-access-adapter.md) — Confine the backend to one data-access package with a stable surface.
- [`arch-feature-package-layout`](references/arch-feature-package-layout.md) — Feature packages follow a `components / hooks / schema / server` layout.
- [`arch-import-via-package-exports`](references/arch-import-via-package-exports.md) — Import via the package `exports` map, never deep internal paths.
- [`arch-provider-gateway-pattern`](references/arch-provider-gateway-pattern.md) — Hide vendor SDKs behind a gateway interface.
- [`arch-policy-engine-for-business-rules`](references/arch-policy-engine-for-business-rules.md) — Model business rules in a policy layer you own, not inline conditionals.
- [`arch-config-driven-navigation`](references/arch-config-driven-navigation.md) — Define routes and navigation in `config/`, not hardcoded in components.

### 8. Forms & UI Conventions (MEDIUM)

- [`ui-rhf-zod-no-generics`](references/ui-rhf-zod-no-generics.md) — Let `zodResolver` infer form types; don't add `useForm` generics.
- [`ui-form-message-per-field`](references/ui-form-message-per-field.md) — Include `FormMessage` for every field.
- [`ui-kit-ui-package-imports`](references/ui-kit-ui-package-imports.md) — Import UI from your `@app/ui` design-system surface, never internal paths.
- [`ui-semantic-tailwind-tokens`](references/ui-semantic-tailwind-tokens.md) — Use semantic Tailwind tokens, not hardcoded colors.
- [`ui-base-ui-render-not-aschild`](references/ui-base-ui-render-not-aschild.md) — Use Base UI `render` prop, not Radix `asChild`.
- [`ui-trans-for-display-text`](references/ui-trans-for-display-text.md) — Render display text through `<Trans>` or `useTranslations`.

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) — Category structure, impact levels, lifecycle rationale.
- [Rule template](assets/templates/_template.md) — Template for adding new rules.
- [AGENTS.md](AGENTS.md) — Auto-generated TOC for fast navigation.

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions and ordering by lifecycle impact |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for adding new rules |
| [metadata.json](metadata.json) | Version, organization, references |

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills