Tanto si utilizamos el asistente de Vue por línea de comandos para crear un proyecto como si lo hacemos de forma manual, necesitaremos conocer la estructura de carpetas donde residen los diferentes archivos de nuestro proyecto.
Así, a la hora de hacer cambios, sabremos si lo estamos haciendo el sitio adecuado (o que otras posibilidades tenemos), de forma que el proyecto sigue siendo fácil de mantener por otros miembros del equipo de desarrollo o por alguien externo que quiera trabajar en el proyecto.
En este artículo vamos a dar un repaso a todos los archivos y carpetas del proyecto y aprender para que sirve cada uno de ellos.
En primer lugar, vamos a centrarnos en la estructura de carpetas de la carpeta raíz, profundizando en cada uno de sus ficheros, así como con que herramientas están relacionados.
El primer nivel de carpetas (carpeta raíz del proyecto) suele tener una pinta similar a la siguiente (puede variar dependiendo de la elección del asistente al crear el proyecto):
├── public/
├── src/
├── tests/
├── .browserslistrc
├── .env
├── .eslintrc.js
├── .gitignore
├── README.md
├── babel.config.js
├── cypress.json
├── jest.config.js
├── package.json
├── package-lock.json
├── tsconfig.json
└── vue.config.js
Las tres primeras carpetas, public
, src
y tests
las abordaremos más adelante. Primero vamos a centrarnos en los ficheros. Ten en cuenta que algunos archivos (los que empiezan por punto) son ficheros ocultos:
Fichero o carpeta | Descripción |
---|---|
.browserslistrc |
Fichero de configuración de BrowserLists. Más info en BrowsersList. |
.env |
Fichero de variables de entorno del proyecto. |
.eslintrc.js |
Fichero de configuración del linter de Javascript ESLint. |
.gitignore |
Fichero que indica los archivos que Git debe ignorar al hacer el versionado. |
README.md |
Fichero Markdown donde se documenta información sobre el proyecto. |
babel.config.js |
Fichero de configuración de Babel, transpilador de Javascript. |
cypress.json |
Fichero de configuración de Cypress, framework de tests end-to-end. |
wdio.*.conf.js |
Ficheros de configuración de WebDriver, framework de tests end-to-end. |
jest.config.js |
Fichero de configuración de Jest, framework de tests unitarios. |
package.json |
Fichero de configuración del proyecto, usando NPM. Más info en NPM. |
package-lock.json |
Fichero histórico de versionado de apoyo para el package.json . Más info en NPM. |
tsconfig.json |
Fichero de configuración de TypeScript, un metalenguaje de Javascript que añade tipado. |
vue.config.js |
Fichero general de configuración del proyecto Vue. |
Veamos cada uno de ellos para saber sus particularidades.
El archivo .browserslistrc
es un fichero en el que podemos establecer una serie de reglas para indicar un conjunto de navegadores. Estas reglas pueden ser leídas por ciertas herramientas (deben soportar Browserslist, como por ejemplo: Babel, PostCSS, etc...), y harán lo posible para ser compatibles con los navegadores indicados.
En algunos casos, en lugar de utilizar el fichero .browserslistrc
, la información se incluye en un browserslist
del package.json. Tienes más información sobre como funciona en el artículo BrowsersList.
En algunos casos, la estructura de carpetas puede contener un archivo .editorconfig
. Este archivo es un intento de indicar características genéricas del código, para que se representen igual independientemente del editor que utilicen, ya sea VSCode, Atom, IntelliJ IDEA WebStorm, etc...
Este fichero incorpora convenciones utilizadas como el tipo de indentado (tabuladores o espacios), el tamaño del indentado, si hay que eliminar los espacios en blancos del final de las líneas, añadir una línea en blanco al final, etc...
Tienes más información en la página oficial de EditorConfig.
EL archivo .env
es un fichero de configuración del sistema que guarda una serie de variables de entorno relacionadas con el proyecto. Se suelen utilizar para establecer variables importantes que se utilizarán en varias partes del proyecto y así sea mucho más sencillo modificarlas y mantenerlas.
Es especialmente útil cuando trabajamos con sistemas mixtos con frontend y backend o cuando utilizamos contenedores de Docker, por ejemplo.
El linter de Javascript ESLint es una magnífica herramienta que nos avisa en tiempo real (mientras escribimos en el editor) de, no solo posibles errores en nuestro código, sino también de problemas de estilo que pueden provocar que, a la larga, nuestro código sea menos legible o mantenible.
Con toda probabilidad tendremos un fichero con el nombre .eslintrc.js
(Javascript) o .eslintrc.json
/ .eslintrc
(JSON). En dicho fichero tendremos la configuración de nuestro linter, que, si hemos utilizado el asistente @vue/cli
, habrá configurado con reglas especiales para que nos aconseje no sólo sobre Javascript, sino como mejorar el código de nuestros componentes .vue
.
Si quieres más información sobre ESLint, puedes echar un vistazo al artículo ESLint.
El fichero .gitignore
es un archivo donde podemos escribir, linea por linea, los nombres de archivos (o patrones o comodines) que queremos que Git
, nuestro sistema de control de versiones, ignore y no tenga en cuenta a la hora de guardar cambios en el repositorio.
Se trata de un simple fichero de texto que es obligatorio utilizar en nuestros proyectos, como mínimo para ignorar la carpeta node_modules. Si no sabes que ficheros y carpetas puede ser interesante añadir, puedes echar un vistazo a gitignore.io, donde te pueden aconsejar un .gitignore
indicando el editor o sistema operativo que uses.
El archivo .prettierrc
es un fichero de configuración que pertenece a Prettier, un formateador de código Javascript automático, que a pesar de ser bastante opinionated, permite modificar ciertos parámetros de comportamiento a través de este fichero y de algunas opciones.
El fichero README.md
es un fichero en formato Markdown, que es un tipo de formato de texto que permite convertirse a HTML. Mediante Markdown, con una serie de símbolos, podemos formatear un documento utilizando negritas, cursivas, encabezados, imágenes, etc...
Se suele incluir en los repositorios de Git, con el nombre en mayúsculas y la extensión en minúsculas: README.md
. Este fichero servirá como primero punto de información sobre el repositorio.
Si tienes instalado babel en tu proyecto, probablemente encontrarás un fichero babel.config.js
, .babelrc
o babel.config.json
. En algunos casos incluso puedes encontrar una entrada babel
en el package.json
, aunque no es muy habitual y no se recomienda esta variante de configuración.
Dicho fichero contiene información sobre los presets (conjunto de configuraciones predefinidas), plugins y otros detalles de Babel sobre el proyecto, para saber de que forma se va a realizar la transpilación de código Javascript moderno a código Javascript más antiguo.
Ten en cuenta que en un proyecto Vue, muchas herramientas parecen tener una configuración escueta o casi inexistente. Esto ocurre porque
Vue
tiene ficheros de configuración más extensos en otras rutas de paquetes ennode_modules/
. Es el caso de herramientas como Babel, Webpack u otros.
El framework de testing Cypress permite realizar tests end-to-end (e2e), un tipo de tests que se realizan en un entorno de navegador, pudiendo comprobar aspectos más ligados al navegador del usuario.
El fichero cypress.json
permite indicar ciertos detalles de configuración, que en el caso de Vue, simplemente hace referencia al fichero tests/e2e/plugins/index.js
, donde se hace referencia a los plugins de Cypress que se cargarán y modificarán o extenderán el comportamiento de Cypress. También se definen ciertas carpetas donde se guardan ciertos archivos relacionados con este framework.
El framework de testing WebDriver I/O es una alternativa a frameworks e2e como cypress o nightwatch, mediante el cuál se pueden realizar tests end-to-end siguiendo el enfoque estándar de WebDriver.
WebDriver I/O suele incluir en proyectos Vue tres ficheros: wdio.local.conf.js
(configuración para tests locales), wdio.sauce.conf.js
(configuración remota para tests en un proveedor Cloud) y wdio.shared.conf.js
(configuración compartida que usará cualquier entorno).
El framework Jest es una herramienta para crear tests unitarios en un proyecto de forma agnóstica, y que pueden funcionar tanto en proyectos con Javascript vanilla, como con frameworks como React
, Angular
o Vue
o incluso entornos como Node
.
Está desarrollada por Facebook y su API es bastante práctica y muy fácil de leer. El fichero jest.config.js
es el que se suele utilizar para definir su configuración, aunque muchas veces también podremos encontrar jest.json
o .jestrc
.
Los ficheros package.json
y package-lock.json
son los que utiliza NPM para crear y gestionar una aplicación o proyecto y sus dependencias. Si quieres más información sobre estos ficheros, echa un vistazo al artículo El archivo package.json.
El fichero tsconfig.json
tiene todos los detalles de configuración de TypeScript localizados en un mismo sitio. Vue lo utiliza para especificar los detalles de compilación que utilizará, así como la forma de actuar al procesar ficheros .ts
o código Typescript incluído dentro de la etiqueta <script lang="ts">
que utilizaremos en los ficheros SFC .vue
.
Además, el fichero shims-vue.d.ts
es un fichero que también existirá en nuestro proyecto si hemos elegido utilizar TypeScript. Los ficheros con extensión .d.ts
se utilizan para proporcionar información a TypeScript de la API de una librería o archivo escrito en Javascript. En este caso, shims-vue.d.ts
ayuda al editor a «entender» los ficheros .vue
que utiliza Vue como SFC (ver más adelante).
En el caso de activar soporte JSX con TypeScript, añadirá un archivo llamado shims.tsx.d.ts
o shims-tsx.d.ts
.
El fichero vue.config.js
permite incluir detalles de configuración adicionales de Vue, como por ejemplo, modificaciones sobre el comportamiento estándar de Webpack, opciones de configuración de plugins Vue instalados en el proyecto, etc...
Probablemente, observarás una carpeta denominada public/
en la carpeta raíz del proyecto. Esta carpeta se utiliza para almacenar ficheros estáticos que no serán procesados por el framework:
├── public/
│ ├── img/
│ ├── favicon.ico
│ ├── index.html
│ └── robots.txt
Vue copiará directamente el contenido de esta carpeta para utilizar en la versión definitiva de la web, por lo que es un lugar ideal para almacenar ficheros estáticos como robots.txt
, favicon.ico
, archivos HTML finales como el index.html
, o imágenes o recursos estáticos.
Ten en cuenta que estos archivos siempre serán públicos y cualquier usuario podrá acceder a ellos, ya que no pasa antes por el framework.
La carpeta src
es probablemente una de las más importantes. En ella se almacena el código fuente (source) de nuestro proyecto, el que estaremos modificando desde nuestro editor de texto o IDE. Es muy importante tener presente que dentro de src
siempre vamos a encontrar los archivos originales sin procesar:
├── src/
│ ├── assets/
│ ├── components/
│ ├── router/
│ ├── store/
│ ├── views/
│ ├── App.vue
│ ├── main.ts
│ ├── registerServiceWorker.ts
│ └── shims-vue.d.ts
Por ejemplo, en el caso de estar utilizando TypeScript o Sass, en src/
encontrarás ficheros .ts
y .sass
(los cuales no son capaces de ser leídos por un navegador). Mientras, en otra carpeta fuera de src/
, denominada comunmente dist/
o build/
se suelen almacenar los archivos finales procesados, como .js
y .css
, por ejemplo, que son los archivos procesados finales que irán desplegados en el servidor o web en producción definitiva.
En Vue, los archivos procesados en modalidad de desarrollo (npm run serve) se almacenan directamente en memoria, ya que está configurado Webpack para ello. Sólo se almacenarán en la carpeta
dist/
si creamos un build en la modalidad de producción connpm run build
.
En Vue, encontraremos siempre un fichero main.ts
(TypeScript) o main.js
(Javascript). Se trata del fichero principal que arranca el proyecto Vue y que se insertará en la plantilla index.html
que se incluye en la carpeta public/
.
Este archivo se encargará de cargar Vue y todos sus plugins asociados, como iremos viendo en posteriores artículos de esta página. Generalmente, main.js
o main.ts
cargan el framework y sus plugins y leen el fichero SFC App.vue
, donde comienza a crearse la aplicación Vue.
Los ficheros .vue
son los denominados SFC de Vue (Single File Components), se trata de un archivo especial de Vue, muy similar a un .html
que incluye 3 etiquetas HTML especiales: <template>
, <script>
y <style>
. A primera vista, parecen ficheros .html
, por lo que la curva de aprendizaje es muy sencilla, sin embargo, hay varias diferencias que veremos más adelante en el capítulo de Single File Components.
El fichero App.vue
es un fichero SFC especial, el componente general e inicial de la aplicación, desde donde se irán cargando los demás componentes.
El fichero registerServiceWorker.ts
(TypeScript) o registerServiceWorker.js
(Javascript) aparecerá en nuestra estructura de ficheros si hemos activado en el asistente la opción de tener compatibilidad con PWA (Progressive Web Apps).
El fichero registerServiceWorker.js
no es más que un archivo que se encarga de registrar los service workers, unos archivos Javascript especiales que se ejecutan en segundo plano en nuestro navegador y nos permiten realizar tareas interesantes que de otra forma no sería posible.
En el interior de la carpeta src
normalmente podemos encontrar una carpeta assets
. Dicha carpeta se utiliza para guardar archivos estáticos como imágenes, audio, tipografías, video, etc... La diferencia con la carpeta assets
o img
que existe en la carpeta public
es que, generalmente, los archivos estáticos que tenemos en public
son para permitir un acceso directo a la URL.
Por otro lado, los archivos que tenemos en la carpeta src/assets
se utilizan en nuestro código de la aplicación, importándolos, y muchas veces no queremos que se pueda acceder directamente a ellos mediante una URL concreta. Al utilizar imágenes de src/assets
, la imagen suele ser procesada por la herramienta que utilice el framework para procesar el Javascript (Webpack en este caso) y se suele renombrar.
Dentro de la carpeta src
nos encontraremos una carpeta router
si hemos elegido utilizar Vue Router en nuestra aplicación para crear rutas desde el frontend. En su interior tendremos un archivo index.js
o index.ts
donde podremos gestionar las rutas de la aplicación y los componentes que cargaremos.
Más adelante veremos más sobre Vue Router.
En el interior de src
es posible encontrar una carpeta store
. Dicha carpeta existe si hemos seleccionado la opción de utilizar Vuex, un gestor o almacén de estados. Las aplicaciones web de tipo SPA suelen utilizar un store o almacén donde se guarda información centralizada para que cualquier componente o parte de la aplicación pueda acceder a ella, almacenar o recuperar información y gestionarla de forma segura.
Más adelante profundizaremos en Vuex.
También en el interior de la carpeta src
podremos encontrar components
, probablemente una de las carpetas más importantes de nuestro proyecto Vue. En ella colocaremos los componentes .vue
que iremos creando durante nuestro proyecto. Los componentes .vue
son archivos que contienen el HTML, CSS y Javascript que está relacionado con una determinada parte de la página, como podría ser un botón, un panel desplegable o un comparador de imágenes.
En el caso de haber activado Vue Router, existirá una carpeta views
donde también se guardan componentes. La diferencia respecto a la carpeta components
, es que en views
se guardan componentes que definen la estructura general de una página, mientras que en components
se guardan partes reutilizables que podemos utilizar en múltiples lugares de nuestra web.
Más adelante veremos más sobre los componentes de Vue.
Por último, y no por ello menos importante, la carpeta tests/
situada en la carpeta raíz del proyecto es la que contiene los ficheros para testear nuestra aplicación web. Observa que tenemos una carpeta unit
para los tests unitarios y una carpeta e2e
para los tests end-to-end:
└── tests/
├── e2e/
└── unit/
Opciones frecuentes para realizar tests unitarios en Vue suelen ser:
Por otro lado, para realizar tests end-to-end en Vue, se suele optar por:
Soy Manz, vivo en Tenerife (España) y soy streamer partner en Twitch y profesor. Me apasiona el universo de la programación web, el diseño y desarrollo web y la tecnología en general. Aunque soy full-stack, mi pasión es el front-end, la terminal y crear cosas divertidas y locas.
Puedes encontrar más sobre mi en Manz.dev