Vue 3 + TypeScript: cómo organizar un proyecto frontend moderno

Cuando un proyecto frontend empieza siendo pequeño, prácticamente cualquier estructura parece buena.

Creas un proyecto, haces un par de componentes, añades unas vistas y empiezas a programar.

Y funciona.

El problema suele aparecer unos meses después.

El proyecto empieza a crecer, aparecen más pantallas, más componentes, llamadas a APIs, modelos de datos, formularios, estados, lógica compartida…

Y de repente tienes un components con treinta archivos, un par de componentes enormes y una carpeta utils donde nadie sabe muy bien qué debería ir.

Esto es algo que he visto más de una vez.

Y también es algo que he aprendido con el tiempo: organizar bien un proyecto frontend desde el principio no significa crear una arquitectura gigantesca. Significa tener claro dónde debería vivir cada cosa.

En este artículo quiero enseñar cómo suelo plantear la estructura de un proyecto con Vue 3, TypeScript y Vite, y sobre todo explicar por qué separaría unas responsabilidades de otras.

No pretendo decir que esta sea la única estructura correcta.

Cada proyecto tiene sus necesidades.

Pero sí creo que puede ser un buen punto de partida para un frontend que vaya a crecer.

Vue 3, TypeScript y Vite

Antes de hablar de carpetas, vamos a situarnos.

Una combinación que me gusta bastante para proyectos frontend actuales es:

  • Vue 3 para la interfaz.
  • TypeScript para el tipado.
  • Vite como herramienta de desarrollo y build.

La combinación es bastante cómoda.

Vite se encarga de arrancar el proyecto y del proceso de construcción.

Vue nos permite dividir la interfaz en componentes.

Y TypeScript nos ayuda a mantener bajo control los datos que manejamos.

Podríamos tener algo así:

Vue 3
   +
TypeScript
   +
Vite

Y encima de esto construiremos nuestra aplicación.

Una de las cosas que más me gusta de trabajar con componentes es que puedes empezar con algo muy sencillo y separar responsabilidades conforme el proyecto lo necesita.

El problema aparece cuando esperamos demasiado para hacerlo.

El problema de meterlo todo en componentes

Imaginemos que tenemos una pantalla de productos.

Al principio podemos crear:

Products.vue

Y dentro ponemos:

  • La petición a la API.
  • El listado.
  • Los filtros.
  • La paginación.
  • El formulario.
  • La validación.
  • La lógica para guardar.
  • Los mensajes de error.

Al principio parece cómodo.

Tenemos todo en un mismo sitio.

Pero el archivo empieza a crecer.

500 líneas.

800 líneas.

1000 líneas.

Y llega ese momento en el que abrir Products.vue empieza a dar un poco de miedo.

Me ha pasado.

Y precisamente por eso intento separar las responsabilidades antes de llegar a ese punto.

No porque tener un componente grande sea automáticamente malo.

Sino porque cuando un componente empieza a encargarse de demasiadas cosas, mantenerlo se vuelve bastante más difícil.

Una estructura que suelo utilizar

Para un proyecto de cierto tamaño, podríamos empezar con algo parecido a esto:

src/
├── assets/
├── components/
├── composables/
├── router/
├── services/
├── stores/
├── types/
├── views/
├── App.vue
└── main.ts

No significa que todos los proyectos necesiten exactamente estas carpetas.

De hecho, si el proyecto es pequeño probablemente no necesites algunas.

Pero cuando empiezas a tener cierta complejidad, esta separación resulta bastante cómoda.

Vamos a ver qué pondría en cada una.

components: piezas reutilizables de la interfaz

Aquí colocaríamos componentes que forman parte de la interfaz.

Por ejemplo:

components/
├── PokemonCard.vue
├── TypeBadge.vue
├── SearchInput.vue
├── LoadingSpinner.vue
└── Pagination.vue

La idea es que estos componentes no sepan demasiado sobre el resto de la aplicación.

Por ejemplo, un PokemonCard debería recibir un Pokémon y mostrarlo.

<PokemonCard :pokemon="pokemon" />

No debería necesitar saber cómo hemos obtenido ese Pokémon.

Eso es responsabilidad de otra parte de la aplicación.

Esta separación puede parecer excesiva cuando el proyecto tiene cinco componentes.

Cuando tienes cincuenta, empiezas a agradecerla.

views: las páginas de la aplicación

Aquí pondríamos las diferentes pantallas.

Por ejemplo:

views/
├── HomeView.vue
├── PokemonListView.vue
├── PokemonDetailView.vue
└── AboutView.vue

Una view representa normalmente una página completa.

Por ejemplo:

/pokemon

podría cargar:

PokemonListView.vue

Y:

/pokemon/25

podría cargar:

PokemonDetailView.vue

Una cosa que intento evitar es que una view termine convirtiéndose en un componente gigantesco.

Si empieza a crecer demasiado, probablemente haya lógica que pueda extraerse a componentes, composables o servicios.

router: las rutas

Aquí tenemos la configuración del Vue Router.

Por ejemplo:

router/
└── index.ts

Y podríamos tener:

const routes = [
    {
        path: '/',
        component: HomeView
    },
    {
        path: '/pokemon',
        component: PokemonListView
    },
    {
        path: '/pokemon/:id',
        component: PokemonDetailView
    }
]

De esta forma tenemos en un mismo sitio la navegación principal de la aplicación.

Cuando el proyecto crece también podemos añadir aquí guards, rutas protegidas o carga lazy de determinadas páginas.

services: hablar con nuestra API

Esta carpeta me parece especialmente importante cuando trabajamos con un backend separado.

Por ejemplo:

services/
├── pokemonService.ts
├── authService.ts
└── userService.ts

Podríamos tener:

export async function getPokemon(id: number) {
    const response = await fetch(`/api/pokemon/${id}`)

    return response.json()
}

La idea es que el componente no tenga que preocuparse de cómo hacemos la petición HTTP.

El componente necesita los datos.

El servicio sabe cómo conseguirlos.

Esta separación me parece especialmente útil cuando el frontend consume una API REST.

Y aquí hay algo que para mí es importante: el frontend debería hablar con nuestro backend, no directamente con servicios externos que forman parte de la lógica del backend.

Si tenemos un backend en NestJS, por ejemplo:

Vue
 ↓
NestJS API
 ↓
Servicio externo

Vue debería conocer nuestra API.

No debería tener que saber qué servicios externos utiliza NestJS por detrás.

types: TypeScript empieza a tener sentido aquí

Una de las grandes ventajas de utilizar TypeScript aparece precisamente cuando empezamos a definir los datos que maneja nuestra aplicación.

Podríamos tener:

types/
├── pokemon.ts
├── user.ts
└── product.ts

Y definir:

export interface Pokemon {
    id: number
    name: string
    height: number
    weight: number
}

Ahora el resto de la aplicación sabe qué estructura tiene un Pokémon.

Y esto puede parecer una pequeña diferencia.

Pero cuando tienes una aplicación grande, tener los tipos bien definidos ayuda muchísimo.

El editor puede avisarnos de errores.

Podemos autocompletar propiedades.

Y si cambiamos la estructura de una respuesta, TypeScript puede ayudarnos a localizar qué partes de la aplicación tenemos que revisar.

Para mí, este es uno de los motivos por los que cada vez me cuesta más volver a proyectos grandes de JavaScript sin tipado.

composables: lógica reutilizable

Los composables son una de las partes de Vue 3 que más me gustan.

Imaginemos que tenemos lógica para buscar:

composables/
└── useSearch.ts

Podríamos tener:

export function useSearch() {
    const search = ref('')

    function clear() {
        search.value = ''
    }

    return {
        search,
        clear
    }
}

Después podemos utilizar esa lógica desde diferentes componentes.

La idea importante es que un composable no tiene por qué representar una parte visual.

Representa lógica reutilizable.

Y aquí hay una diferencia que considero bastante importante:

Un componente se preocupa principalmente de la interfaz.

Un composable puede encargarse de lógica que queremos reutilizar.

Esto permite evitar que acabemos copiando y pegando la misma lógica en cinco componentes diferentes.

¿Y stores?

Cuando una aplicación empieza a tener información que necesitan diferentes partes de la interfaz, aparece otro problema:

¿Dónde guardamos ese estado?

Por ejemplo:

  • Usuario autenticado.
  • Preferencias.
  • Carrito.
  • Configuración.
  • Datos compartidos.

Aquí podemos utilizar una store.

Si utilizamos Pinia, podríamos tener:

stores/
├── auth.ts
├── cart.ts
└── settings.ts

Por ejemplo:

export const useAuthStore = defineStore('auth', {
    state: () => ({
        user: null
    })
})

Pero aquí también intento aplicar una regla bastante sencilla:

No meter todo en una store.

Que podamos guardar algo globalmente no significa que debamos hacerlo.

Si un dato solo lo necesita un componente, probablemente no necesita estar en una store.

Las stores deberían utilizarse cuando realmente tenemos estado que necesita ser compartido.

¿Y los assets?

Aquí podemos colocar recursos estáticos:

assets/
├── images/
├── icons/
└── styles/

Imágenes, fuentes, estilos globales o cualquier otro recurso que tenga sentido mantener dentro del proyecto.

De nuevo, no hay que convertirlo en una religión.

Si el proyecto necesita otra organización, se cambia.

Lo importante es que alguien que entre en el proyecto pueda encontrar las cosas sin tener que hacer arqueología.

Cómo se conectaría todo

Si juntamos todas estas piezas, podríamos tener algo parecido a esto:

                 ┌──────────────┐
                 │     View     │
                 └──────┬───────┘
                        │
             ┌──────────┴──────────┐
             │                     │
       Components            Composables
             │                     │
             └──────────┬──────────┘
                        │
                     Services
                        │
                        ▼
                    REST API
                        │
                        ▼
                     Backend

Y cada parte tiene una responsabilidad bastante clara.

La View organiza la página.

Los components representan piezas visuales.

Los composables contienen lógica reutilizable.

Los services se encargan de comunicarse con la API.

Los types describen los datos.

Las stores mantienen el estado compartido.

Y el backend se ocupa de toda la lógica que no corresponde al frontend.

No es una arquitectura especialmente revolucionaria.

Y precisamente por eso me gusta.

Un ejemplo completo

Vamos a imaginar una aplicación de Pokémon.

Tenemos:

PokemonListView.vue

La vista necesita mostrar una lista.

Podría utilizar:

pokemonService.ts

para obtener los datos:

const pokemon = await getPokemon()

Los datos están tipados:

interface Pokemon {
    id: number
    name: string
    sprite: string
}

Y la vista utiliza:

PokemonCard.vue

para representar cada Pokémon.

Podríamos terminar teniendo:

views/
└── PokemonListView.vue

components/
└── PokemonCard.vue

services/
└── pokemonService.ts

types/
└── pokemon.ts

Cada pieza tiene su trabajo.

Y si mañana cambia la API, no tenemos que empezar buscando llamadas HTTP por veinte componentes diferentes.

Podemos empezar mirando pokemonService.ts.

Eso, para mí, es exactamente lo que debería conseguir una buena organización.

El error de intentar crear la arquitectura perfecta desde el día uno

Aquí quiero hacer una pequeña pausa porque es algo que veo bastante.

Cuando estamos empezando un proyecto nuevo es muy tentador crear:

components/
composables/
services/
stores/
types/
utils/
helpers/
repositories/
models/
interfaces/
factories/
...

Y todavía no hemos escrito ni una pantalla.

Yo no lo haría.

La arquitectura debería crecer con el proyecto.

Si mañana solo tienes:

App.vue

no necesitas quince carpetas.

Empieza sencillo.

Cuando aparezca una responsabilidad que necesite separarse, sepárala.

Esto también lo he aprendido con los años: una buena arquitectura no es la que tiene más carpetas.

Es la que hace que el código sea fácil de entender.

¿Dónde pongo una función?

Esta es una pregunta bastante habitual.

Imaginemos una función:

formatPrice(price)

¿Va en un composable?

¿En un service?

¿En una store?

¿En utils?

No hay una respuesta universal.

Yo intentaría preguntarme:

¿De qué depende esta función?

Si es una función puramente reutilizable:

formatPrice(29.99)

podría tener sentido como utilidad.

Si necesita estado reactivo, quizá sea más apropiado un composable.

Si habla con una API, probablemente debería estar en un service.

Si gestiona estado global, quizá pertenezca a una store.

Parece una tontería, pero hacerse esta pregunta evita acabar metiendo absolutamente todo en utils.

Y sí, esa carpeta también puede convertirse en un cajón desastre.

Lo mismo ocurre con los componentes

Otro error bastante habitual es crear componentes demasiado grandes.

Por ejemplo:

PokemonDetail.vue

y acabar con:

PokemonDetail.vue
  ├── Información básica
  ├── Estadísticas
  ├── Habilidades
  ├── Evoluciones
  ├── Movimientos
  ├── Modal
  └── 700 líneas de código

En algún momento probablemente tenga sentido separar:

PokemonBasicInfo.vue
PokemonStats.vue
PokemonAbilities.vue
PokemonEvolution.vue
PokemonMoves.vue

No porque haya una regla que diga que un componente no puede tener 700 líneas.

Sino porque probablemente esas partes tengan responsabilidades diferentes.

Y cuando una pieza tiene una responsabilidad clara, normalmente resulta más fácil trabajar con ella.

¿Hay una estructura perfecta?

No.

Y creo que es importante decirlo.

Puedes encontrar diez proyectos Vue y probablemente los diez tengan estructuras diferentes.

Algunos utilizarán una arquitectura basada en features.

Otros organizarán todo por tipo de archivo.

Otros tendrán una mezcla de ambas.

Y no significa que uno esté necesariamente bien y los demás mal.

La estructura debería adaptarse al proyecto.

Para una aplicación pequeña:

components/
views/
services/

puede ser suficiente.

Para una aplicación más grande quizá tenga sentido organizar por funcionalidades:

features/
├── pokemon/
├── users/
├── auth/
└── dashboard/

Lo importante es que la organización ayude al equipo.

No que quede bonita en GitHub.

Una cosa que he aprendido trabajando con proyectos grandes

Cuando llevas tiempo trabajando en desarrollo, empiezas a valorar mucho una cosa que al principio quizá no parece tan importante:

poder volver a un proyecto meses después y entenderlo rápidamente.

Porque el problema no es solamente trabajar en el código hoy.

También está el:

«¿Quién escribió esto?»

«¿Por qué esta llamada está aquí?»

«¿Dónde se modifica este dato?»

«¿Por qué este componente necesita esta información?»

Y cuando el proyecto está bien separado, encontrar las respuestas resulta bastante más sencillo.

Para mí, una buena estructura no debería hacer que programar sea más complicado.

Debería hacer que entender el proyecto sea más fácil.

Algunas reglas que intento seguir

No son reglas universales.

Son simplemente algunas ideas que me han funcionado trabajando con proyectos web.

1. Los componentes deberían tener responsabilidades claras

Si un componente empieza a hacerlo todo, probablemente sea hora de dividirlo.

2. Las llamadas a la API deberían estar centralizadas

No quiero encontrar fetch() repartidos por veinte componentes.

3. TypeScript debería utilizarse de verdad

Si tenemos TypeScript pero todo acaba siendo any, estamos perdiendo una parte importante de sus ventajas.

4. No todo necesita ser global

No conviertas cada dato en una store simplemente porque puedes.

5. Extrae lógica cuando realmente se reutilice

No hace falta crear un composable para una función que solo utiliza un componente.

6. La arquitectura puede evolucionar

No necesitas descubrir hoy cómo será el proyecto dentro de dos años.

Y probablemente tampoco puedas hacerlo.

Vue 3 + TypeScript no consiste solo en utilizar herramientas modernas

Esta es probablemente la idea que me gustaría dejar como conclusión.

Utilizar Vue 3, TypeScript y Vite no significa automáticamente que tengamos un frontend bien construido.

Puedes tener todas estas tecnologías y terminar con un proyecto imposible de mantener.

Y también puedes construir una aplicación perfectamente mantenible sin utilizar una arquitectura gigantesca.

Las herramientas ayudan.

Pero la organización y las decisiones que tomamos siguen siendo mucho más importantes.

Después de años trabajando en desarrollo web, cada vez tengo más claro que una buena arquitectura no debería llamar la atención.

Debería simplemente hacer que trabajar con el proyecto resulte más sencillo.

Conclusión

Vue 3 y TypeScript ofrecen una base muy buena para construir aplicaciones frontend modernas.

Pero cuando el proyecto empieza a crecer, la tecnología por sí sola no va a solucionar el problema.

Tenemos que decidir dónde colocar cada cosa.

Qué pertenece a un componente.

Qué debería ser un composable.

Qué debe comunicarse con la API.

Qué información necesita estar en una store.

Qué datos deberían estar tipados.

Y qué cosas sencillamente no necesitan existir todavía.

Una estructura como:

src/
├── assets/
├── components/
├── composables/
├── router/
├── services/
├── stores/
├── types/
├── views/
├── App.vue
└── main.ts

puede ser un punto de partida perfectamente válido.

Pero no hay que obsesionarse con ella.

La mejor estructura no es la que tiene más carpetas ni la que parece más profesional. Es la que permite que tú —o la persona que venga después— pueda abrir el proyecto y entender rápidamente dónde está cada cosa.

Y después de haber trabajado con proyectos de tamaños muy diferentes, creo que esa es una de las cosas que más se terminan valorando.

Porque programar es importante.

Pero mantener lo que has programado durante meses o años también lo es.

Media: 0,00/5 0 votos