start-vibing-stacks 2.3.0 → 2.4.0

package/stacks/frontend/react/skills/react-ui-patterns/SKILL.md

@@ -138,7 +138,7 @@ function UserList({ users }: { users: User[] }) {
         icon={<Users className="h-8 w-8" />}
         title="No users yet"
         description="Invite your first team member"
-        action={{ label: 'Invite User', onClick: () => router.visit('/users/invite') }}
+        action={{ label: 'Invite User', onClick: () => window.location.assign('/users/invite') }}
       />
     );
   }
@@ -191,57 +191,76 @@ function EmptyState({ icon, title, description, action }: {
 </button>
 ```
 
-## Form Pattern (Inertia.js)
+## Form Pattern (React Hook Form + Zod)
 
 ```tsx
-import { useForm } from '@inertiajs/react';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation } from '@tanstack/react-query';
+import { z } from 'zod';
+import { toast } from 'sonner';
+
+const CreateUserSchema = z.object({
+  name: z.string().min(2, 'Name is required'),
+  email: z.string().email('Invalid email'),
+});
+
+type CreateUserForm = z.infer<typeof CreateUserSchema>;
 
 export default function CreateUser() {
-  const { data, setData, post, processing, errors, reset } = useForm({
-    name: '',
-    email: '',
+  const {
+    register,
+    handleSubmit,
+    reset,
+    formState: { errors },
+  } = useForm<CreateUserForm>({
+    resolver: zodResolver(CreateUserSchema),
   });
 
-  const submit = (e: React.FormEvent) => {
-    e.preventDefault();
-    post('/users', {
-      onSuccess: () => {
-        toast.success('User created!');
-        reset();
-      },
-      onError: () => toast.error('Failed to create user'),
-    });
-  };
+  const mutation = useMutation({
+    mutationFn: (data: CreateUserForm) =>
+      fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data),
+      }).then((res) => {
+        if (!res.ok) throw new Error('Failed to create user');
+        return res.json();
+      }),
+    onSuccess: () => {
+      toast.success('User created!');
+      reset();
+    },
+    onError: () => toast.error('Failed to create user'),
+  });
 
   return (
-    <form onSubmit={submit} className="space-y-4">
+    <form onSubmit={handleSubmit((data) => mutation.mutate(data))} className="space-y-4">
       <div>
         <label className="block text-sm font-medium text-foreground mb-1">Name</label>
         <input
-          value={data.name}
-          onChange={e => setData('name', e.target.value)}
+          {...register('name')}
           className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
         />
-        {errors.name && <p className="mt-1 text-sm text-destructive">{errors.name}</p>}
+        {errors.name && <p className="mt-1 text-sm text-destructive">{errors.name.message}</p>}
       </div>
 
       <div>
         <label className="block text-sm font-medium text-foreground mb-1">Email</label>
         <input
           type="email"
-          value={data.email}
-          onChange={e => setData('email', e.target.value)}
+          {...register('email')}
           className="w-full h-10 px-3 rounded-md border border-border bg-background text-foreground"
         />
-        {errors.email && <p className="mt-1 text-sm text-destructive">{errors.email}</p>}
+        {errors.email && <p className="mt-1 text-sm text-destructive">{errors.email.message}</p>}
       </div>
 
       <button
         type="submit"
-        disabled={processing}
+        disabled={mutation.isPending}
         className="bg-primary text-primary-foreground px-6 py-2 rounded-lg hover:bg-primary-hover disabled:opacity-50 transition-colors"
       >
-        {processing ? (
+        {mutation.isPending ? (
           <span className="flex items-center gap-2">
             <Loader className="h-4 w-4 animate-spin" /> Creating...
           </span>
@@ -252,27 +271,44 @@ export default function CreateUser() {
 }
 ```
 
-## Optimistic Updates
+## Optimistic Updates (TanStack Query)
 
 ```tsx
-// Show result immediately, rollback on error
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+
 function ToggleFavorite({ item }: { item: Item }) {
-  const [optimistic, setOptimistic] = useState(item.isFavorite);
-
-  const toggle = () => {
-    setOptimistic(!optimistic);  // Instant UI
-    router.post(`/items/${item.id}/favorite`, {}, {
-      preserveState: true,
-      onError: () => {
-        setOptimistic(item.isFavorite);  // Rollback
-        toast.error('Failed to update');
-      },
-    });
-  };
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: () =>
+      fetch(`/api/items/${item.id}/favorite`, { method: 'POST' }).then((res) => {
+        if (!res.ok) throw new Error('Failed');
+        return res.json();
+      }),
+    onMutate: async () => {
+      await queryClient.cancelQueries({ queryKey: ['items'] });
+      const previous = queryClient.getQueryData<Item[]>(['items']);
+
+      queryClient.setQueryData<Item[]>(['items'], (old) =>
+        old?.map((i) =>
+          i.id === item.id ? { ...i, isFavorite: !i.isFavorite } : i
+        )
+      );
+
+      return { previous };
+    },
+    onError: (_err, _vars, context) => {
+      queryClient.setQueryData(['items'], context?.previous);
+      toast.error('Failed to update');
+    },
+    onSettled: () => {
+      queryClient.invalidateQueries({ queryKey: ['items'] });
+    },
+  });
 
   return (
-    <button onClick={toggle} className="text-xl">
-      {optimistic ? '❤️' : '🤍'}
+    <button onClick={() => mutation.mutate()} className="text-xl">
+      {item.isFavorite ? '❤️' : '🤍'}
     </button>
   );
 }
@@ -294,5 +330,5 @@ function ToggleFavorite({ item }: { item: Item }) {
 1. **`if (loading) return <Spinner />`** — check `loading && !data` instead
 2. **Silent catch** — always toast/display errors to user
 3. **No empty state** — every list needs one
-4. **Clickable button during submit** — always `disabled={processing}`
+4. **Clickable button during submit** — always `disabled={isPending}` or `disabled={isSubmitting}`
 5. **Console.log-only errors** — user must see feedback

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -15,7 +15,7 @@
 ## Setup (v4)
 
 ```css
-/* resources/css/app.css (Laravel + Inertia) */
+/* src/app/globals.css */
 @import "tailwindcss";
 
 @theme {

package/stacks/frontend/react/skills/zod-validation/SKILL.md

@@ -113,18 +113,38 @@ if (result.success) {
 
 ### Environment Variables
 
+> **Split server and client env schemas.** `NEXT_PUBLIC_*` is embedded in the browser bundle — NEVER put secrets there.
+
 ```tsx
-const EnvSchema = z.object({
-  NEXT_PUBLIC_API_URL: z.string().url(),
-  NEXT_PUBLIC_STRIPE_KEY: z.string().startsWith('pk_'),
+// lib/env.server.ts — Server-only secrets (NEVER import from client components)
+const ServerEnvSchema = z.object({
   DATABASE_URL: z.string().min(1),
+  OPENAI_KEY: z.string().startsWith('sk-'),
+  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
   NODE_ENV: z.enum(['development', 'production', 'test']),
 });
 
-// Validate at app startup
-export const env = EnvSchema.parse(process.env);
+export const serverEnv = ServerEnvSchema.parse({
+  DATABASE_URL: process.env['DATABASE_URL'],
+  OPENAI_KEY: process.env['OPENAI_KEY'],
+  STRIPE_SECRET_KEY: process.env['STRIPE_SECRET_KEY'],
+  NODE_ENV: process.env['NODE_ENV'],
+});
+
+// lib/env.client.ts — Public vars only (safe for browser)
+const ClientEnvSchema = z.object({
+  NEXT_PUBLIC_APP_URL: z.string().url(),
+  NEXT_PUBLIC_STRIPE_KEY: z.string().startsWith('pk_'),
+});
+
+export const clientEnv = ClientEnvSchema.parse({
+  NEXT_PUBLIC_APP_URL: process.env['NEXT_PUBLIC_APP_URL'],
+  NEXT_PUBLIC_STRIPE_KEY: process.env['NEXT_PUBLIC_STRIPE_KEY'],
+});
 ```
 
+**Rule:** If a variable contains a key, secret, token, or password, it MUST be in `ServerEnvSchema` without `NEXT_PUBLIC_` prefix.
+
 ### Reusable Schemas
 
 ```tsx
@@ -160,26 +180,72 @@ const ContactSchema = z.object({
 });
 ```
 
-## Integration with Laravel (Inertia.js)
+## Integration with Next.js Server Actions
 
 ```tsx
-// Frontend validates BEFORE sending to Laravel
-const StoreLeadSchema = z.object({
+'use server';
+
+import { z } from 'zod';
+
+const CreateLeadSchema = z.object({
   name: z.string().min(2),
-  email: EmailSchema,
-  domain_id: UUIDSchema,
+  email: z.string().email().toLowerCase().trim(),
+  domainId: z.string().uuid(),
 });
 
-// In component
-const handleSubmit = (formData: unknown) => {
-  const result = StoreLeadSchema.safeParse(formData);
+export async function createLead(formData: FormData) {
+  const result = CreateLeadSchema.safeParse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+    domainId: formData.get('domainId'),
+  });
+
   if (!result.success) {
-    setErrors(result.error.flatten().fieldErrors);
-    return;
+    return { errors: result.error.flatten().fieldErrors };
   }
-  // Send validated data to Laravel
-  router.post('/leads', result.data);
-};
+
+  await db.lead.create({ data: result.data });
+  return { success: true };
+}
+```
+
+### Client-Side with React Hook Form
+
+```tsx
+'use client';
+
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+
+const CreateLeadSchema = z.object({
+  name: z.string().min(2),
+  email: z.string().email(),
+  domainId: z.string().uuid(),
+});
+
+type CreateLeadForm = z.infer<typeof CreateLeadSchema>;
+
+export function LeadForm() {
+  const { register, handleSubmit, formState: { errors } } = useForm<CreateLeadForm>({
+    resolver: zodResolver(CreateLeadSchema),
+  });
+
+  const onSubmit = async (data: CreateLeadForm) => {
+    await fetch('/api/leads', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(data),
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <input {...register('name')} />
+      {errors.name && <span>{errors.name.message}</span>}
+      {/* ... */}
+    </form>
+  );
+}
 ```
 
 ## FORBIDDEN

package/stacks/nodejs/skills/nextjs-app-router/SKILL.md

@@ -114,6 +114,104 @@ export async function generateMetadata({ params }: { params: { id: string } }) {
 }
 ```
 
+## Environment Variables & API Security (MANDATORY)
+
+> **NEXT_PUBLIC_ vars are embedded in the browser JS bundle.** Anyone can see them in DevTools.
+
+### Server vs Client Environment
+
+| Prefix | Accessible from | Safe for |
+|--------|----------------|----------|
+| No prefix | Server Components, Route Handlers, Server Actions | API keys, secrets, tokens, DB URLs |
+| `NEXT_PUBLIC_*` | Server + Browser (embedded in JS) | Public URLs, analytics IDs, publishable keys |
+
+### FORBIDDEN Environment Patterns
+
+```bash
+# NEVER DO THIS — secret exposed in browser bundle
+NEXT_PUBLIC_OPENAI_KEY=sk-abc123
+NEXT_PUBLIC_STRIPE_SECRET_KEY=sk_live_abc
+NEXT_PUBLIC_DATABASE_URL=postgresql://user:pass@host/db
+
+# CORRECT — server-only (no NEXT_PUBLIC_ prefix)
+OPENAI_KEY=sk-abc123
+STRIPE_SECRET_KEY=sk_live_abc
+DATABASE_URL=postgresql://user:pass@host/db
+
+# OK as NEXT_PUBLIC_ — no secret value
+NEXT_PUBLIC_APP_URL=https://myapp.com
+NEXT_PUBLIC_STRIPE_KEY=pk_live_abc
+NEXT_PUBLIC_GA_ID=G-XXXXX
+```
+
+### API Proxy Pattern (MANDATORY)
+
+External API calls with secrets MUST go through server-side Route Handlers:
+
+```tsx
+// app/api/ai/route.ts — Secret stays on server
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { prompt } = await req.json();
+
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${process.env['OPENAI_KEY']}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: prompt }],
+    }),
+  });
+
+  if (!response.ok) {
+    return NextResponse.json({ error: 'AI request failed' }, { status: 502 });
+  }
+
+  return NextResponse.json(await response.json());
+}
+```
+
+```tsx
+// components/chat.tsx — Client calls YOUR route, not external API
+'use client';
+
+async function sendMessage(prompt: string) {
+  const res = await fetch('/api/ai', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ prompt }),
+  });
+  return res.json();
+}
+```
+
+### Server Actions for Mutations
+
+Server Actions also keep secrets server-side:
+
+```tsx
+// app/actions/payment.ts
+'use server';
+
+import Stripe from 'stripe';
+
+const stripe = new Stripe(process.env['STRIPE_SECRET_KEY']!);
+
+export async function createCheckout(priceId: string) {
+  const session = await stripe.checkout.sessions.create({
+    mode: 'payment',
+    line_items: [{ price: priceId, quantity: 1 }],
+    success_url: `${process.env['APP_URL']}/success`,
+    cancel_url: `${process.env['APP_URL']}/cancel`,
+  });
+  return { url: session.url };
+}
+```
+
 ## FORBIDDEN
 
 1. **`'use client'` on server-capable components** — default to server
@@ -121,3 +219,6 @@ export async function generateMetadata({ params }: { params: { id: string } }) {
 3. **`getServerSideProps` / `getStaticProps`** — App Router uses async components
 4. **API routes for server-only data** — use server components directly
 5. **Prop drilling through layouts** — use parallel routes or context
+6. **`NEXT_PUBLIC_` with API keys, secrets, or tokens** — secrets leak to browser bundle
+7. **Calling external APIs from client components** — use Route Handlers as proxy
+8. **`process.env['SECRET']` in `'use client'` files** — only `NEXT_PUBLIC_*` vars work client-side

package/stacks/nodejs/stack.json

@@ -1,29 +1,13 @@
 {
   "id": "nodejs",
   "name": "Node.js / TypeScript",
-  "icon": "\ud83d\udce6",
+  "icon": "📦",
   "runtime": "Bun / Node.js 20+",
   "minVersion": "20.0.0",
   "packageManager": "bun|npm|pnpm",
-  "extensions": [
-    ".ts",
-    ".tsx",
-    ".js",
-    ".jsx",
-    ".mjs",
-    ".cjs"
-  ],
-  "testExtensions": [
-    "*.test.ts",
-    "*.spec.ts",
-    "*.test.tsx"
-  ],
-  "detectFiles": [
-    "package.json",
-    "tsconfig.json",
-    "bun.lockb",
-    "next.config.js"
-  ],
+  "extensions": [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"],
+  "testExtensions": ["*.test.ts", "*.spec.ts", "*.test.tsx"],
+  "detectFiles": ["package.json", "tsconfig.json", "bun.lockb", "bun.lock", "next.config.js"],
   "commands": {
     "test": "bun run test",
     "lint": "bun run lint",
@@ -33,146 +17,95 @@
     "typecheck": "bun run typecheck"
   },
   "qualityGates": [
-    {
-      "name": "TypeCheck",
-      "command": "bun run typecheck",
-      "required": true,
-      "order": 1
-    },
-    {
-      "name": "Lint",
-      "command": "bun run lint",
-      "required": true,
-      "order": 2
-    },
-    {
-      "name": "Tests",
-      "command": "bun run test",
-      "required": true,
-      "order": 3
-    },
-    {
-      "name": "Build",
-      "command": "bun run build",
-      "required": true,
-      "order": 4
-    }
+    { "name": "TypeCheck", "command": "bun run typecheck", "required": true, "order": 1 },
+    { "name": "Lint", "command": "bun run lint", "required": true, "order": 2 },
+    { "name": "Tests", "command": "bun run test", "required": true, "order": 3 },
+    { "name": "Build", "command": "bun run build", "required": true, "order": 4 }
   ],
   "frameworks": [
     {
       "id": "nextjs",
       "name": "Next.js (App Router)",
-      "icon": "\u25b2",
-      "detectFiles": [
-        "next.config.js",
-        "next.config.ts",
-        "next.config.mjs"
-      ]
+      "icon": "▲",
+      "detectFiles": ["next.config.js", "next.config.ts", "next.config.mjs"],
+      "default": true,
+      "skills": ["nextjs-app-router"]
     },
     {
       "id": "nuxt",
       "name": "Nuxt",
-      "icon": "\ud83d\udc9a",
-      "detectFiles": [
-        "nuxt.config.ts"
-      ]
+      "icon": "💚",
+      "detectFiles": ["nuxt.config.ts"],
+      "skills": []
     },
     {
       "id": "astro",
       "name": "Astro",
-      "icon": "\ud83d\ude80",
-      "detectFiles": [
-        "astro.config.mjs"
-      ]
+      "icon": "🚀",
+      "detectFiles": ["astro.config.mjs"],
+      "skills": []
     },
     {
       "id": "express",
       "name": "Express",
-      "icon": "\u26a1"
+      "icon": "⚡",
+      "skills": ["trpc-api"]
     },
     {
       "id": "fastify",
       "name": "Fastify",
-      "icon": "\ud83c\udfce\ufe0f"
+      "icon": "🏎️",
+      "skills": ["trpc-api"]
     },
     {
       "id": "vanilla",
       "name": "Vanilla Node.js",
-      "icon": "\ud83d\udcc4"
+      "icon": "📄",
+      "skills": []
     }
   ],
   "databases": [
-    {
-      "id": "mongodb",
-      "name": "MongoDB",
-      "icon": "\ud83c\udf43"
-    },
-    {
-      "id": "postgresql",
-      "name": "PostgreSQL",
-      "icon": "\ud83d\udc18"
-    },
-    {
-      "id": "mysql",
-      "name": "MySQL / MariaDB",
-      "icon": "\ud83d\udc2c"
-    },
-    {
-      "id": "sqlite",
-      "name": "SQLite (Turso / libSQL)",
-      "icon": "\ud83d\udcc1"
-    },
-    {
-      "id": "redis",
-      "name": "Redis (Upstash)",
-      "icon": "\ud83d\udd34"
-    },
-    {
-      "id": "none",
-      "name": "None",
-      "icon": "\u274c"
-    }
+    { "id": "mongodb", "name": "MongoDB", "icon": "🍃" },
+    { "id": "postgresql", "name": "PostgreSQL", "icon": "🐘" },
+    { "id": "mysql", "name": "MySQL / MariaDB", "icon": "🐬" },
+    { "id": "sqlite", "name": "SQLite (Turso / libSQL)", "icon": "📁" },
+    { "id": "redis", "name": "Redis (Upstash)", "icon": "🔴" },
+    { "id": "none", "name": "None", "icon": "❌" }
   ],
   "frontendOptions": [
     {
       "id": "react-tailwind",
       "name": "React 19+ / TailwindCSS 4+",
-      "icon": "\u269b\ufe0f"
+      "icon": "⚛️",
+      "skillsDir": "react",
+      "default": true,
+      "frameworks": ["nextjs", "express", "fastify", "vanilla"]
     },
     {
       "id": "vue",
       "name": "Vue.js / Nuxt",
-      "icon": "\ud83d\udc9a"
+      "icon": "💚",
+      "frameworks": ["nuxt"]
     },
     {
       "id": "svelte",
       "name": "Svelte / SvelteKit",
-      "icon": "\ud83d\udd25"
-    },
-    {
-      "id": "shadcn",
-      "name": "shadcn/ui + Tailwind",
-      "icon": "\ud83c\udfa8"
+      "icon": "🔥",
+      "frameworks": ["astro", "vanilla"]
     },
     {
       "id": "none",
-      "name": "API only \u2014 no frontend",
-      "icon": "\u274c"
+      "name": "API only — no frontend",
+      "icon": "❌"
     }
   ],
   "deployTargets": [
-    {
-      "id": "github",
-      "name": "GitHub (git push)",
-      "icon": "\ud83d\udc19"
-    }
+    { "id": "github", "name": "GitHub (git push)", "icon": "🐙" }
   ],
   "skills": [
     "typescript-strict",
-    "react-patterns",
-    "nextjs-app-router",
-    "zod-validation",
-    "vitest-testing"
+    "bun-runtime",
+    "zod-validation"
   ],
   "requirements": [
     {
@@ -185,17 +118,6 @@
         "linux": "curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - && sudo apt install -y nodejs"
       },
       "versionRegex": "v?(\\d+\\.\\d+\\.\\d+)"
-    },
-    {
-      "name": "Bun",
-      "command": "bun",
-      "versionFlag": "--version",
-      "minVersion": "1.0.0",
-      "installCommand": {
-        "macos": "brew install oven-sh/bun/bun",
-        "linux": "curl -fsSL https://bun.sh/install | bash"
-      },
-      "versionRegex": "(\\d+\\.\\d+\\.\\d+)"
     }
   ]
 }