boilerplate-frontend
The IT4C Boilerplate for frontends
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker and jq.
The project uses vite as builder, vike to do the SSR. The design framework is vuetify which requires the frontend framework vue3. For localization vue-i18n is used; Session storage is handled with pinia.
Testing is done with vitest and code style is enforced with eslint, remark-cli and stylelint.
This projects utilizes storybook and chromatic to develop, document & test frontend components and vuepress for static documentation generation.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run server:prod | Runs productions server |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
npm run server:dev | Run development server |
npm run server:prod:ts | Run production server without build (ts-node) |
npm run server:build | Build Server into an executable cjs file |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:locales | Run linter locales |
npm run test:lint:remark | Run linter remark |
npm run test:lint:style | Run linter stylelint |
npm run test:unit | Run all unit tests and generate coverage report |
npm run test:unit:update | Run unit tests, coverage and update snapshots |
npm run test:unit:dev | Run all unit tests in watch mode |
npm test | Run all tests & linters |
| Storybook | |
npm run storybook | Run Storybook |
npm run storybook:build | Build static storybook |
npm run storybook:test | Run tests against all storybook stories |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Chromatic | |
npm run chromatic | Run Chromatic. See Chromatic section for details |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
Docker can be run in production mode:
docker compose -f docker-compose.yml up
Chromatic
In order to use the chromatic workflow you need to provide a CHROMATIC_PROJECT_TOKEN in the repository secrets.
If you want to run chromatic from the command line you either have to provide this variable as well
export CHROMATIC_PROJECT_TOKEN=...
npm run chromatic
or you have to append it via parameter:
npm run chromatic -- --project-token=...
Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
npm install
Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
| Endpoint | Description |
|---|---|
| http://localhost:3000 | Web |
| http://localhost:6006 | Storybook |
| http://localhost:8080 | Documentation |
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a backend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git
git fetch xxx_boilerplate_frontend
git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master
git read-tree --prefix=xxx/ -u xxx_boilerplate_frontend/master
git commit -m "Imported boilerplate_frontend as a subtree under xxx/."
To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_frontend master
git commit -m "Updated boilerplate_frontend in subtree under xxx/."
Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
This mechanic was taken from this source
Known Problems
- [ ] Image flicker
- [ ] Black Buttons