Lecciones de enviar un SaaS con Next.js y de crear una CLI de andamiaje
Explica las decisiones fundamentales: elección de tecnologías, autenticación, multiarrendatario, facturación y gestión de estado, además de cómo crear una CLI que simplifica la configuración de proyectos Next.js.
Desplegar un producto SaaS real con React y Next.js no se trata tanto de elegir una biblioteca de moda como de tomar correctamente decenas de decisiones pequeñas y poco llamativas antes incluso de tocar un panel de control. La misma disciplina que permite que la arquitectura de un producto resista las exigencias de clientes reales también se aplica en tareas tan cotidianas como estructurar un nuevo proyecto Next.js; por eso, una herramienta CLI desarrollada internamente para generar código base acaba enseñando la misma lección que el desarrollo del propio SaaS: es en el aburrido trabajo de configuración donde realmente triunfan o fracasan los proyectos.
Elegir una tecnología que no te ralentice
Después de desplegar más de un producto SaaS, la combinación de tecnologías suele adoptar una estructura predecible:
- Next.js como el único framework para el enrutamiento, la renderización del lado servidor y las rutas API, de modo que no tengas que manejar herramientas separadas para cada función.
None of these choices are made for novelty's sake. Together they let a small team move quickly without quietly building up technical debt they'll never have time to repay.
Build the Unglamorous Foundations First
It's tempting for founders to jump straight into building dashboards. Resist that urge. Before anything user-facing, get these three things in place:
- Autenticación — implementada con sesiones reales, no solo tokens almacenados en localStorage.
- Multitenancy — incluso si hoy solo tienes un cliente, diseña la solución para más de uno desde el principio.
- Gancho de facturación — configurar los webhooks de Stripe desde temprano evita una reescritura complicada una vez que el producto se lance realmente.
He aquí un patrón que vale la pena adoptar para realizar llamadas a APIs con alcance por tenant sin tener que repetir el código:
// hooks/useTenantFetch.ts
import { useCallback } from "react";
import { useSession } from "next-auth/react";
export function useTenantFetch() {
const { data: session } = useSession();
const fetchScoped = useCallback(
async (endpoint: string, options: RequestInit = {}) => {
if (!session?.tenantId) throw new Error("No active tenant");
const res = await fetch(`/api/${session.tenantId}${endpoint}`, {
...options,
headers: {
...options.headers,
"Content-Type": "application/json",
},
});
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
return res.json();
},
[session]
);
return { fetchScoped };
}
Es una pequeña utilidad, pero te ahorra tener que distribuir verificaciones de ID de tenant en docenas de componentes más adelante.
Saber qué debe estar en el estado global
No todos los datos merecen un lugar en Redux. Un ingeniero que trabaja en una startup respaldada por Y Combinator lo expresó bien: el estado global es una deuda que genera intereses con el tiempo. Reserve Redux (o su almacén global de elección) exclusivamente para aquello que realmente afecta a toda la interfaz de usuario —modales, flags de funcionalidades, preferencias del usuario— y deje que React Query o SWR se encarguen de todo lo demás, que en realidad no es más que datos del servidor disfrazados.
Algunas conclusiones resumen los aspectos relacionados con la creación de aplicaciones SaaS:
- Haga que la autenticación y la facturación funcionen antes de invertir en una interfaz de usuario pulida.
- TypeScript deja de ser opcional en cuanto entra en juego el dinero.
- Resista la tendencia a centralizar excesivamente el estado; la mayoría de las funcionalidades pertenecen a herramientas de estado del servidor, no a un almacén global.
Nada de esto proviene de buscar la biblioteca más reciente. Proviene de los principios fundamentales: establecer desde el principio la autenticación, la gestión de usuarios y la facturación, y todo lo demás —el crecimiento, las nuevas funciones, la escalabilidad— se vuelve mucho más fácil de desarrollar sobre esa base.
Cuando la propia configuración se convierte en el cuello de botella
Ese mismo instinto por eliminar tareas repetitivas y propensas a errores en la configuración es lo que eventualmente conduce a automatizar esos pasos básicos. Todo desarrollador frontend conoce esa rutina: se crea un esqueleto para un nuevo proyecto con create-next-app, y luego comienza el trabajo realmente tedioso. Se crea una carpeta components, se separa ui de features, se configuran los hooks, se conectan los types compartidos, se escriben ayudantes de utilidad, se configuran alias de rutas y se organiza la jerarquía de carpetas; y puede pasar una hora antes de haber escrito siquiera una línea de lógica empresarial real.
Después de realizar ese ritual demasiadas veces, el siguiente paso lógico fue automatizarlo, lo que dio como resultado el primer paquete npm de código abierto publicado: nexarch-cli.
El problema subyacente
Las plantillas iniciales estándar de Next.js ofrecen una hoja en blanco, no una arquitectura lista para producción. Las aplicaciones modernas generalmente necesitan:
- Una separación clara entre la lógica de presentación y la lógica de negocio
- Un agrupamiento modular basado en funcionalidades
- Definiciones de tipos escalables y envoltorios de utilidades
- Convenciones consistentes que todo el equipo pueda seguir
Recrear todo esto a mano para cada prototipo o proyecto del cliente es lento, inconsistente y propenso a errores.
Qué hace realmente nexarch-cli
nexarch-cli es una herramienta interactiva de línea de comandos diseñada para crear en cuestión de segundos una arquitectura limpia y modular de Next.js. En lugar de crear manualmente carpetas anidadas y archivos de ejemplo, basta con responder a unas pocas preguntas en la terminal, y la herramienta establecerá para usted la estructura básica.
Sus principales características incluyen:
- Estructuración interactiva mediante sencillas preguntas en la terminal adaptadas a sus necesidades.
- Arquitectura modular con convenciones preconfiguradas para permitir el crecimiento de la aplicación.
- No se requiere instalación global — funciona bajo demanda mediante
npx. - Alineación con las convenciones actuales de Next.js y React, manteniendo las estructuras de directorios acordes con las prácticas modernas.
Ejecutarlo
No es necesario instalar nada a nivel global. Puedes ejecutarlo directamente:
npx nexarch-cli
Una vez que respondas a las preguntas, se generará la estructura de tu proyecto y estará lista para el desarrollo real.
Lecciones al crear una primera CLI
Desarrollar y publicar esto como la primera herramienta para desarrolladores conllevó una fuerte curva de aprendizaje. Algunas de las lecciones más importantes:
- La experiencia de usuario en la terminal es tan importante como el código subyacente. Manejar las salidas de los procesos de manera limpia, presentar prompts legibles y mostrar mensajes de error claros son tan cruciales como la lógica que genera los archivos.
- Las operaciones del sistema de archivos ocultan muchos casos límite. Escribir herramientas para crear directorios de forma recursiva y plantillas de archivos que funcionen de manera consistente en diferentes sistemas operativos requiere pruebas cuidadosas y repetidas.
package.json (bin), gestionar los permisos de archivo con chmod y mantener la carga por dependencias casi en cero revelan cómo funcionan realmente las herramientas CLI basadas en Node.Dónde se encuentra el proyecto actualmente
La herramienta sigue siendo un esfuerzo inicial de código abierto, y se beneficia de aportes externos mientras aún está tomando forma. El código se encuentra en github.com/CaffeineLogs/nexarch-cli, y el paquete publicado puede encontrarse en el registro de npm bajo el nombre nexarch-cli.
Cualquiera que tenga un diseño de proyecto preferido diferente, o que se enfrente a situaciones que el scaffold aún no maneja bien, puede plantearlas como un problema en el repositorio. Las sugerencias sobre posibles mejoras futuras —como configuraciones de estilo integradas o presets listos para la gestión de estado— también son bienvenidas como puntos de discusión o comentarios.
Tanto si está decidiendo qué incluir en Redux como cómo estructurar un proyecto nuevo de Next.js, la lección se repite: las partes de un proyecto que resultan más tediosas —autenticación, arrendamiento, facturación, estructura de carpetas— son precisamente las que vale la pena resolver correctamente, y a menudo automatizar, antes que cualquier otra cosa.
Lecturas relacionadas
- Auto-generar un cliente API type-safe de Next.js a partir de NestJS Swagger — Aprenda cómo eliminar tipos API duplicados utilizando NestJS Swagger y Orval para generar automáticamente ganchos React Query type-safe para Next.js.
- Construir UI de agente AI multietapa con Next.js y el AI SDK — Aprenda cómo diseñar una interfaz de agente AI lista para producción usando herramientas tipadas, bucles multietapa y componentes de UI generativos en tiempo real en Next.js.