148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# Route Handlers + Drizzle Guide
|
|
|
|
Use this guide when a feature should stop relying on mock data and start using the app's real server boundary.
|
|
|
|
## Default request flow
|
|
|
|
The preferred flow in this repo is:
|
|
|
|
`component -> service.ts -> /api route handler -> Drizzle -> database`
|
|
|
|
This keeps:
|
|
|
|
- React components UI-focused
|
|
- route handlers responsible for auth, org resolution, and HTTP behavior
|
|
- Drizzle access on the server only
|
|
|
|
Avoid these paths as defaults:
|
|
|
|
- `component -> mock-api`
|
|
- `component -> Drizzle directly`
|
|
- `client component -> external DB client`
|
|
|
|
## Build order
|
|
|
|
### 1. Schema first
|
|
|
|
Define tables and relations before writing React code.
|
|
|
|
Typical pieces:
|
|
|
|
- feature table such as `orders`
|
|
- optional `organizationId` foreign key
|
|
- audit columns such as `createdAt` and `updatedAt`
|
|
|
|
If the task includes org-aware access, make tenant ownership explicit in the schema.
|
|
|
|
### 2. API contract second
|
|
|
|
In `src/features/<feature>/api/types.ts`, define:
|
|
|
|
- entity shape used by the UI
|
|
- list filters
|
|
- list response
|
|
- detail response
|
|
- mutation payloads
|
|
|
|
Keep response types stable even if the schema is denormalized underneath.
|
|
|
|
### 3. Route handlers third
|
|
|
|
Implement:
|
|
|
|
- `src/app/api/<feature>/route.ts` for `GET` list and `POST` create
|
|
- `src/app/api/<feature>/[id]/route.ts` for `GET`, `PATCH` or `PUT`, and `DELETE`
|
|
|
|
Responsibilities:
|
|
|
|
- authenticate the request
|
|
- resolve active organization
|
|
- check membership or role
|
|
- parse request params and body
|
|
- query or mutate via Drizzle
|
|
- return consistent JSON
|
|
|
|
## Example list handler
|
|
|
|
```tsx
|
|
import { and, count, desc, eq, ilike } from 'drizzle-orm';
|
|
import { NextRequest, NextResponse } from 'next/server';
|
|
import { auth } from '@/auth';
|
|
import { db } from '@/lib/db';
|
|
import { memberships, orders } from '@/db/schema';
|
|
|
|
export async function GET(request: NextRequest) {
|
|
const session = await auth();
|
|
if (!session?.user?.id) {
|
|
return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
|
|
}
|
|
|
|
const { searchParams } = request.nextUrl;
|
|
const page = Number(searchParams.get('page') ?? 1);
|
|
const limit = Number(searchParams.get('limit') ?? 10);
|
|
const search = searchParams.get('search') ?? '';
|
|
const offset = (page - 1) * limit;
|
|
|
|
const membership = await db.query.memberships.findFirst({
|
|
where: eq(memberships.userId, session.user.id)
|
|
});
|
|
|
|
if (!membership) {
|
|
return NextResponse.json({ message: 'Organization membership required' }, { status: 403 });
|
|
}
|
|
|
|
const whereClause = and(
|
|
eq(orders.organizationId, membership.organizationId),
|
|
search ? ilike(orders.customerName, `%${search}%`) : undefined
|
|
);
|
|
|
|
const [items, totalRows] = await Promise.all([
|
|
db.select().from(orders).where(whereClause).orderBy(desc(orders.createdAt)).limit(limit).offset(offset),
|
|
db.select({ value: count() }).from(orders).where(whereClause)
|
|
]);
|
|
|
|
return NextResponse.json({
|
|
items,
|
|
totalItems: totalRows[0]?.value ?? 0
|
|
});
|
|
}
|
|
```
|
|
|
|
## Service layer pattern
|
|
|
|
`service.ts` should call the local route handlers through `apiClient`.
|
|
|
|
```tsx
|
|
import { apiClient } from '@/lib/api-client';
|
|
import type { Order, OrderFilters, OrdersResponse, OrderMutationPayload } from './types';
|
|
|
|
export async function getOrders(filters: OrderFilters): Promise<OrdersResponse> {
|
|
const searchParams = new URLSearchParams();
|
|
if (filters.page) searchParams.set('page', String(filters.page));
|
|
if (filters.limit) searchParams.set('limit', String(filters.limit));
|
|
if (filters.search) searchParams.set('search', filters.search);
|
|
if (filters.status) searchParams.set('status', filters.status);
|
|
if (filters.sort) searchParams.set('sort', filters.sort);
|
|
|
|
return apiClient<OrdersResponse>(`/orders?${searchParams.toString()}`);
|
|
}
|
|
|
|
export async function createOrder(values: OrderMutationPayload): Promise<Order> {
|
|
return apiClient<Order>('/orders', {
|
|
method: 'POST',
|
|
body: JSON.stringify(values)
|
|
});
|
|
}
|
|
```
|
|
|
|
## Migration advice for this repo
|
|
|
|
If the task is migrating existing code:
|
|
|
|
- start with `products` or `users` because both already have route-handler shells
|
|
- swap `service.ts` away from `fakeProducts` or `fakeUsers`
|
|
- replace route-handler mock implementations with Drizzle queries
|
|
- keep `queries.ts` and UI mostly stable where possible
|
|
|
|
That minimizes UI churn and isolates the migration to the intended seam.
|