Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cmggevolution/template-vue
A complete vue template for all cases
https://github.com/cmggevolution/template-vue
cypress docker eslint github-actions husky linux pinia prettier vite vitest vue3 vue3-ty vuejs
Last synced: 2 months ago
JSON representation
A complete vue template for all cases
- Host: GitHub
- URL: https://github.com/cmggevolution/template-vue
- Owner: CMGGEvolution
- Created: 2024-10-07T16:43:26.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2024-10-21T17:05:06.000Z (4 months ago)
- Last Synced: 2024-10-21T23:20:16.839Z (4 months ago)
- Topics: cypress, docker, eslint, github-actions, husky, linux, pinia, prettier, vite, vitest, vue3, vue3-ty, vuejs
- Language: Vue
- Homepage:
- Size: 114 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# template-vue
A complete vue template for a robust project.This includes link to different tools used.
[](http://commitizen.github.io/cz-cli/) [](https://sonarcloud.io/summary/new_code?id=CMGGEvolution_template-vue) [](https://sonarcloud.io/summary/new_code?id=CMGGEvolution_template-vue) [](https://sonarcloud.io/summary/new_code?id=CMGGEvolution_template-vue)  [](https://cloud.cypress.io/projects/frc51p/runs)
## Libraries used
- [Typescript](https://www.typescriptlang.org/)
- [Vue.js](https://vuejs.org/)
- [vue-router](https://router.vuejs.org/)
- [Pinia store](https://pinia.vuejs.org/)
- [vue-i18n](https://vue-i18n.intlify.dev/)
- [vue-test-utils](https://test-utils.vuejs.org/)
- [TailwindCss](https://tailwindcss.com/)
- [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen)
- [vitest](https://vitest.dev/)
- [vite](https://vite.dev/)
- [Cypress](https://www.cypress.io/)
- [husky](https://www.npmjs.com/package/husky)
- [eslint-config-epsvue](https://www.npmjs.com/package/eslint-config-epsvue). It combine [Eslint](https://eslint.org/), [Prettier](https://prettier.io/) and [Stylelint](https://www.npmjs.com/package/stylelint) and it is also customizable 😉
- [lint-staged](https://www.npmjs.com/package/lint-staged)
- [commitizen](https://github.com/commitizen/cz-cli): this is a nice utils for commit template 🤙
- [vuelidate](https://vuelidate-next.netlify.app/): 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](https://www.browserstack.com/guide/end-to-end-testing)
In our case, we used [Get started with cypress](https://docs.cypress.io/app/get-started/why-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](https://docs.github.com/en/actions/writing-workflows/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](.github/workflows/README-CI.md)
- [Generate coverage](.github/workflows/README-GC.md)
- [Continuous deployment](.github/workflows/README-DEPLOY.md)
- [Release](.github/workflows/README-RELEASE.md)
- [commitizen](https://github.com/commitizen/cz-cli)
## Be a commitizen 💆
[Commitizen](https://github.com/commitizen/cz-cli) 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](https://www.npmjs.com/package/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](https://github.com/conventional-changelog/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](https://docs.github.com/en/repositories/creating-and-managing-repositories/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](https://docs.github.com/en/repositories/creating-and-managing-repositories/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:
```bash
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](https://vite.dev/guide/env-and-mode)
- There are also the [modes](https://vite.dev/guide/env-and-mode#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
```javascript
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](https://vite.dev/guide/env-and-mode#mode)
- We also created some alias for different section of the project
```javascript
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](https://stackoverflow.com/questions/75201705/how-to-set-multiple-aliases-in-vite-react#75201776)
- 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:
```javascript
thresholds: {
lines: 84,
branches: 84,
functions: 84,
statements: 84,
},
```
You can read more about it on this [vitest coverage](https://v0.vitest.dev/config/#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](https://vercel.com/) or [Netlify](https://www.netlify.com/) 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](./SERVER_CONFIG.md)
## Useful packages can helps in your dev journey
- [Dayjs](https://day.js.org/): 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](https://www.uuidgenerator.net/): 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](https://github.com/masterivanic/Dev-and-it-ressource).
Please if this has helped you a bit, add a start. If not, please give me a feed back on [this discussion](https://github.com/CMGGEvolution/template-vue/discussions/16)