Estructura de TypeScript: código inicial y carpetas

Publicado el 2026-10-27 · Actualizado el 2026-10-27

Una buena estructura inicial de TypeScript no consiste en crear veinte carpetas vacías. Consiste en separar las responsabilidades que ya existen, activar comprobaciones útiles y preparar una forma simple de probar el código. Este ejemplo explica qué archivos necesitas al comienzo y qué decisiones puedes posponer.

Empezar por un proyecto pequeño y ejecutable

Antes de discutir arquitectura, define un caso de uso: una API de reservas, una herramienta de inventario o un panel interno. Anota la entrada, la salida y los fallos previsibles. Una estructura limpia responde a esas necesidades; no a una plantilla enorme descargada sin entenderla. En equipos pequeños suele funcionar mejor empezar con pocos módulos.

Crea un repositorio, inicializa el proyecto con el gestor de paquetes elegido e instala TypeScript como dependencia de desarrollo. Mantén un archivo README con los comandos de instalación, compilación y ejecución. Desde el primer día, otra persona debería poder clonar el repositorio y reproducir el resultado sin preguntar qué pasos faltan.

Carpetas recomendadas sin sobreingeniería

Una distribución inicial razonable incluye src para el código de aplicación, src/domain para reglas de negocio, src/services para casos de uso, src/adapters para comunicaciones externas y tests para las comprobaciones. Puedes mantener los tipos cerca del módulo que los utiliza. No es obligatorio que cualquier aplicación incluya todas esas carpetas desde el primer día.

Por ejemplo, en un sistema de reservas, domain puede definir las reglas de disponibilidad; services coordina la creación de una reserva y adapters habla con la base de datos. El controlador HTTP convierte una solicitud en datos validados y llama al servicio. Así es posible cambiar la interfaz web sin reescribir la regla central de negocio.

Configurar tsconfig con decisiones explícitas

Activa strict en tsconfig.json para aumentar el rigor de las comprobaciones de tipos. Define un directorio de salida, una raíz de código y una configuración de módulos compatible con el entorno real en el que ejecutarás la aplicación. No copies opciones de Node a un proyecto de navegador ni al revés: las resoluciones de módulos pueden comportarse de forma diferente.

Un punto de partida ilustrativo usa compilerOptions con strict: true, rootDir: "./src" y outDir: "./dist". La elección de module y moduleResolution depende del runtime y del empaquetador. Después ejecuta el compilador con --noEmit cuando quieras revisar los tipos sin generar artefactos. La documentación oficial de TypeScript es la referencia para cada opción.

Validar entradas aunque exista tipado estático

TypeScript comprueba tipos durante el desarrollo, pero no convierte automáticamente en seguros los datos que llegan por HTTP, formularios o archivos. Un cliente externo todavía puede enviar campos faltantes, fechas inválidas o números fuera de rango. Separa los tipos internos de la validación en tiempo de ejecución y responde a errores con mensajes comprensibles.

Si una reserva recibe fecha, cantidad de asistentes y correo electrónico, valida cada campo antes de guardar. Prueba solicitudes sin fecha, con cantidades negativas y con una cadena inesperada. Si toda la confianza depende de una anotación como `as Reservation`, el sistema puede aceptar datos inválidos y fallar demasiado tarde.

Aislar efectos y facilitar pruebas

Las operaciones que consultan servicios, envían correos o escriben en una base de datos tienen efectos externos. Mantén esas operaciones detrás de interfaces sencillas para poder sustituirlas durante las pruebas. Las reglas que calculan importes, límites o disponibilidad deben probarse sin depender de la red ni de credenciales reales.

En un ejemplo de compras, una función pura puede calcular el subtotal y los descuentos a partir de entradas verificadas. Otra capa gestiona la operación de pago. Así, un error en la pasarela no obliga a cambiar el cálculo del precio. Incluye casos normales, límites, duplicados e intentos repetidos de la misma operación.

Crear un flujo mínimo de calidad

Añade comandos para comprobar tipos, ejecutar pruebas y construir el proyecto. El pipeline de integración continua debe fallar cuando alguno de esos pasos no se completa. Conserva un archivo de ejemplo de variables de entorno sin secretos, documenta las versiones requeridas y evita incluir credenciales en el repositorio.

Incluye una prueba de principio a fin de la operación más valiosa, aunque al comienzo haya pocas funciones. Por ejemplo, crear una solicitud, validar el resultado y comprobar que el usuario recibe una confirmación. Este recorrido descubre fallos de integración que las pruebas de funciones individuales no detectan.

Cuándo usar un agente de desarrollo

Un agente como Infera Agent puede ayudarte a generar un esqueleto inicial, organizar módulos y revisar casos de prueba a partir de una especificación concreta. Debes inspeccionar el código resultante, ejecutar las comprobaciones y verificar que el proyecto funciona en el entorno elegido. Un repositorio que compila no equivale automáticamente a una aplicación lista para producción.

Antes de pagar por una herramienta de desarrollo asistido, prueba una tarea representativa: modificar una regla, añadir una prueba y corregir un fallo detectado. Mide si el resultado reduce tiempo sin crear deuda técnica. El verdadero valor comercial se encuentra en mantener y evolucionar el producto, no en generar carpetas rápidamente.

Si necesitas convertir este flujo en una aplicación comprobable, empieza con un prototipo limitado en Infera Agent: https://inferaagent.com. Evalúa las pruebas, los costes reales y la utilidad antes de contratar un plan de pago.

Preguntas

Empieza gratis Plantillas