@1aboveio/app-dev-skills 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -2
- package/package.json +33 -4
- package/skills/airflow/LICENSE +3 -0
- package/skills/airflow/SKILL.md +199 -0
- package/skills/airflow/release-check.mjs +93 -0
- package/skills/android-foundation/LICENSE +3 -0
- package/skills/android-foundation/SKILL.md +192 -0
- package/skills/android-foundation/assets/android-ci-job.yml +217 -0
- package/skills/android-foundation/references/ci.md +87 -0
- package/skills/android-foundation/references/gotchas.md +221 -0
- package/skills/android-foundation/references/setup.md +164 -0
- package/skills/android-foundation/release-check.mjs +93 -0
- package/skills/android-foundation/scripts/device-run.sh +176 -0
- package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
- package/skills/app-debug/LICENSE +3 -0
- package/skills/app-debug/SKILL.md +110 -0
- package/skills/app-debug/references/common-errors.md +128 -0
- package/skills/app-debug/release-check.mjs +93 -0
- package/skills/better-auth/LICENSE +3 -0
- package/skills/better-auth/SKILL.md +598 -0
- package/skills/better-auth/references/feishu-api.md +270 -0
- package/skills/better-auth/release-check.mjs +93 -0
- package/skills/ios-foundation/LICENSE +3 -0
- package/skills/ios-foundation/SKILL.md +184 -0
- package/skills/ios-foundation/references/setup.md +243 -0
- package/skills/ios-foundation/release-check.mjs +93 -0
- package/skills/monorepo/LICENSE +3 -0
- package/skills/monorepo/SKILL.md +462 -0
- package/skills/monorepo/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/LICENSE +3 -0
- package/skills/nextjs-fullstack/SKILL.md +211 -0
- package/skills/nextjs-fullstack/conventions.md +318 -0
- package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
- package/skills/nextjs-fullstack/nextjs16.md +287 -0
- package/skills/nextjs-fullstack/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/server-actions.md +409 -0
- package/skills/prisma-setup/LICENSE +3 -0
- package/skills/prisma-setup/SKILL.md +181 -0
- package/skills/prisma-setup/nextjs.md +258 -0
- package/skills/prisma-setup/release-check.mjs +93 -0
- package/skills/prisma-setup/turborepo.md +301 -0
- package/skills/pyspark/LICENSE +3 -0
- package/skills/pyspark/SKILL.md +127 -0
- package/skills/pyspark/assets/templates/etl.py +748 -0
- package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
- package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
- package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
- package/skills/pyspark/references/etl-contract.md +129 -0
- package/skills/pyspark/references/production-validation.md +131 -0
- package/skills/pyspark/references/reconciliation.md +38 -0
- package/skills/pyspark/references/transformation-design.md +190 -0
- package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
- package/skills/pyspark/release-check.mjs +93 -0
- package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
- package/skills/python-backend/LICENSE +3 -0
- package/skills/python-backend/SKILL.md +325 -0
- package/skills/python-backend/assets/uv-install.sh +48 -0
- package/skills/python-backend/references/uv-installs.md +83 -0
- package/skills/python-backend/release-check.mjs +93 -0
- package/skills/shadcn/LICENSE +3 -0
- package/skills/shadcn/SKILL.md +120 -0
- package/skills/shadcn/assets/shadcn-small.png +0 -0
- package/skills/shadcn/assets/shadcn.png +0 -0
- package/skills/shadcn/cli.md +411 -0
- package/skills/shadcn/customization.md +224 -0
- package/skills/shadcn/mcp.md +101 -0
- package/skills/shadcn/release-check.mjs +93 -0
- package/skills/shadcn/rules/base-vs-radix.md +323 -0
- package/skills/shadcn/rules/component-selection.md +67 -0
- package/skills/shadcn/rules/composition.md +195 -0
- package/skills/shadcn/rules/data-table.md +201 -0
- package/skills/shadcn/rules/forms.md +255 -0
- package/skills/shadcn/rules/icons.md +103 -0
- package/skills/shadcn/rules/styling.md +167 -0
- package/skills/zod-v4/LICENSE +3 -0
- package/skills/zod-v4/SKILL.md +286 -0
- package/skills/zod-v4/release-check.mjs +93 -0
|
@@ -0,0 +1,409 @@
|
|
|
1
|
+
# React 19 Server Action Patterns
|
|
2
|
+
|
|
3
|
+
Full-stack form pattern using `useActionState`, `serverAction` wrapper, `withCallbacks`, and Zod validation.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Data Flow
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
User submits form
|
|
11
|
+
|
|
|
12
|
+
handleSubmit (react-hook-form + zod)
|
|
13
|
+
|
|
|
14
|
+
startTransition -> formAction(payload)
|
|
15
|
+
|
|
|
16
|
+
withCallbacks intercepts call
|
|
17
|
+
|
|
|
18
|
+
Server action runs (isPending = true)
|
|
19
|
+
|- beforeAction (auth check)
|
|
20
|
+
|- Zod validation
|
|
21
|
+
|- DAL function execution
|
|
22
|
+
|- onSuccess (revalidatePath)
|
|
23
|
+
|
|
|
24
|
+
Returns ActionState
|
|
25
|
+
|
|
|
26
|
+
withCallbacks triggers success/error callback
|
|
27
|
+
|- onSuccess: toast, reset, close dialog
|
|
28
|
+
|- onError: toast error, rollback optimistic
|
|
29
|
+
|
|
|
30
|
+
Component re-renders
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Core Utilities
|
|
36
|
+
|
|
37
|
+
### ActionState Type
|
|
38
|
+
|
|
39
|
+
```typescript
|
|
40
|
+
// lib/server-action.ts
|
|
41
|
+
export type ActionState<T = unknown> = {
|
|
42
|
+
success: boolean;
|
|
43
|
+
message?: string;
|
|
44
|
+
error?: {
|
|
45
|
+
code: number;
|
|
46
|
+
detail?: string;
|
|
47
|
+
};
|
|
48
|
+
data?: T;
|
|
49
|
+
};
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
### withCallbacks
|
|
53
|
+
|
|
54
|
+
Wraps async actions with success/error callbacks:
|
|
55
|
+
|
|
56
|
+
```typescript
|
|
57
|
+
type Callbacks<T> = {
|
|
58
|
+
onSuccess?: (state: T) => void;
|
|
59
|
+
onError?: (state: T) => void;
|
|
60
|
+
};
|
|
61
|
+
|
|
62
|
+
export function withCallbacks<Args extends unknown[], T extends ActionState>(
|
|
63
|
+
fn: (...args: Args) => Promise<T>,
|
|
64
|
+
callbacks: Callbacks<T>
|
|
65
|
+
): (...args: Args) => Promise<T> {
|
|
66
|
+
return async (...args: Args) => {
|
|
67
|
+
const state = await fn(...args);
|
|
68
|
+
|
|
69
|
+
if (state?.success === true) {
|
|
70
|
+
callbacks.onSuccess?.(state);
|
|
71
|
+
} else if (state?.success === false) {
|
|
72
|
+
callbacks.onError?.(state);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
return state;
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### serverAction Factory
|
|
81
|
+
|
|
82
|
+
```typescript
|
|
83
|
+
export type ServerActionOptions<TInput extends z.ZodTypeAny> = {
|
|
84
|
+
beforeAction?: () => Promise<void>;
|
|
85
|
+
onSuccess?: (data: z.infer<TInput>) => Promise<void>;
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
export function serverAction<TInput extends z.ZodTypeAny, TOutput>(
|
|
89
|
+
action: (data: z.infer<TInput>) => Promise<TOutput>,
|
|
90
|
+
schema: TInput,
|
|
91
|
+
options?: ServerActionOptions<TInput>
|
|
92
|
+
) {
|
|
93
|
+
return async (
|
|
94
|
+
_previousState: unknown,
|
|
95
|
+
payload: z.infer<TInput>
|
|
96
|
+
): Promise<ActionState<TOutput>> => {
|
|
97
|
+
try {
|
|
98
|
+
if (options?.beforeAction) {
|
|
99
|
+
await options.beforeAction();
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
const validated = await schema.safeParseAsync(payload);
|
|
103
|
+
if (!validated.success) {
|
|
104
|
+
return {
|
|
105
|
+
success: false,
|
|
106
|
+
message: "Validation failed",
|
|
107
|
+
error: { code: 422, detail: validated.error.message },
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
const result = await action(validated.data);
|
|
112
|
+
|
|
113
|
+
if (options?.onSuccess) {
|
|
114
|
+
await options.onSuccess(validated.data);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return { success: true, message: "Success", data: result };
|
|
118
|
+
} catch (error: unknown) {
|
|
119
|
+
console.error("Server action error:", error);
|
|
120
|
+
return {
|
|
121
|
+
success: false,
|
|
122
|
+
message: error instanceof Error ? error.message : "Error occurred",
|
|
123
|
+
error: { code: 500 },
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
};
|
|
127
|
+
}
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Authentication Hooks
|
|
133
|
+
|
|
134
|
+
```typescript
|
|
135
|
+
// lib/require-auth.ts
|
|
136
|
+
"use server";
|
|
137
|
+
|
|
138
|
+
import { auth } from "@/lib/auth";
|
|
139
|
+
import { headers } from "next/headers";
|
|
140
|
+
import { cache } from "react";
|
|
141
|
+
import prisma from "@/lib/prisma";
|
|
142
|
+
|
|
143
|
+
export const getSession = cache(async () => {
|
|
144
|
+
return await auth.api.getSession({ headers: await headers() });
|
|
145
|
+
});
|
|
146
|
+
|
|
147
|
+
export async function requireAuth() {
|
|
148
|
+
const session = await getSession();
|
|
149
|
+
if (!session?.user?.id) {
|
|
150
|
+
throw new Error("Unauthorized");
|
|
151
|
+
}
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
export async function requireAdmin() {
|
|
155
|
+
const session = await getSession();
|
|
156
|
+
if (!session?.user?.id) throw new Error("Unauthorized");
|
|
157
|
+
|
|
158
|
+
const user = await prisma.user.findUnique({
|
|
159
|
+
where: { id: session.user.id },
|
|
160
|
+
select: { role: true },
|
|
161
|
+
});
|
|
162
|
+
|
|
163
|
+
if (user?.role !== "admin") throw new Error("Admin required");
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
export function requireOrgAccess(organizationId: string) {
|
|
167
|
+
return async () => {
|
|
168
|
+
const session = await getSession();
|
|
169
|
+
if (!session?.user?.id) throw new Error("Unauthorized");
|
|
170
|
+
|
|
171
|
+
const membership = await prisma.organizationMember.findFirst({
|
|
172
|
+
where: { userId: session.user.id, organizationId },
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
if (!membership) throw new Error("No access");
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## Server Action Definition
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
// app/dashboard/actions.ts
|
|
186
|
+
"use server";
|
|
187
|
+
|
|
188
|
+
import { revalidatePath } from "next/cache";
|
|
189
|
+
import { serverAction } from "@/lib/server-action";
|
|
190
|
+
import { requireAuth, requireAdmin } from "@/lib/require-auth";
|
|
191
|
+
import { createOrganizationDAL, deleteOrganizationDAL } from "@/dal/organization";
|
|
192
|
+
import { createOrgSchema, deleteOrgSchema } from "@/types/organization";
|
|
193
|
+
|
|
194
|
+
// Basic with auth + revalidation
|
|
195
|
+
export const createOrganization = serverAction(
|
|
196
|
+
createOrganizationDAL,
|
|
197
|
+
createOrgSchema,
|
|
198
|
+
{
|
|
199
|
+
beforeAction: requireAuth,
|
|
200
|
+
onSuccess: async () => revalidatePath("/organization"),
|
|
201
|
+
}
|
|
202
|
+
);
|
|
203
|
+
|
|
204
|
+
// Admin-only
|
|
205
|
+
export const deleteOrganization = serverAction(
|
|
206
|
+
deleteOrganizationDAL,
|
|
207
|
+
deleteOrgSchema,
|
|
208
|
+
{
|
|
209
|
+
beforeAction: requireAdmin,
|
|
210
|
+
onSuccess: async () => revalidatePath("/organization"),
|
|
211
|
+
}
|
|
212
|
+
);
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Client Component: Basic Form
|
|
218
|
+
|
|
219
|
+
```tsx
|
|
220
|
+
"use client";
|
|
221
|
+
|
|
222
|
+
import { startTransition, useActionState, useMemo, useState } from "react";
|
|
223
|
+
import { useForm } from "react-hook-form";
|
|
224
|
+
import { zodResolver } from "@hookform/resolvers/zod";
|
|
225
|
+
import { toast } from "sonner";
|
|
226
|
+
import { z } from "zod";
|
|
227
|
+
import { withCallbacks } from "@/lib/server-action";
|
|
228
|
+
|
|
229
|
+
const schema = z.object({
|
|
230
|
+
name: z.string().min(1),
|
|
231
|
+
email: z.string().email(),
|
|
232
|
+
});
|
|
233
|
+
type FormData = z.infer<typeof schema>;
|
|
234
|
+
|
|
235
|
+
interface Props {
|
|
236
|
+
action: (state: unknown, payload: FormData) => Promise<ActionState>;
|
|
237
|
+
onSuccess?: () => void;
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
export function CreateUserForm({ action, onSuccess }: Props) {
|
|
241
|
+
const { register, handleSubmit, reset, formState: { errors } } = useForm<FormData>({
|
|
242
|
+
resolver: zodResolver(schema),
|
|
243
|
+
});
|
|
244
|
+
const [open, setOpen] = useState(false);
|
|
245
|
+
|
|
246
|
+
// 1. Wrap with callbacks (memoize when deps change)
|
|
247
|
+
const wrappedAction = useMemo(
|
|
248
|
+
() => withCallbacks(action, {
|
|
249
|
+
onSuccess: (state) => {
|
|
250
|
+
toast.success(state.message || "Created");
|
|
251
|
+
reset();
|
|
252
|
+
onSuccess?.();
|
|
253
|
+
setOpen(false);
|
|
254
|
+
},
|
|
255
|
+
onError: (state) => {
|
|
256
|
+
toast.error(state.message || "Failed");
|
|
257
|
+
},
|
|
258
|
+
}),
|
|
259
|
+
[action, reset, onSuccess]
|
|
260
|
+
);
|
|
261
|
+
|
|
262
|
+
// 2. Use wrapped action
|
|
263
|
+
const [, formAction, isPending] = useActionState(wrappedAction, undefined);
|
|
264
|
+
|
|
265
|
+
// 3. Submit with startTransition
|
|
266
|
+
function onSubmit(data: FormData) {
|
|
267
|
+
startTransition(() => formAction(data));
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
return (
|
|
271
|
+
<form onSubmit={handleSubmit(onSubmit)}>
|
|
272
|
+
<input {...register("name")} />
|
|
273
|
+
{errors.name && <p>{errors.name.message}</p>}
|
|
274
|
+
<input {...register("email")} type="email" />
|
|
275
|
+
{errors.email && <p>{errors.email.message}</p>}
|
|
276
|
+
<button disabled={isPending}>Save</button>
|
|
277
|
+
</form>
|
|
278
|
+
);
|
|
279
|
+
}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## Optimistic Updates
|
|
285
|
+
|
|
286
|
+
```tsx
|
|
287
|
+
"use client";
|
|
288
|
+
|
|
289
|
+
import { startTransition, useActionState, useState } from "react";
|
|
290
|
+
import { withCallbacks } from "@/lib/server-action";
|
|
291
|
+
import { toast } from "sonner";
|
|
292
|
+
|
|
293
|
+
export function StatusToggle({ initialEnabled, action }) {
|
|
294
|
+
const [enabled, setEnabled] = useState(initialEnabled);
|
|
295
|
+
const [previousEnabled, setPreviousEnabled] = useState(initialEnabled);
|
|
296
|
+
|
|
297
|
+
const [, toggleAction, isPending] = useActionState(
|
|
298
|
+
withCallbacks(action, {
|
|
299
|
+
onSuccess: () => toast.success("Updated"),
|
|
300
|
+
onError: (result) => {
|
|
301
|
+
toast.error(result.message);
|
|
302
|
+
setEnabled(previousEnabled); // Rollback
|
|
303
|
+
},
|
|
304
|
+
}),
|
|
305
|
+
null
|
|
306
|
+
);
|
|
307
|
+
|
|
308
|
+
function onToggle() {
|
|
309
|
+
setPreviousEnabled(enabled); // Save for rollback
|
|
310
|
+
setEnabled(!enabled); // Optimistic update
|
|
311
|
+
|
|
312
|
+
startTransition(() => {
|
|
313
|
+
toggleAction({ enabled: !enabled });
|
|
314
|
+
});
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
return (
|
|
318
|
+
<button onClick={onToggle} disabled={isPending}>
|
|
319
|
+
{enabled ? "Enabled" : "Disabled"}
|
|
320
|
+
</button>
|
|
321
|
+
);
|
|
322
|
+
}
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
---
|
|
326
|
+
|
|
327
|
+
## Auth Forms (Direct Client)
|
|
328
|
+
|
|
329
|
+
For auth client calls (not DAL):
|
|
330
|
+
|
|
331
|
+
```tsx
|
|
332
|
+
"use client";
|
|
333
|
+
|
|
334
|
+
import { startTransition, useActionState, useEffect } from "react";
|
|
335
|
+
import { useRouter } from "next/navigation";
|
|
336
|
+
import { useForm } from "react-hook-form";
|
|
337
|
+
import { zodResolver } from "@hookform/resolvers/zod";
|
|
338
|
+
import { z } from "zod";
|
|
339
|
+
import { authClient } from "@/lib/auth-client";
|
|
340
|
+
import type { ActionState } from "@/lib/server-action";
|
|
341
|
+
|
|
342
|
+
const loginSchema = z.object({
|
|
343
|
+
email: z.string().email(),
|
|
344
|
+
password: z.string().min(8),
|
|
345
|
+
});
|
|
346
|
+
|
|
347
|
+
export function LoginForm() {
|
|
348
|
+
const router = useRouter();
|
|
349
|
+
const { handleSubmit, register } = useForm({
|
|
350
|
+
resolver: zodResolver(loginSchema),
|
|
351
|
+
});
|
|
352
|
+
|
|
353
|
+
const [state, formAction, isPending] = useActionState<ActionState, FormData>(
|
|
354
|
+
async (prev, data) => {
|
|
355
|
+
const result = await authClient.signIn.email(data);
|
|
356
|
+
if (result.error) {
|
|
357
|
+
return { success: false, message: result.error.message };
|
|
358
|
+
}
|
|
359
|
+
return { success: true, data: result.data };
|
|
360
|
+
},
|
|
361
|
+
{ success: false }
|
|
362
|
+
);
|
|
363
|
+
|
|
364
|
+
useEffect(() => {
|
|
365
|
+
if (state.success) router.push("/dashboard");
|
|
366
|
+
}, [state, router]);
|
|
367
|
+
|
|
368
|
+
function onSubmit(data) {
|
|
369
|
+
startTransition(() => formAction(data));
|
|
370
|
+
}
|
|
371
|
+
|
|
372
|
+
return (
|
|
373
|
+
<form onSubmit={handleSubmit(onSubmit)}>
|
|
374
|
+
<input {...register("email")} type="email" />
|
|
375
|
+
<input {...register("password")} type="password" />
|
|
376
|
+
{!state.success && state.message && <p>{state.message}</p>}
|
|
377
|
+
<button disabled={isPending}>Log in</button>
|
|
378
|
+
</form>
|
|
379
|
+
);
|
|
380
|
+
}
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
---
|
|
384
|
+
|
|
385
|
+
## Key Rules
|
|
386
|
+
|
|
387
|
+
| Rule | Implementation |
|
|
388
|
+
|------|----------------|
|
|
389
|
+
| Always use `startTransition` | Prevents UI blocking |
|
|
390
|
+
| Wrap with `useMemo` | When callbacks have changing deps |
|
|
391
|
+
| Pass action as prop | Dependency injection |
|
|
392
|
+
| Zod validation | Server in serverAction, client in react-hook-form |
|
|
393
|
+
| Toast in withCallbacks | Keep UI feedback in callbacks |
|
|
394
|
+
| Revalidate in serverAction | Cache invalidation via onSuccess |
|
|
395
|
+
| Optimistic updates | Store previous, update UI, rollback on error |
|
|
396
|
+
| Auth in beforeAction | Use requireAuth/requireAdmin hooks |
|
|
397
|
+
|
|
398
|
+
---
|
|
399
|
+
|
|
400
|
+
## When to Use Each Approach
|
|
401
|
+
|
|
402
|
+
| Use Case | Approach |
|
|
403
|
+
|----------|----------|
|
|
404
|
+
| Database mutations | `serverAction` + DAL |
|
|
405
|
+
| Auth client calls | Inline async in `useActionState` |
|
|
406
|
+
| API routes | Inline async in `useActionState` |
|
|
407
|
+
| Sensitive operations | `serverAction` with `beforeAction` |
|
|
408
|
+
| Cookie/session access | `serverAction` |
|
|
409
|
+
| Public forms | `serverAction` without `beforeAction` |
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: prisma-setup
|
|
3
|
+
description: Use when adding or debugging Prisma with PostgreSQL, Next.js, or Turborepo, including schema.prisma, prisma.config.ts, client generation, migrations, seeds, relations, adapters, and DAL/database-layer setup. Triggers on phrases like "Prisma schema", "prisma migrate", "schema.prisma", "seed the database", "PrismaClient error", "relation issue", or "database layer".
|
|
4
|
+
release-version: 0.36.0
|
|
5
|
+
---
|
|
6
|
+
**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
|
|
7
|
+
# Prisma v7 Setup Guide
|
|
8
|
+
|
|
9
|
+
**Prisma ORM v7** | **PostgreSQL** | **@prisma/adapter-pg**
|
|
10
|
+
|
|
11
|
+
## Reference Guides
|
|
12
|
+
|
|
13
|
+
- [Next.js + Prisma v7](nextjs.md) - Standalone Next.js setup
|
|
14
|
+
- [Turborepo + Prisma v7](turborepo.md) - Monorepo with shared DB package
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Critical Prisma v7 Requirements
|
|
19
|
+
|
|
20
|
+
### Generator Configuration
|
|
21
|
+
|
|
22
|
+
```prisma
|
|
23
|
+
generator client {
|
|
24
|
+
provider = "prisma-client" # NOT "prisma-client-js"
|
|
25
|
+
output = "../app/generated/prisma" # Custom output REQUIRED
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
datasource db {
|
|
29
|
+
provider = "postgresql"
|
|
30
|
+
# NO url here - moved to prisma.config.ts
|
|
31
|
+
}
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
### Client Import Path
|
|
35
|
+
|
|
36
|
+
```typescript
|
|
37
|
+
// CORRECT - include /client at the end
|
|
38
|
+
import { PrismaClient } from "../app/generated/prisma/client"
|
|
39
|
+
|
|
40
|
+
// WRONG - missing /client
|
|
41
|
+
import { PrismaClient } from "../app/generated/prisma"
|
|
42
|
+
|
|
43
|
+
// WRONG - default location
|
|
44
|
+
import { PrismaClient } from "@prisma/client"
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### Prisma Config (prisma.config.ts)
|
|
48
|
+
|
|
49
|
+
```typescript
|
|
50
|
+
import "dotenv/config" // REQUIRED at top
|
|
51
|
+
import { defineConfig, env } from "prisma/config"
|
|
52
|
+
|
|
53
|
+
export default defineConfig({
|
|
54
|
+
schema: "prisma/schema.prisma",
|
|
55
|
+
migrations: {
|
|
56
|
+
path: "prisma/migrations",
|
|
57
|
+
},
|
|
58
|
+
// NO engine property - removed in v7
|
|
59
|
+
datasource: {
|
|
60
|
+
url: env("DATABASE_URL"),
|
|
61
|
+
},
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Client Singleton
|
|
66
|
+
|
|
67
|
+
```typescript
|
|
68
|
+
// lib/prisma.ts
|
|
69
|
+
import { PrismaClient } from "../app/generated/prisma/client"
|
|
70
|
+
import { PrismaPg } from "@prisma/adapter-pg"
|
|
71
|
+
|
|
72
|
+
const adapter = new PrismaPg({
|
|
73
|
+
connectionString: process.env.DATABASE_URL!,
|
|
74
|
+
})
|
|
75
|
+
|
|
76
|
+
const globalForPrisma = global as unknown as { prisma: PrismaClient }
|
|
77
|
+
|
|
78
|
+
const prisma = globalForPrisma.prisma || new PrismaClient({ adapter })
|
|
79
|
+
|
|
80
|
+
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma
|
|
81
|
+
|
|
82
|
+
export default prisma
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Deprecated Patterns (NEVER USE)
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
// DEPRECATED - prisma-client-js
|
|
91
|
+
generator client {
|
|
92
|
+
provider = "prisma-client-js"
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
// DEPRECATED - url in datasource
|
|
96
|
+
datasource db {
|
|
97
|
+
provider = "postgresql"
|
|
98
|
+
url = env("DATABASE_URL")
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// DEPRECATED - engine property
|
|
102
|
+
export default defineConfig({
|
|
103
|
+
engine: "classic", // REMOVED in v7
|
|
104
|
+
})
|
|
105
|
+
|
|
106
|
+
// DEPRECATED - accelerateUrl
|
|
107
|
+
new PrismaClient({
|
|
108
|
+
accelerateUrl: process.env.DATABASE_URL,
|
|
109
|
+
})
|
|
110
|
+
|
|
111
|
+
// DEPRECATED - Accelerate extension (for TCP connections)
|
|
112
|
+
import { withAccelerate } from "@prisma/extension-accelerate"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Version Requirements
|
|
118
|
+
|
|
119
|
+
- **Node.js:** 20.19+ (Node 18 NOT supported)
|
|
120
|
+
- **TypeScript:** 5.4.0+
|
|
121
|
+
- **Prisma:** 7.0.0+
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Installation
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
# Dev dependencies
|
|
129
|
+
npm install prisma tsx --save-dev
|
|
130
|
+
|
|
131
|
+
# Production dependencies
|
|
132
|
+
npm install @prisma/adapter-pg @prisma/client dotenv
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Database URL
|
|
138
|
+
|
|
139
|
+
Must use standard TCP URL:
|
|
140
|
+
|
|
141
|
+
```env
|
|
142
|
+
# CORRECT
|
|
143
|
+
DATABASE_URL="postgres://user:pass@host:5432/db"
|
|
144
|
+
|
|
145
|
+
# WRONG - HTTP URL
|
|
146
|
+
DATABASE_URL="prisma+postgres://accelerate.prisma-data.net/..."
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
---
|
|
150
|
+
|
|
151
|
+
## Common Commands
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
# Generate client
|
|
155
|
+
npx prisma generate
|
|
156
|
+
|
|
157
|
+
# Push schema (no migrations)
|
|
158
|
+
npx prisma db push
|
|
159
|
+
|
|
160
|
+
# Create migration
|
|
161
|
+
npx prisma migrate dev --name your_migration
|
|
162
|
+
|
|
163
|
+
# Open Studio
|
|
164
|
+
npx prisma studio
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
---
|
|
168
|
+
|
|
169
|
+
## Verification Checklist
|
|
170
|
+
|
|
171
|
+
Before writing any Prisma code, verify:
|
|
172
|
+
|
|
173
|
+
1. `provider = "prisma-client"` (not prisma-client-js)
|
|
174
|
+
2. Custom `output` path specified
|
|
175
|
+
3. Import from `generated/prisma/client` (with /client)
|
|
176
|
+
4. `import "dotenv/config"` in prisma.config.ts
|
|
177
|
+
5. Using `@prisma/adapter-pg` with `adapter` property
|
|
178
|
+
6. No `url` in datasource block
|
|
179
|
+
7. No `engine` property in config
|
|
180
|
+
8. DATABASE_URL uses `postgres://` (not `prisma+postgres://`)
|
|
181
|
+
9. All DB operations wrapped in try-catch
|