@create-lft-app/nextjs 3.1.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@create-lft-app/nextjs",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Next.js template para proyectos LFT con Midday Design System",
   "type": "module",
   "bin": {

package/template/.claude/skills/anti-patterns.md

@@ -0,0 +1,150 @@
+# Anti-Patterns & Correct Patterns
+
+## NEVER: Import queries or mutations directly in components
+
+```typescript
+// WRONG
+import { useEntityMutations } from '@/modules/[entity]/hooks/useEntityMutations'
+import { useEntityQueries } from '@/modules/[entity]/hooks/useEntityQueries'
+
+export function MyComponent() {
+  const { createEntity } = useEntityMutations()
+  const { entities } = useEntityQueries()
+}
+```
+
+```typescript
+// CORRECT — Always use the unified hook
+import { useEntity } from '@/modules/[entity]/hooks/useEntity'
+
+export function MyComponent() {
+  const { createEntity, entities } = useEntity()
+}
+```
+
+## NEVER: Consume the entire Zustand store
+
+```typescript
+// WRONG — Causes unnecessary re-renders
+const store = useEntityStore()
+```
+
+```typescript
+// CORRECT — Use separate selectors with useShallow
+import { useShallow } from 'zustand/react/shallow'
+
+const state = useEntityStore(useShallow((s) => s.state))
+const actions = useEntityStore(useShallow((s) => s.actions))
+```
+
+## NEVER: Manual data fetching in useEffect
+
+```typescript
+// WRONG
+useEffect(() => {
+  fetch('/api/entities').then(setData)
+}, [])
+```
+
+```typescript
+// CORRECT — Use TanStack Query
+const { data } = useQuery({
+  queryKey: ['entities'],
+  queryFn: fetchEntities,
+})
+```
+
+## NEVER: Server actions without authenticated user context
+
+```typescript
+// WRONG — Anonymous client, RLS will fail
+export async function deleteEntity(id: string) {
+  const supabase = createClient()
+  await supabase.from('entities').delete().eq('id', id)
+}
+```
+
+```typescript
+// CORRECT — Authenticated client with user verification
+'use server'
+import { createClient } from '@/lib/supabase/server'
+
+export async function deleteEntity(id: string) {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+
+  const { error } = await supabase.from('entities').delete().eq('id', id)
+  if (error) throw error
+}
+```
+
+## NEVER: Use Drizzle db directly in Server Actions
+
+```typescript
+// WRONG — db queries must go through repository
+'use server'
+export async function getProducts() {
+  return await db.select().from(products) // VIOLATION
+}
+```
+
+```typescript
+// CORRECT — Server actions use repository
+'use server'
+import { productRepository } from '../repositories/products.repository'
+
+export async function getProducts() {
+  await requireAuth()
+  return productRepository.findAll()
+}
+```
+
+**RULE**: If you see `db.select()`, `db.insert()`, `db.update()`, or `db.delete()` outside a `.repository.ts` file, it's an architectural violation.
+
+## NEVER: Put server/fetched data in Zustand stores
+
+Zustand stores are for **UI state only** (selections, filters, modal states). Server data belongs in TanStack Query cache.
+
+## NEVER: Use modals/dialogs for CRUD operations
+
+```typescript
+// WRONG — Modal for create/edit
+<Dialog>
+  <DialogTrigger>Create User</DialogTrigger>
+  <DialogContent><UserForm /></DialogContent>
+</Dialog>
+```
+
+```typescript
+// CORRECT — Navigate to full pages
+router.push('/users/new')        // Create
+router.push(`/users/${id}/edit`) // Edit
+router.push(`/users/${id}`)     // View detail
+// Only exception: AlertDialog for delete confirmation
+```
+
+## NEVER: Hardcode locale for dates or numbers
+
+```typescript
+// WRONG
+date.toLocaleDateString('es-ES')
+num.toLocaleString('es-AR')
+```
+
+```typescript
+// CORRECT — Use centralized config (see skill: formatting)
+import { formatDate } from '@/lib/date'
+import { DEFAULT_LOCALE } from '@/lib/date'
+
+formatDate(value)
+num.toLocaleString(DEFAULT_LOCALE)
+```
+
+## NEVER: Use revalidatePath when data is consumed via TanStack Query
+
+Cache invalidation is handled by `invalidateQueries` in the mutations hook. Only use `revalidatePath` if a Server Component also consumes the same data outside TanStack Query.
+
+## NEVER: Skip the implementation order
+
+Always follow the checklist in skill: module-architecture.

package/template/.claude/skills/drizzle-schema.md

@@ -0,0 +1,178 @@
+# Drizzle ORM & Repository Pattern
+
+## File Structure
+
+```
+src/db/
+├── index.ts          # Drizzle client (exports `db`)
+├── schema/
+│   ├── index.ts      # Barrel export of all schemas — ALWAYS export here
+│   └── [entity].ts   # Schema per entity
+├── migrations/       # Auto-generated migrations
+└── seed.ts           # Seed script
+```
+
+## Drizzle Client
+
+```typescript
+// src/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import postgres from 'postgres'
+import * as schema from './schema'
+
+const connectionString = process.env.DATABASE_URL!
+const client = postgres(connectionString, { prepare: false })
+
+export const db = drizzle(client, { schema })
+export type Database = typeof db
+```
+
+## Schema Definition
+
+```typescript
+// src/db/schema/products.ts
+import { pgTable, uuid, varchar, text, timestamp, pgEnum, numeric, integer } from 'drizzle-orm/pg-core'
+
+export const products = pgTable('products', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: varchar('name', { length: 255 }).notNull(),
+  description: text('description'),
+  price: numeric('price', { precision: 10, scale: 2 }).notNull(),
+  stock: integer('stock').default(0).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+})
+
+// Inferred types
+export type Product = typeof products.$inferSelect
+export type NewProduct = typeof products.$inferInsert
+```
+
+**ALWAYS export each schema in `src/db/schema/index.ts`:**
+
+```typescript
+// src/db/schema/index.ts
+export * from './products'
+// Add new entities here
+```
+
+### Naming Conventions
+
+- Table names: **snake_case plural** (`products`, `order_items`)
+- Column names: **snake_case** in DB (`created_at`), **camelCase** in TypeScript (`createdAt`)
+- Enum types: **snake_case** (`user_role`, `order_status`)
+- Always include `id`, `createdAt`, `updatedAt` on every table
+- Use `uuid` for primary keys with `defaultRandom()`
+- Use `timestamp('...', { withTimezone: true })` for dates
+
+## Repository Pattern (MANDATORY for own tables)
+
+Every entity with its own table MUST have a repository. Server actions NEVER use `db` directly.
+
+```typescript
+// modules/[entity]/repositories/[entity].repository.ts
+import { db } from '@/db'
+import { products, type Product, type NewProduct } from '@/db/schema'
+import { eq } from 'drizzle-orm'
+
+export interface ProductRepository {
+  findAll(): Promise<Product[]>
+  findById(id: string): Promise<Product | null>
+  create(data: NewProduct): Promise<Product>
+  update(id: string, data: Partial<NewProduct>): Promise<Product>
+  delete(id: string): Promise<void>
+}
+
+export const productRepository: ProductRepository = {
+  async findAll() {
+    return await db.select().from(products)
+  },
+
+  async findById(id: string) {
+    const [product] = await db
+      .select()
+      .from(products)
+      .where(eq(products.id, id))
+    return product ?? null
+  },
+
+  async create(data: NewProduct) {
+    const [product] = await db.insert(products).values(data).returning()
+    return product
+  },
+
+  async update(id: string, data: Partial<NewProduct>) {
+    const [product] = await db
+      .update(products)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(products.id, id))
+      .returning()
+    return product
+  },
+
+  async delete(id: string) {
+    await db.delete(products).where(eq(products.id, id))
+  },
+}
+```
+
+## Drizzle Commands
+
+| Command | When to use |
+|---------|-------------|
+| `pnpm db:generate` | After modifying schemas to generate migrations |
+| `pnpm db:migrate` | To apply pending migrations |
+| `pnpm db:push` | Dev only — sync schema directly without migration |
+| `pnpm db:studio` | To inspect data visually |
+| `pnpm db:seed` | To populate database with seed data |
+
+## Schema Change Workflow
+
+1. Modify or create schema in `src/db/schema/[entity].ts`
+2. Export in `src/db/schema/index.ts`
+3. Run: `pnpm db:generate`
+4. Review generated migration in `src/db/migrations/`
+5. Run: `pnpm db:migrate`
+
+## Seed Pattern
+
+```typescript
+// src/db/seed.ts
+import { db } from './index'
+import { products } from './schema'
+
+async function seed() {
+  console.log('Seeding database...')
+  await db.delete(products)
+  await db.insert(products).values([
+    { name: 'Product A', price: '10.00' },
+    { name: 'Product B', price: '20.00' },
+  ])
+  console.log('Database seeded!')
+}
+
+seed().catch(console.error).finally(() => process.exit())
+```
+
+## Drizzle vs Supabase Admin
+
+| Entity | Must use | Reason |
+|--------|----------|--------|
+| `auth.users` | Supabase Admin API | Auth users (see skill: supabase-server-actions) |
+| Own tables (`products`, `orders`, etc.) | Drizzle ORM + Repository | RLS + typed queries |
+
+## Drizzle Config
+
+```typescript
+// drizzle.config.ts
+import { defineConfig } from 'drizzle-kit'
+
+export default defineConfig({
+  schema: './src/db/schema/index.ts',
+  out: './src/db/migrations',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: process.env.DATABASE_URL!,
+  },
+})
+```

package/template/.claude/skills/formatting.md

@@ -0,0 +1,56 @@
+# Date & Number Formatting
+
+## Rule: ALWAYS use `@/lib/date` for dates, NEVER native Date methods
+
+```typescript
+// WRONG
+const date = new Date(value)
+return date.toLocaleDateString('es-ES')
+
+// CORRECT
+import { formatDate } from '@/lib/date'
+return formatDate(value)
+```
+
+## Available Functions (`@/lib/date`)
+
+| Function | Output example | Use case |
+|----------|---------------|----------|
+| `formatDate(date)` | `"15/01/2024"` | Standard date |
+| `formatDateShort(date)` | `"15 ene"` | Filters, chips |
+| `formatDateLong(date)` | `"15 de enero de 2024"` | Headers, titles |
+| `formatTime(date)` | `"14:30"` | Time only |
+| `formatDateTime(date)` | `"15/01/2024 14:30"` | Date and time |
+| `formatRelative(date)` | `"hace 2 horas"` | Relative time |
+
+## Number Formatting
+
+ALWAYS use `DEFAULT_LOCALE` from `@/lib/date` for numbers:
+
+```typescript
+// WRONG — hardcoded locale
+num.toLocaleString('es-AR')
+
+// CORRECT — centralized config
+import { DEFAULT_LOCALE, DEFAULT_CURRENCY } from '@/lib/date'
+num.toLocaleString(DEFAULT_LOCALE)
+
+// Currency
+new Intl.NumberFormat(DEFAULT_LOCALE, {
+  style: 'currency',
+  currency: DEFAULT_CURRENCY,
+}).format(amount)
+```
+
+## Configuration
+
+All i18n config is centralized in `lib/date/config.ts`:
+
+```typescript
+// lib/date/config.ts
+export const DEFAULT_LOCALE = 'es-AR'
+export const DEFAULT_TIMEZONE = 'America/Argentina/Buenos_Aires'
+export const DEFAULT_CURRENCY = 'ARS'
+```
+
+Changing these values affects the entire project (dates and numbers).

package/template/.claude/skills/module-architecture.md

@@ -0,0 +1,143 @@
+# Module Architecture Pattern
+
+## Mandatory Flow
+
+```
+Repository → Server Actions → Queries → Mutations → Unified Hook → Component
+```
+
+Every feature module MUST follow this exact structure. No exceptions.
+
+## Module Folder Structure
+
+```
+modules/
+└── [entity]/
+    ├── repositories/
+    │   └── [entity].repository.ts     # Data access with Drizzle (required for own tables)
+    ├── actions/
+    │   └── [entity]-actions.ts        # Server actions (uses repository, NEVER db direct)
+    ├── components/
+    │   ├── [entity]-list.tsx           # Component imports ONLY unified hook
+    │   ├── [entity]-form.tsx
+    │   └── [entity]-detail.tsx
+    ├── hooks/
+    │   ├── use[Entity]Queries.ts       # TanStack Query (read operations)
+    │   ├── use[Entity]Mutations.ts     # TanStack Mutations (write operations)
+    │   └── use[Entity].ts              # UNIFIED HOOK (components use THIS)
+    ├── stores/
+    │   └── use[Entity]Store.ts         # Zustand store (UI state only)
+    ├── schemas/
+    │   └── [entity].schema.ts          # Zod validation schemas
+    ├── utils/
+    │   └── [entity]-mapper.ts          # Mappers if needed (e.g., auth.users → User)
+    ├── columns.tsx                     # TanStack Table column definitions (if needed)
+    └── index.ts                        # Barrel export
+```
+
+## Layer Architecture
+
+```
+UI/Presentation Layer
+    ↓ (components use unified hook)
+Service/Business Layer (hooks: use[Entity].ts)
+    ↓ (calls server actions)
+Action Layer (actions: [entity]-actions.ts)
+    ↓ (calls repository)
+Data Access Layer (repositories: [entity].repository.ts)
+    ↓ (uses Drizzle)
+Data Source (Supabase/PostgreSQL)
+```
+
+## Implementation Checklist
+
+When creating or modifying a module, follow these steps in order:
+
+1. **Drizzle schema** — `db/schema/[entity].ts` + export in `db/schema/index.ts` (see skill: drizzle-schema)
+2. **Repository** — `modules/[entity]/repositories/[entity].repository.ts` (required for own tables, see skill: drizzle-schema)
+3. **Zod schemas** — `modules/[entity]/schemas/[entity].schema.ts`
+4. **Server actions** — `modules/[entity]/actions/[entity]-actions.ts` (uses repository, NEVER db direct; see skill: supabase-server-actions)
+5. **Zustand store** — `modules/[entity]/stores/use[Entity]Store.ts` (UI state only, consumed with `useShallow`)
+6. **Queries hook** — `modules/[entity]/hooks/use[Entity]Queries.ts` (TanStack Query, read operations)
+7. **Mutations hook** — `modules/[entity]/hooks/use[Entity]Mutations.ts` (TanStack Mutations with cache invalidation)
+8. **Unified hook** — `modules/[entity]/hooks/use[Entity].ts` (combines store + queries + mutations)
+9. **Components** — Import ONLY the unified hook, never queries/mutations directly
+10. **Pages** — Create routes: `/[entity]`, `/[entity]/new`, `/[entity]/[id]`, `/[entity]/[id]/edit` (see skill: ui-patterns)
+11. **Verify** — Run `pnpm typecheck && pnpm lint`
+
+**Note:** For modules using `auth.users` (like the users module), skip steps 1-2 and use Supabase Admin API instead (see skill: supabase-server-actions).
+
+## Unified Hook Pattern
+
+The unified hook is the single entry point for components. It combines store state, queries, and mutations:
+
+```typescript
+// modules/[entity]/hooks/use[Entity].ts
+import { useShallow } from 'zustand/react/shallow'
+import { use[Entity]Store } from '../stores/use[Entity]Store'
+import { use[Entity]Queries } from './use[Entity]Queries'
+import { use[Entity]Mutations } from './use[Entity]Mutations'
+
+export function use[Entity]() {
+  const state = use[Entity]Store(useShallow((s) => s.state))
+  const actions = use[Entity]Store(useShallow((s) => s.actions))
+  const queries = use[Entity]Queries()
+  const mutations = use[Entity]Mutations()
+
+  return {
+    // Store
+    ...state,
+    ...actions,
+    // Queries
+    ...queries,
+    // Mutations
+    ...mutations,
+  }
+}
+// IMPORTANT: Avoid naming collisions across store/queries/mutations.
+// Use prefixed names (e.g., `isCreating`, `isDeleting` instead of generic `isPending`).
+```
+
+## Component Usage
+
+```typescript
+// modules/[entity]/components/[entity]-list.tsx
+import { use[Entity] } from '../hooks/use[Entity]'
+
+export function EntityList() {
+  const { entities, isLoading, createEntity, selectedId, setSelectedId } = use[Entity]()
+
+  // All state, queries, and mutations available from a single hook
+}
+```
+
+## Zustand Store Pattern
+
+Stores hold **UI state only** (selections, filters, modals). Never put server data in stores.
+
+```typescript
+// modules/[entity]/stores/use[Entity]Store.ts
+import { create } from 'zustand'
+
+interface EntityState {
+  state: {
+    selectedId: string | null
+    isFormOpen: boolean
+  }
+  actions: {
+    setSelectedId: (id: string | null) => void
+    setFormOpen: (open: boolean) => void
+  }
+}
+
+export const use[Entity]Store = create<EntityState>((set) => ({
+  state: {
+    selectedId: null,
+    isFormOpen: false,
+  },
+  actions: {
+    setSelectedId: (id) => set((s) => ({ state: { ...s.state, selectedId: id } })),
+    setFormOpen: (open) => set((s) => ({ state: { ...s.state, isFormOpen: open } })),
+  },
+}))
+```