Next.js template para proyectos LFT con Midday Design System
npm install @create-lft-app/nextjsbash
npx @create-lft-app/nextjs mi-proyecto
`
Stack Tecnológico
| Categoría | Librería | Versión |
|-----------|----------|---------|
| Framework | Next.js | ^16 |
| Lenguaje | TypeScript | ^5 |
| Estado Global | Zustand | ^5 |
| Data Fetching | TanStack Query | ^5 |
| Tablas | TanStack Table | ^8 |
| UI Components | Radix UI | latest |
| Animaciones | Framer Motion | ^11 |
| Auth & Backend | Supabase SSR | ^0.5 |
| ORM | Drizzle | latest |
| Validación | Zod | ^3 |
| Excel | xlsx (SheetJS) | latest |
| Fechas | dayjs | ^1 |
| Forms | React Hook Form | ^7 |
| Package Manager | pnpm | latest |
Estructura de Carpetas
`
template/
├── proxy.ts # Next.js 16 middleware (protección de rutas)
├── drizzle.config.ts # Configuración Drizzle ORM
│
├── src/
│ ├── app/
│ │ ├── layout.tsx # Layout raíz
│ │ ├── page.tsx # Página principal (redirect)
│ │ ├── providers.tsx # TanStack Query + providers
│ │ │
│ │ ├── api/ # API Routes
│ │ │ └── webhooks/
│ │ │ └── route.ts
│ │ │
│ │ ├── (auth)/ # Rutas protegidas (requieren sesión)
│ │ │ ├── layout.tsx
│ │ │ ├── dashboard/
│ │ │ └── users/
│ │ │
│ │ └── (public)/ # Rutas públicas
│ │ ├── layout.tsx
│ │ └── login/
│ │
│ ├── components/
│ │ ├── layout/ # Componentes de layout
│ │ │ ├── sidebar.tsx
│ │ │ ├── sidebar-context.tsx
│ │ │ └── main-content.tsx
│ │ │
│ │ ├── tables/ # TanStack Table genéricos
│ │ │ ├── data-table.tsx
│ │ │ ├── data-table-column-header.tsx
│ │ │ ├── data-table-pagination.tsx
│ │ │ ├── data-table-toolbar.tsx
│ │ │ └── data-table-view-options.tsx
│ │ │
│ │ └── ui/ # Radix + Framer Motion
│ │ ├── animations/
│ │ ├── button.tsx
│ │ ├── card.tsx
│ │ ├── dialog.tsx
│ │ ├── sheet.tsx
│ │ └── ...
│ │
│ ├── config/
│ │ ├── navigation.ts # Configuración de navegación
│ │ └── site.ts # Metadata del sitio
│ │
│ ├── db/ # Drizzle ORM
│ │ ├── index.ts # Cliente de base de datos
│ │ ├── seed.ts # Seeds
│ │ └── schema/ # Schemas de tablas
│ │
│ ├── hooks/ # Hooks globales reutilizables
│ │ ├── useDataTable.ts
│ │ ├── useDebounce.ts
│ │ └── useMediaQuery.ts
│ │
│ ├── lib/
│ │ ├── utils.ts # Utilidades (cn, etc.)
│ │ ├── query-client.ts # TanStack Query config
│ │ │
│ │ ├── date/ # Utilidades dayjs
│ │ │ ├── config.ts
│ │ │ └── formatters.ts
│ │ │
│ │ ├── excel/ # Utilidades xlsx
│ │ │ ├── exporter.ts
│ │ │ └── parser.ts
│ │ │
│ │ ├── supabase/ # Clientes Supabase
│ │ │ ├── client.ts # Browser
│ │ │ ├── server.ts # Server
│ │ │ └── proxy.ts # Session middleware
│ │ │
│ │ └── validations/ # Zod schemas comunes
│ │
│ ├── modules/ # ⭐ MÓDULOS (feature-based)
│ │ ├── auth/
│ │ └── users/
│ │
│ ├── stores/ # Zustand stores globales
│ │ └── useUiStore.ts
│ │
│ └── types/ # TypeScript types globales
│
└── supabase/
├── config.toml
└── functions/ # Edge Functions (Deno)
`
Arquitectura Modular
$3
`
Store (Zustand) → Queries (TanStack) → Mutations → Hook Unificado → Componente
`
Regla fundamental: Los componentes SOLO importan el hook unificado, nunca queries, mutations o stores directamente.
$3
Cada módulo es self-contained y sigue esta estructura:
`
src/modules/[nombre]/
├── index.ts # Barrel exports
├── columns.tsx # Columnas TanStack Table (si aplica)
│
├── actions/
│ └── [nombre]-actions.ts # Server actions
│
├── components/
│ └── [nombre]-list.tsx # Componentes del módulo
│
├── hooks/
│ ├── use[Nombre].ts # ⭐ Hook unificado (ÚNICO import en componentes)
│ ├── use[Nombre]Queries.ts # Queries TanStack
│ └── use[Nombre]Mutations.ts # Mutations TanStack
│
├── schemas/
│ └── [nombre].schema.ts # Zod schemas + tipos
│
└── stores/
└── use[Nombre]Store.ts # Zustand store del módulo
`
Crear un Nuevo Módulo
$3
`bash
mkdir -p src/modules/products/{actions,components,hooks,schemas,stores}
`
$3
`typescript
// src/modules/products/schemas/products.schema.ts
import { z } from 'zod'
export const productSchema = z.object({
id: z.string().uuid(),
name: z.string().min(1, 'Nombre requerido'),
price: z.number().positive(),
stock: z.number().int().min(0),
created_at: z.string(),
})
export const createProductSchema = productSchema.omit({ id: true, created_at: true })
export const updateProductSchema = createProductSchema.partial()
export type Product = z.infer
export type CreateProductInput = z.infer
export type UpdateProductInput = z.infer
`
$3
`typescript
// src/modules/products/actions/products-actions.ts
'use server'
import { createClient } from '@/lib/supabase/server'
import { createProductSchema, type CreateProductInput } from '../schemas/products.schema'
export async function getProducts() {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) throw new Error('Unauthorized')
const { data, error } = await supabase
.from('products')
.select('*')
.order('created_at', { ascending: false })
if (error) throw error
return data
}
export async function createProduct(input: CreateProductInput) {
const parsed = createProductSchema.safeParse(input)
if (!parsed.success) throw new Error(parsed.error.errors[0].message)
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
if (!user) throw new Error('Unauthorized')
const { data, error } = await supabase
.from('products')
.insert(parsed.data)
.select()
.single()
if (error) throw error
return data
}
`
$3
`typescript
// src/modules/products/stores/useProductsStore.ts
import { create } from 'zustand'
import { useShallow } from 'zustand/shallow'
interface ProductsState {
selectedProductId: string | null
isCreateDialogOpen: boolean
filters: { search: string; category: string | null }
}
interface ProductsActions {
setSelectedProductId: (id: string | null) => void
setIsCreateDialogOpen: (open: boolean) => void
setFilters: (filters: Partial) => void
reset: () => void
}
const initialState: ProductsState = {
selectedProductId: null,
isCreateDialogOpen: false,
filters: { search: '', category: null },
}
export const useProductsStore = create((set) => ({
...initialState,
setSelectedProductId: (id) => set({ selectedProductId: id }),
setIsCreateDialogOpen: (open) => set({ isCreateDialogOpen: open }),
setFilters: (filters) => set((state) => ({
filters: { ...state.filters, ...filters }
})),
reset: () => set(initialState),
}))
// Selector optimizado con useShallow
export const useProductsFilters = () =>
useProductsStore(useShallow((state) => state.filters))
`
$3
`typescript
// src/modules/products/hooks/useProductsQueries.ts
'use client'
import { useQuery } from '@tanstack/react-query'
import { getProducts, getProductById } from '../actions/products-actions'
export const productsKeys = {
all: ['products'] as const,
lists: () => [...productsKeys.all, 'list'] as const,
list: (filters: Record) => [...productsKeys.lists(), filters] as const,
details: () => [...productsKeys.all, 'detail'] as const,
detail: (id: string) => [...productsKeys.details(), id] as const,
}
export function useProductsQueries(productId?: string) {
const productsQuery = useQuery({
queryKey: productsKeys.lists(),
queryFn: () => getProducts(),
})
const productQuery = useQuery({
queryKey: productsKeys.detail(productId!),
queryFn: () => getProductById(productId!),
enabled: !!productId,
})
return {
products: productsQuery.data ?? [],
product: productQuery.data,
isLoading: productsQuery.isLoading,
error: productsQuery.error,
}
}
`
$3
`typescript
// src/modules/products/hooks/useProductsMutations.ts
'use client'
import { useMutation, useQueryClient } from '@tanstack/react-query'
import { createProduct, updateProduct, deleteProduct } from '../actions/products-actions'
import { productsKeys } from './useProductsQueries'
import type { CreateProductInput, UpdateProductInput } from '../schemas/products.schema'
export function useProductsMutations() {
const queryClient = useQueryClient()
const createMutation = useMutation({
mutationFn: (data: CreateProductInput) => createProduct(data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: productsKeys.lists() })
},
})
const updateMutation = useMutation({
mutationFn: ({ id, data }: { id: string; data: UpdateProductInput }) =>
updateProduct(id, data),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: productsKeys.all })
},
})
const deleteMutation = useMutation({
mutationFn: (id: string) => deleteProduct(id),
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: productsKeys.lists() })
},
})
return {
createProduct: createMutation.mutateAsync,
updateProduct: updateMutation.mutateAsync,
deleteProduct: deleteMutation.mutateAsync,
isCreating: createMutation.isPending,
isUpdating: updateMutation.isPending,
isDeleting: deleteMutation.isPending,
}
}
`
$3
`typescript
// src/modules/products/hooks/useProducts.ts
'use client'
import { useProductsQueries } from './useProductsQueries'
import { useProductsMutations } from './useProductsMutations'
import { useProductsStore, useProductsFilters } from '../stores/useProductsStore'
export function useProducts(productId?: string) {
// Queries
const { products, product, isLoading, error } = useProductsQueries(productId)
// Mutations
const {
createProduct,
updateProduct,
deleteProduct,
isCreating,
isUpdating,
isDeleting
} = useProductsMutations()
// Store
const filters = useProductsFilters()
const {
selectedProductId,
isCreateDialogOpen,
setSelectedProductId,
setIsCreateDialogOpen,
setFilters,
} = useProductsStore()
// Datos filtrados
const filteredProducts = products.filter((p) =>
p.name.toLowerCase().includes(filters.search.toLowerCase())
)
return {
// Data
products: filteredProducts,
product,
// Loading states
isLoading,
isCreating,
isUpdating,
isDeleting,
error,
// Actions
createProduct,
updateProduct,
deleteProduct,
// UI State
selectedProductId,
isCreateDialogOpen,
filters,
setSelectedProductId,
setIsCreateDialogOpen,
setFilters,
}
}
`
$3
`typescript
// src/modules/products/components/products-list.tsx
'use client'
import { DataTable } from '@/components/tables/data-table'
import { useProducts } from '../hooks/useProducts'
import { columns } from '../columns'
export function ProductsList() {
const { products, isLoading } = useProducts()
if (isLoading) {
return Cargando productos...
}
return (
data={products}
searchKey="name"
searchPlaceholder="Buscar por nombre..."
/>
)
}
`
$3
`typescript
// src/modules/products/index.ts
export * from './components/products-list'
export * from './hooks/useProducts'
export * from './schemas/products.schema'
export { columns as productColumns } from './columns'
`
$3
`typescript
// src/app/(auth)/products/page.tsx
import { createClient } from '@/lib/supabase/server'
import { ProductsContent } from './products-content'
export default async function ProductsPage() {
const supabase = await createClient()
const { data: { user } } = await supabase.auth.getUser()
return
}
`
`typescript
// src/app/(auth)/products/products-content.tsx
'use client'
import { PageTransition, PageHeader, PageTitle } from '@/components/ui/animations'
import { ProductsList } from '@/modules/products'
export function ProductsContent({ userEmail }: { userEmail: string }) {
return (
Productos
)
}
`
$3
`typescript
// src/components/layout/sidebar.tsx
const navItems: NavItem[] = [
// ...otros items
{
path: '/products',
name: 'Productos',
icon: 'Package', // Agregar icono en icons.tsx si no existe
},
]
`
$3
`typescript
// proxy.ts
const protectedPaths = ['/dashboard', '/users', '/products', '/settings']
`
Variables de Entorno
`bash
.env.local
NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SUPABASE_URL=tu-supabase-url
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=tu-supabase-key
DATABASE_URL=postgresql://user:password@host:5432/database
`
Comandos
`bash
Desarrollo
pnpm dev
Build
pnpm build
Linting
pnpm lint
Base de datos
pnpm db:generate # Generar migraciones
pnpm db:migrate # Aplicar migraciones
pnpm db:seed # Ejecutar seeds
``