mirror of
https://github.com/IT4Change/boilerplate-frontend.git
synced 2025-12-13 07:35:53 +00:00
54 lines
20 KiB
HTML
54 lines
20 KiB
HTML
<!doctype html>
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="utf-8" />
|
|
<meta name="viewport" content="width=device-width,initial-scale=1" />
|
|
<meta name="generator" content="VuePress 2.0.0-rc.14" />
|
|
<style>
|
|
:root {
|
|
--c-bg: #fff;
|
|
}
|
|
|
|
html.dark {
|
|
--c-bg: #22272e;
|
|
}
|
|
|
|
html,
|
|
body {
|
|
background-color: var(--c-bg);
|
|
}
|
|
</style>
|
|
<script>
|
|
const userMode = localStorage.getItem('vuepress-color-scheme')
|
|
const systemDarkMode =
|
|
window.matchMedia &&
|
|
window.matchMedia('(prefers-color-scheme: dark)').matches
|
|
if (userMode === 'dark' || (userMode !== 'light' && systemDarkMode)) {
|
|
document.documentElement.classList.toggle('dark', true)
|
|
}
|
|
</script>
|
|
<title>boilerplate-frontend | IT4C Frontend Boilerplate Documentation</title><meta name="description" content="IT4C Frontend Boilerplate Documentation">
|
|
<link rel="preload" href="/boilerplate-frontend/assets/style-BDZmSSuf.css" as="style"><link rel="stylesheet" href="/boilerplate-frontend/assets/style-BDZmSSuf.css">
|
|
<link rel="modulepreload" href="/boilerplate-frontend/assets/app-CnpfAwgF.js"><link rel="modulepreload" href="/boilerplate-frontend/assets/index.html-CanOZARV.js">
|
|
<link rel="prefetch" href="/boilerplate-frontend/assets/LICENSE.html-DlHRjj0o.js" as="script"><link rel="prefetch" href="/boilerplate-frontend/assets/404.html-Do_4XBj0.js" as="script">
|
|
</head>
|
|
<body>
|
|
<div id="app"><!--[--><div class="vp-theme-container external-link-icon"><!--[--><header class="vp-navbar"><div class="vp-toggle-sidebar-button" title="toggle sidebar" aria-expanded="false" role="button" tabindex="0"><div class="icon" aria-hidden="true"><span></span><span></span><span></span></div></div><span><a class="route-link" href="/boilerplate-frontend/"><!----><span class="vp-site-name" aria-hidden="true">IT4C Frontend Boilerplate Documentation</span></a></span><div class="vp-navbar-items-wrapper" style=""><!--[--><!--]--><!----><!--[--><!--]--><button class="vp-toggle-color-mode-button" title="toggle color mode"><svg class="light-icon" viewbox="0 0 32 32" style=""><path d="M16 12.005a4 4 0 1 1-4 4a4.005 4.005 0 0 1 4-4m0-2a6 6 0 1 0 6 6a6 6 0 0 0-6-6z" fill="currentColor"></path><path d="M5.394 6.813l1.414-1.415l3.506 3.506L8.9 10.318z" fill="currentColor"></path><path d="M2 15.005h5v2H2z" fill="currentColor"></path><path d="M5.394 25.197L8.9 21.691l1.414 1.415l-3.506 3.505z" fill="currentColor"></path><path d="M15 25.005h2v5h-2z" fill="currentColor"></path><path d="M21.687 23.106l1.414-1.415l3.506 3.506l-1.414 1.414z" fill="currentColor"></path><path d="M25 15.005h5v2h-5z" fill="currentColor"></path><path d="M21.687 8.904l3.506-3.506l1.414 1.415l-3.506 3.505z" fill="currentColor"></path><path d="M15 2.005h2v5h-2z" fill="currentColor"></path></svg><svg class="dark-icon" viewbox="0 0 32 32" style="display:none;"><path d="M13.502 5.414a15.075 15.075 0 0 0 11.594 18.194a11.113 11.113 0 0 1-7.975 3.39c-.138 0-.278.005-.418 0a11.094 11.094 0 0 1-3.2-21.584M14.98 3a1.002 1.002 0 0 0-.175.016a13.096 13.096 0 0 0 1.825 25.981c.164.006.328 0 .49 0a13.072 13.072 0 0 0 10.703-5.555a1.01 1.01 0 0 0-.783-1.565A13.08 13.08 0 0 1 15.89 4.38A1.015 1.015 0 0 0 14.98 3z" fill="currentColor"></path></svg></button><!----></div></header><!--]--><div class="vp-sidebar-mask"></div><!--[--><aside class="vp-sidebar"><!----><!--[--><!--]--><ul class="vp-sidebar-items"><!--[--><li><p tabindex="0" class="vp-sidebar-item vp-sidebar-heading">boilerplate-frontend <!----></p><!----></li><!--]--></ul><!--[--><!--]--></aside><!--]--><!--[--><main class="vp-page"><!--[--><!--]--><div class="theme-default-content"><!--[--><!--]--><div><h1 id="boilerplate-frontend" tabindex="-1"><a class="header-anchor" href="#boilerplate-frontend"><span>boilerplate-frontend</span></a></h1><p><a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/nodejs->%3D20.5.0-blue" alt="nodejs"></a><a href="https://www.npmjs.com/package/npm" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/npm-latest-blue" alt="npm"></a><a href="https://www.docker.com/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/docker-latest-blue" alt="docker"></a><a href="https://jqlang.github.io/jq/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/jq-latest-blue" alt="jq"></a><a href="https://vuejs.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vue&label=vue&color=green" alt="vue"></a><a href="https://vike.dev/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vike&label=vike&color=green" alt="vike"></a><a href="https://vuetifyjs.com/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vuetify&label=vuetify&color=green" alt="vuetify"></a><a href="https://pinia.vuejs.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.pinia&label=pinia&color=green" alt="pinia"></a><a href="https://vue-i18n.intlify.dev/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies['vue-i18n']&label=vue-i18n&color=green" alt="vue-i18n"></a><a href="https://eslint.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.eslint&label=eslint&color=yellow" alt="eslint"></a><a href="https://remark.js.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies['remark-cli']&label=remark-cli&color=yellow" alt="remark-cli"></a><a href="https://stylelint.io/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.stylelint&label=stylelint&color=yellow" alt="stylelint"></a><a href="https://vitest.dev/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.vitest&label=vitest&color=yellow" alt="vitest"></a><a href="https://storybook.js.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.storybook&label=storybook&color=orange" alt="storybook"></a><a href="https://vuepress.vuejs.org/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.vuepress&label=vuepress&color=orange" alt="vuepress"></a><a href="https://www.chromatic.com/" target="_blank" rel="noopener noreferrer"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.chromatic&label=chromatic&color=orange" alt="chromatic"></a></p><p>The IT4C Boilerplate for frontends</p><p><img src="/boilerplate-frontend/assets/it4c-logo2-clean-bg_alpha-128x128-B_JxeTXp.png" alt=""></p><h2 id="requirements-technology" tabindex="-1"><a class="header-anchor" href="#requirements-technology"><span>Requirements & Technology</span></a></h2><p>To be able to build this project you need <code>nodejs</code>, <code>npm</code> and optional <code>docker</code> and <code>jq</code>.</p><p>The project uses <code>vite</code> as builder, <code>vike</code> to do the SSR. The design framework is <code>vuetify</code> which requires the frontend framework <code>vue3</code>. For localization <code>vue-i18n</code> is used; Session storage is handled with <code>pinia</code>.</p><p>Testing is done with <code>vitest</code> and code style is enforced with <code>eslint</code>, <code>remark-cli</code> and <code>stylelint</code>.</p><p>This projects utilizes <code>storybook</code> and <code>chromatic</code> to develop, document & test frontend components and <code>vuepress</code> for static documentation generation.</p><h2 id="commands" tabindex="-1"><a class="header-anchor" href="#commands"><span>Commands</span></a></h2><p>The following commands are available:</p><table><thead><tr><th>Command</th><th>Description</th></tr></thead><tbody><tr><td><code>npm install</code></td><td>Project setup</td></tr><tr><td><code>npm run build</code></td><td>Compiles and minifies for production</td></tr><tr><td><code>npm run server:prod</code></td><td>Runs productions server</td></tr><tr><td><strong>Develop</strong></td><td></td></tr><tr><td><code>npm run dev</code></td><td>Compiles and hot-reloads for development</td></tr><tr><td><code>npm run server:dev</code></td><td>Run development server</td></tr><tr><td><code>npm run server:prod:ts</code></td><td>Run production server without build (ts-node)</td></tr><tr><td><code>npm run server:build</code></td><td>Build Server into an executable cjs file</td></tr><tr><td><strong>Test</strong></td><td></td></tr><tr><td><code>npm run test:lint</code></td><td>Run all linters</td></tr><tr><td><code>npm run test:lint:eslint</code></td><td>Run linter eslint</td></tr><tr><td><code>npm run test:lint:locales</code></td><td>Run linter locales</td></tr><tr><td><code>npm run test:lint:remark</code></td><td>Run linter remark</td></tr><tr><td><code>npm run test:lint:style</code></td><td>Run linter stylelint</td></tr><tr><td><code>npm run test:unit</code></td><td>Run all unit tests and generate coverage report</td></tr><tr><td><code>npm run test:unit:update</code></td><td>Run unit tests, coverage and update snapshots</td></tr><tr><td><code>npm run test:unit:dev</code></td><td>Run all unit tests in watch mode</td></tr><tr><td><code>npm test</code></td><td>Run all tests & linters</td></tr><tr><td><strong>Storybook</strong></td><td></td></tr><tr><td><code>npm run storybook</code></td><td>Run Storybook</td></tr><tr><td><code>npm run storybook:build</code></td><td>Build static storybook</td></tr><tr><td><code>npm run storybook:test</code></td><td>Run tests against all storybook stories</td></tr><tr><td><strong>Documentation</strong></td><td></td></tr><tr><td><code>npm run docs:dev</code></td><td>Run Documentation in development mode</td></tr><tr><td><code>npm run docs:build</code></td><td>Build static documentation</td></tr><tr><td><strong>Chromatic</strong></td><td></td></tr><tr><td><code>npm run chromatic</code></td><td>Run Chromatic. See Chromatic section for details</td></tr><tr><td><strong>Maintenance</strong></td><td></td></tr><tr><td><code>npm run update</code></td><td>Check for updates</td></tr></tbody></table><h3 id="docker" tabindex="-1"><a class="header-anchor" href="#docker"><span>Docker</span></a></h3><p>Docker can be run in development mode utilizing <code>docker-compose.overwrite.yml</code>:</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">docker</span> compose up</span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><p>Docker can be run in production mode:</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">docker</span> compose <span class="token parameter variable">-f</span> docker-compose.yml up</span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="chromatic" tabindex="-1"><a class="header-anchor" href="#chromatic"><span>Chromatic</span></a></h3><p>In order to use the chromatic workflow you need to provide a <code>CHROMATIC_PROJECT_TOKEN</code> in the repository secrets.</p><p>If you want to run chromatic from the command line you either have to provide this variable as well</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token builtin class-name">export</span> <span class="token assign-left variable">CHROMATIC_PROJECT_TOKEN</span><span class="token operator">=</span><span class="token punctuation">..</span>.</span>
|
|
<span class="line"><span class="token function">npm</span> run chromatic</span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><p>or you have to append it via parameter:</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">npm</span> run chromatic -- --project-token<span class="token operator">=</span><span class="token punctuation">..</span>.</span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div></div></div><h3 id="update" tabindex="-1"><a class="header-anchor" href="#update"><span>Update</span></a></h3><p>You can get a list of packes to update by running <code>npm run update</code>.</p><p>Appending <code>-u </code> will also update the packages in the <code>package.json</code>. You have to run <code>npm install</code> again after.</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">npm</span> run update -- <span class="token parameter variable">-u</span></span>
|
|
<span class="line"><span class="token function">npm</span> <span class="token function">install</span></span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="endpoints" tabindex="-1"><a class="header-anchor" href="#endpoints"><span>Endpoints</span></a></h2><p>The following endpoints are provided given the right command is executed or all three if <code>docker compose</code> is used:</p><table><thead><tr><th>Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><a href="http://localhost:3000" target="_blank" rel="noopener noreferrer">http://localhost:3000</a></td><td>Web</td></tr><tr><td><a href="http://localhost:6006" target="_blank" rel="noopener noreferrer">http://localhost:6006</a></td><td>Storybook</td></tr><tr><td><a href="http://localhost:8080" target="_blank" rel="noopener noreferrer">http://localhost:8080</a></td><td>Documentation</td></tr></tbody></table><h2 id="how-to-use-as-part-of-a-project" tabindex="-1"><a class="header-anchor" href="#how-to-use-as-part-of-a-project"><span>How to use as part of a project</span></a></h2><p>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.</p><p>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.</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">git</span> remote <span class="token function">add</span> xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git</span>
|
|
<span class="line"><span class="token function">git</span> fetch xxx_boilerplate_frontend</span>
|
|
<span class="line"><span class="token function">git</span> merge <span class="token parameter variable">-s</span> ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master</span>
|
|
<span class="line"><span class="token function">git</span> read-tree <span class="token parameter variable">--prefix</span><span class="token operator">=</span>xxx/ <span class="token parameter variable">-u</span> xxx_boilerplate_frontend/master</span>
|
|
<span class="line"><span class="token function">git</span> commit <span class="token parameter variable">-m</span> <span class="token string">"Imported boilerplate_frontend as a subtree under xxx/."</span></span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>To update the subtree you can use</p><div class="language-bash line-numbers-mode" data-highlighter="prismjs" data-ext="sh" data-title="sh"><pre class="language-bash"><code><span class="line"><span class="token function">git</span> subtree pull <span class="token parameter variable">-P</span> xxx/ xxx_boilerplate_frontend master</span>
|
|
<span class="line"><span class="token function">git</span> commit <span class="token parameter variable">-m</span> <span class="token string">"Updated boilerplate_frontend in subtree under xxx/."</span></span>
|
|
<span class="line"></span></code></pre><div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0;"><div class="line-number"></div><div class="line-number"></div></div></div><p>Where <code>xxx</code> 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.</p><p>This mechanic was taken from this <a href="https://stackoverflow.com/questions/1683531/how-to-import-existing-git-repository-into-another/8396318#8396318" target="_blank" rel="noopener noreferrer">source</a></p><h2 id="known-problems" tabindex="-1"><a class="header-anchor" href="#known-problems"><span>Known Problems</span></a></h2><ul><li>[ ] <a href="https://github.com/vuetifyjs/vuetify/issues/18772" target="_blank" rel="noopener noreferrer">Image flicker</a></li><li>[ ] <a href="https://github.com/vuetifyjs/vuetify/issues/18773" target="_blank" rel="noopener noreferrer">Black Buttons</a></li></ul><h2 id="license" tabindex="-1"><a class="header-anchor" href="#license"><span>License</span></a></h2><p><a href="./LICENSE">Apache 2.0</a></p></div><!--[--><!--]--></div><footer class="vp-page-meta"><!----><div class="vp-meta-item git-info"><!----><!----></div></footer><!----><!--[--><!--]--></main><!--]--></div><!--[--><!----><!--]--><!--]--></div>
|
|
<script type="module" src="/boilerplate-frontend/assets/app-CnpfAwgF.js" defer></script>
|
|
</body>
|
|
</html>
|