start-vibing-stacks 2.3.0 → 2.4.1

package/stacks/frontend/react/skills/react-standards/SKILL.md

@@ -5,16 +5,16 @@
 - **ReactJS >= 19** — MANDATORY
 - **TailwindCSS >= 4** — MANDATORY
 
-## Translation Pattern
+## Label Constants Pattern
 
 ```tsx
-// ✅ Translations as CONST at the top, BEFORE hooks
+// ✅ Labels as CONST at the top, BEFORE hooks
 const LABELS = {
-    title: __('dashboard.title'),
-    save: __('common.save'),
-    cancel: __('common.cancel'),
-    errorRequired: __('errors.field_required'),
-};
+    title: 'Dashboard',
+    save: 'Save',
+    cancel: 'Cancel',
+    errorRequired: 'This field is required',
+} as const;
 
 export default function Dashboard() {
     const [data, setData] = useState(null);
@@ -22,14 +22,14 @@ export default function Dashboard() {
     return <h1>{LABELS.title}</h1>;
 }
 
-// ❌ NEVER call __() inside JSX (Hook violations)
-return <h1>{__('dashboard.title')}</h1>; // ❌
+// ❌ NEVER scatter string literals across JSX
+return <h1>Dashboard</h1>; // ❌ Duplicated, hard to maintain
 ```
 
 **Rules:**
-- Translations in `CONST` variables before state hooks
-- New strings → add to `lang/en/*.php` and `lang/pt/*.php`
-- Error strings centralized in `lang/*/errors.php`
+- Labels in `CONST` objects before state hooks for stable references
+- For i18n projects, use `next-intl` or `i18next` — same CONST pattern applies with `t()` calls
+- Error strings centralized in a shared constants file
 
 ## Debug Logging
 
@@ -65,11 +65,11 @@ export default function Dashboard() {
 
 ```tsx
 // ═══════════════════════════════════════════
-// 1. TRANSLATIONS (before hooks)
+// 1. LABELS (before hooks)
 // ═══════════════════════════════════════════
 const LABELS = {
-    title: __('dashboard.title'),
-    save: __('common.save'),
+    title: 'Dashboard',
+    save: 'Save',
 } as const;
 
 // ═══════════════════════════════════════════
@@ -156,7 +156,7 @@ import { cn } from '@/lib/utils';
 5. **Shared styles** — create a `styles.ts` file for cross-component constants
 
 ```tsx
-// resources/js/styles.ts — shared across components
+// src/styles.ts — shared across components
 export const SHARED_STYLES = {
     page: 'max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8',
     btnPrimary: 'px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary-hover ...',
@@ -187,10 +187,10 @@ export default function Bad() {
 ## SVG Icons
 
 ```tsx
-// ✅ Separate files, import with ?react
-// resources/js/Icons/CheckIcon.svg
-import CheckIcon from '@/Icons/CheckIcon.svg?react';
-import { CheckIcon, AlertIcon } from '@/Icons';
+// ✅ Separate files, import with ?react (Vite) or as components
+// src/components/icons/CheckIcon.svg
+import CheckIcon from '@/components/icons/CheckIcon.svg?react';
+import { CheckIcon, AlertIcon } from '@/components/icons';
 
 // ❌ Inline SVG
 <svg viewBox="0 0 24 24">...</svg> // ❌ Bloats JSX

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