template-vue

A complete vue template for a robust project.This includes link to different tools used.

Libraries used

• Typescript
• Vue.js
• vue-router
• Pinia store
• vue-i18n
• vue-test-utils
• TailwindCss
• openapi-typescript-codegen
• vitest
• vite
• Cypress
• husky
• eslint-config-epsvue. It combine Eslint, Prettier and Stylelint and it is also customizable 😉
• lint-staged
• commitizen: this is a nice utils for commit template 🤙
• vuelidate: Vuelidate is a simple, but powerful, lightweight model-based validation for Vue.js 3 and 2.

Project structure

Having a good structure is one of the key points for a good, maintainable and evolution project 🤙. But, this also helps developer when dealing with the project in the future and also when they want to improve it 😉. Here is an example of project structure we proposed

The most crucial things in web development are the tests (units, integration, e2e, etc.). In this one, there are the units tests and the e2e.

E2E

End-to-end testing is a key part of software development, especially in agile methodologies. It’s more than just checking parts of the code 🤭; it’s about testing the whole application as a user would, from start to finish. This method checks that every system and feature works together correctly, ensuring the software does what it’s supposed to do 👷🏽‍♂️.

In essence, end-to-end testing examines the application’s workflow—the path a user follows to complete tasks. It combines different testing types, such as GUI, database, and security testing. Tools such as Selenium and Cypress help automate these tests, making them more efficient and reliable. End To End Testing: Tools, Types, & Best Practices

In our case, we used Get started with cypress to conduct our e2e tests. For the structure, I placed the cypress folder that contains all about it outside the src file; The reason is that the tests are not needed in our end build. The e2e test are placed in the cypress/e2e folder where we have many folders depending on the device.

• desktop: Where we place all the test related to desktop (>1280)
• laptop: Where we place all the test related to laptop (>1024)
• tablet : Where we place all the test related to tablet (>640)
• mobile : Where we place all the test related to mobile (>320)

We also created a cypress/utils folder where we can place all reusable interceptors and helpers used in our e2e tests. This is also to separate our e2e tests to our main code inside the src folder. The folder like fixtures, support are generated by cypress. You can find more in the documentation.

Public folder

This folder is most likely we place the icons for each device (ios, android, etc.) and these are referenced in the index.html file inside the head tag.

Specs

This file contains all the specifications (contracts .yaml | .yml) files our app will need to call the backend services. The files used there are used to generate the typeScript types and functions we will use in our module. There can have many depending on the architecture(microservice). To generate this, we used openapi-typescript-codegen and they commands are on the package.json file. I recommend to use a contract first approach 👍🏽, why? because this reduces the risk and incomprehension between both teams (BE/FE). The contract is made first with all the types and services. With this, we can make our tests more accurate and reflecting the most what we will have on the prod environment

Assets

This folder contain all the assets (images, icons and css files) globally used like for the components, layouts, etc.

Core

The core folder inside the src folder is where we place all the general types/interfaces we used almost everywhere and that our app depend on; classes that defined the shape of our models(Entity), our errors and more.

Router

The router folder inside the src folder is the folder where our project routes are defined. In Vue.js, we use vue-router

Services

The Services folder inside the src folder is the one containing our services.

• apis: this folder contain our generated services from the contract(specifications)
• user: this folder is the one related to the users of our app containing entities, errors related to the user. (It can be Person, Client, Prospect depending on the business language)
• utils: is the folder containing the utils used by our entities to manage the business logic

Utils

The utils folder inside the src folder is the one containing all our utilities (text utilities, date utilities, etc.)

Modules

This folder contains all our modules depending on the fragmentation made by your team. There are commons folders

• common: this contains what is common among our modules (components, composables, directives, layouts). Inside our components we can have the form folder which contains all the custom inputs widely used.
• layouts: this one contain the base layouts
• i18n.json: this file contains the base internationalization where we place all the commons on widely used translations
• user: this is an example of module. Each one contains its components, views, stores, icons and also its internationalization file

Each module will contain its own __tests__ folder where we place all our units tests (src/modules/users/components/__tests__). Don't worry these files are excluded during the build.😮‍💨

Workflows

Prerequisites

Basic knowledge about yaml file and workflow using GitHub Action Workflow syntax for GitHub Actions. For the rest I will provide a link for each subject which could be useful for your own understanding throughout the explanation.

Here are the documentation about each workflow:

• Continuous integration
• Generate coverage
• Continuous deployment
• Release
• commitizen

Be a commitizen 💆

Commitizen is a nice utils to setup the commit template for your project. When you commit with Commitizen, you'll be prompted to fill out any required commit fields at commit time. No more waiting until later for a git commit hook to run and reject your commit (though that can still be helpful). No more digging through CONTRIBUTING.md to find what the preferred format is. Get instant feedback on your commit message formatting and be prompted for required fields.

Husky is a tool that allows us to easily wrangle Git hooks and run the scripts we want at those stages.

There are also some alternative to commitizen like commitlint, etc. It's up to you to choose, remove and customize

Steps before starting using

Init a project

There are some few steps you need to follow:

1. You can fork this repository

2. Make this repository a template. You can see how by reading this Creating a template repository

3. Now you can use this as your template for all your future vue project by referring to this github documentation about Creating a repository from a template

4. Once create, clone this repo on your local machine and install dependencies using npm ci command

5. To make the husky file executable, run the following command in your project's root directory:

   chmod 700 .husky/_/*

6. Delete all unnecessary .md files in the .github/workflows's folder and also the SERVER_CONFIG.md in your root project. Don't forget to model the README.md to correspond to your project🤭

7. To make a commit after a work, you can just type git commit in your console and commitizen will guide you.

8. Congratulation 🎉🥳. Now you can develop your amazing project.💪🏻

Some precision

There are some files you may not understand why they are presents in the project but don't, here, i will give you a precision about how to use them. Let's start

• env.d.ts this file is use for developer experience when developing the project and reduce error when using a environment variable. Interesting 🤭 isn't it? This helps you to have auto completion when dealing with environment variables. To use it, you will need to declare the variable inside the corresponding file either .env.development, env.staging or .env.production but most of the time, you will declare the same variable on all these files because if it is used in the dev env, it will probably be used in the other one. After the declaration in those files, make the same on the env.d.ts file inside the ImportMetaEnv interface. Now when you will need to use this variable just type import.meta.env. and you will see the magic completion 🌠. Don't forget to start your env variable name with VITE_. Want to know why and also more about environment variable in vite? You can read this article about Env Variables and Modes

• There are also the modes in vite. To be less talkative, this is like the your different environment (dev, test or staging and production). You can see in the vite.config.ts file this config

  build: {
    outDir: mode === "staging" ? "dist-staging" : "dist";
  }

This is there to differentiate the build output of these environments. We will have the dist-staging only on the test or staging environment. Leant more by reading about Env Variables and Modes

• We also created some alias for different section of the project

     resolve: {
           alias: {
           "@": fileURLToPath(new URL("./src", import.meta.url)),
           "@core": fileURLToPath(new URL("./src/core", import.meta.url)),
           "@modules": fileURLToPath(new URL("./src/modules", import.meta.url)),
           "@utils": fileURLToPath(new URL("./src/utils", import.meta.url)),
           "@services": fileURLToPath(new URL("./src/services", import.meta.url)),
           "@assets": fileURLToPath(new URL("./src/assets", import.meta.url))
        }
     },

This is an advantage for our eyes when importing something from a folder far and also helps use to directly know where the file we are importing come from. You can create you own if you desire. Don't know how? Read this answer on stackOverflow about How to set multiple aliases in vite

• When starting your project, you may want to change the test threshold to a reasonable but efficient one for the project. This is possible, you just need to change this in the vitest.config.ts file. Here is an example:

     thresholds: {
        lines: 84,
         branches: 84,
         functions: 84,
         statements: 84,
     },

You can read more about it on this vitest coverage.

Note

In modern project, we often setup different environments and one of them is the test or staging environment. The advice i can give to you to reduce the cost is to use a free server for frontend test like Vercel or Netlify just for the test and when everything goes well, deploy it to your own server maybe using the config i provide on the next section. But don't forget that if your frontend use an api, the api url must be set on the frontend side before starting using it. And also your api need to be deployed.

Apache server

• Apache server configuration

Useful packages can helps in your dev journey

• Dayjs: is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times for modern browsers with a largely Moment.js-compatible API.
• UUID Generator: this may not be a package, but it is useful when testing.

Other

Want a place to find link toward resources in dev, visit this repos Dev-and-it-resource.

Please if this has helped you a bit, add a start. If not, please give me a feed back on this discussion