tyler.durden/dashy
1
0
Fork 0
mirror of https://github.com/Lissy93/dashy.git synced 2025-04-08 17:06:18 +02:00
Code Issues Packages Projects Releases Wiki Activity
dashy/docs/developing/index.html

21 lines
50 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en" dir="ltr">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Docusaurus v2.0.0-beta.2">
<title data-react-helmet="true">Developing | Dashy</title><meta data-react-helmet="true" property="og:url" content="https://dashy.to/docs/developing"><meta data-react-helmet="true" name="docusaurus_locale" content="en"><meta data-react-helmet="true" name="docusaurus_version" content="current"><meta data-react-helmet="true" name="docusaurus_tag" content="docs-default-current"><meta data-react-helmet="true" property="og:title" content="Developing | Dashy"><meta data-react-helmet="true" name="description" content="This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture."><meta data-react-helmet="true" property="og:description" content="This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture."><link data-react-helmet="true" rel="shortcut icon" href="/img/favicon.ico"><link data-react-helmet="true" rel="canonical" href="https://dashy.to/docs/developing"><link data-react-helmet="true" rel="alternate" href="https://dashy.to/docs/developing" hreflang="en"><link data-react-helmet="true" rel="alternate" href="https://dashy.to/docs/developing" hreflang="x-default"><link rel="stylesheet" href="/assets/css/styles.33ea40b1.css">
<link rel="preload" href="/assets/js/runtime~main.ce955c9b.js" as="script">
<link rel="preload" href="/assets/js/main.7777a0ba.js" as="script">
</head>
<body>
<script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}()</script><div id="__docusaurus">
<div><a href="#main" class="skipToContent_1oUP">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><a class="navbar__brand" href="/"><img src="/img/dashy.png" alt="Dashy Logo" class="themedImage_1VuW themedImage--light_3UqQ navbar__logo"><img src="/img/dashy.png" alt="Dashy Logo" class="themedImage_1VuW themedImage--dark_hz6m navbar__logo"><b class="navbar__title">Dashy</b></a></div><div class="navbar__items navbar__items--right"><div class="react-toggle displayOnlyInLargeViewport_GrZ2 react-toggle--disabled"><div class="react-toggle-track" role="button" tabindex="-1"><div class="react-toggle-track-check"><span class="toggle_71bT">🌜</span></div><div class="react-toggle-track-x"><span class="toggle_71bT">🌞</span></div><div class="react-toggle-thumb"></div></div><input type="checkbox" class="react-toggle-screenreader-only" aria-label="Switch between dark and light mode"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div><div class="navbar-sidebar"><div class="navbar-sidebar__brand"><a class="navbar__brand" href="/"><img src="/img/dashy.png" alt="Dashy Logo" class="themedImage_1VuW themedImage--light_3UqQ navbar__logo"><img src="/img/dashy.png" alt="Dashy Logo" class="themedImage_1VuW themedImage--dark_hz6m navbar__logo"><b class="navbar__title">Dashy</b></a></div><div class="navbar-sidebar__items"><div class="menu"><ul class="menu__list"></ul></div></div></div></nav><div class="main-wrapper docs-wrapper doc-page"><div class="docPage_31aa"><aside class="docSidebarContainer_3Kbt"><div class="sidebar_15mo"><nav class="menu menu--responsive thin-scrollbar menu_Bmed menuWithAnnouncementBar_2WvA" aria-label="Sidebar navigation"><button aria-label="Open menu" aria-haspopup="true" class="button button--secondary button--sm menu__button" type="button"><svg class="sidebarMenuIcon_fgN0" width="24" height="24" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><ul class="menu__list"><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Running Dashy</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/quick-start">Quick Start</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/deployment">Deployment</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/configuring">Configuring</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/management">Management</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/troubleshooting">Troubleshooting</a></li></ul></li><li class="menu__list-item"><a class="menu__link menu__link--sublist menu__link--active" href="#!">Community</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/showcase">User Showcase</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing">Contributing</a></li><li class="menu__list-item"><a aria-current="page" class="menu__link menu__link--active active" tabindex="0" href="/docs/developing">Developing</a></li><li class="menu__list-item"><a class="menu__link" tabindex="0" href="/docs/development-guides">Development Guides</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Feature Docs</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/icons">Icons</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/theming">Theming</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/status-indicators">Status Indicators</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/authentication">Authentication</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/searching">Keyboard Shortcuts</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/alternate-views">Alternate Views &amp; Opening Methods</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/multi-language-support">Internationalization</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/backup-restore">Cloud Backup and Restore</a></li></ul></li><li class="menu__list-item menu__list-item--collapsed"><a class="menu__link menu__link--sublist" href="#!">Misc</a><ul class="menu__list"><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/privacy">Privacy &amp; Security</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/changelog">Changelog</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/license">license</a></li><li class="menu__list-item"><a class="menu__link" tabindex="-1" href="/docs/code-of-conduct">Contributor Covenant Code of Conduct</a></li></ul></li></ul></nav></div></aside><main class="docMainContainer_3ufF"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_3FnS"><div class="docItemContainer_33ec"><article><div class="markdown"><header><h1 class="h1Heading_27L5">Developing</h1></header><p>This article outlines how to get Dashy running in a development environment, and outlines the basics of the architecture.
If you&#x27;re adding new features, you may want to check out the <a href="/docs/development-guides">Development Guides</a> docs, for tutorials covering basic tasks.</p><ul><li><a href="#setting-up-the-dev-environment">Setting up the Development Environment</a></li><li><a href="#resources-for-beginners">Resources for Beginners</a></li><li><a href="#style-guide">Style Guide</a></li><li><a href="#frontend-components">Frontend Components</a></li><li><a href="#directory-structure">Project Structure</a></li><li><a href="#dependencies-and-packages">Dependencies and Packages</a></li></ul><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="setting-up-the-dev-environment"></a>Setting up the Dev Environment<a class="hash-link" href="#setting-up-the-dev-environment" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="prerequisites"></a>Prerequisites<a class="hash-link" href="#prerequisites" title="Direct link to heading">#</a></h3><p>You will need either the latest or LTS version of <strong><a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer">Node.js</a></strong> to build and serve the application and <strong><a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a></strong> to easily fetch the code, and push any changes. If you plan on running or deploying the container, you&#x27;ll also need <strong><a href="https://docs.docker.com/get-docker/" target="_blank" rel="noopener noreferrer">Docker</a></strong>. To avoid any unexpected issues, ensure you&#x27;ve got at least <strong><a href="https://www.npmjs.com/get-npm" target="_blank" rel="noopener noreferrer">NPM</a></strong> V 7.5 or <strong><a href="https://classic.yarnpkg.com/en/docs/install/#windows-stable" target="_blank" rel="noopener noreferrer">Yarn</a></strong> 1.22 (you may find <a href="https://github.com/nvm-sh/nvm" target="_blank" rel="noopener noreferrer">NVM</a> helpful for switching/ managing versions).</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="running-the-project"></a>Running the Project<a class="hash-link" href="#running-the-project" title="Direct link to heading">#</a></h3><ol><li>Get Code: <code>git clone https://github.com/Lissy93/dashy.git</code></li><li>Navigate into the directory: <code>cd dashy</code></li><li>Install dependencies: <code>yarn</code></li><li>Start dev server: <code>yarn dev</code></li></ol><p>Dashy should now be being served on http://localhost:8080/. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="project-commands"></a>Project Commands<a class="hash-link" href="#project-commands" title="Direct link to heading">#</a></h3><ul><li><code>yarn dev</code> - Starts the development server with hot reloading</li><li><code>yarn build</code> - Builds the project for production, and outputs it into <code>./dist</code></li><li><code>yarn start</code> - Starts a web server, and serves up the production site from <code>./dist</code></li><li><code>yarn validate-config</code> - Parses and validates your <code>conf.yml</code> against Dashy&#x27;s schema</li><li><code>yarn lint</code> - Lints code to ensure it follows a consistent, neat style</li><li><code>yarn test</code> - Runs tests, and outputs results</li></ul><p>There is also:</p><ul><li><code>yarn build-and-start</code> will run <code>yarn build</code> and <code>yarn start</code></li><li><code>yarn build-watch</code> will output contents to <code>./dist</code> and recompile when anything in <code>./src</code> is modified, you can then use either <code>yarn start</code> or your own server, to have a production environment that watches for changes.</li></ul><p>Using the Vue CLI:</p><ul><li>The app is build with Vue, and uses the <a href="https://cli.vuejs.org/guide/cli-service.html" target="_blank" rel="noopener noreferrer">Vue-CLI Service</a> for basic commands.</li><li>If you have <a href="https://github.com/npm/npx" target="_blank" rel="noopener noreferrer">NPX</a> installed, then you can invoke the Vue CLI binary using <code>npx vue-cli-service [command]</code></li><li>Vue also has a GUI environment that can be used for basic project management, and may be useful for beginners, this can be started by running <code>vue ui</code>, and opening up <code>http://localhost:8000</code></li></ul><p>Note:</p><ul><li>If you are using NPM, replace <code>yarn</code> with <code>npm run</code></li><li>If you are using Docker, precede each command with <code>docker exec -it [container-id]</code>. Container ID can be found by running <code>docker ps</code></li></ul><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="environmental-variables"></a>Environmental Variables<a class="hash-link" href="#environmental-variables" title="Direct link to heading">#</a></h3><p>All environmental variables are optional. Currently there are not many environmental variables used, as most of the user preferences are stored under <code>appConfig</code> in the <code>conf.yml</code> file.</p><p>You can set variables within your local development environment using a <code>.env</code> file.</p><p>Any environmental variables used by the frontend are preceded with <code>VUE_APP_</code>. Vue will merge the contents of your <code>.env</code> file into the app in a similar way to the <a href="https://github.com/motdotla/dotenv" target="_blank" rel="noopener noreferrer">&#x27;dotenv&#x27;</a> package, where any variables that you set on your system will always take preference over the contents of any <code>.env</code> file.</p><ul><li><code>PORT</code> - The port in which the application will run (defaults to <code>4000</code> for the Node.js server, and <code>80</code> within the Docker container)</li><li><code>NODE_ENV</code> - Which environment to use, either <code>production</code>, <code>development</code> or <code>test</code></li><li><code>VUE_APP_DOMAIN</code> - The URL where Dashy is going to be accessible from. This should include the protocol, hostname and (if not 80 or 443), then the port too, e.g. <code>https://localhost:3000</code>, <code>http://192.168.1.2:4002</code> or <code>https://dashy.mydomain.com</code></li></ul><p>If you do add new variables, ensure that there is always a fallback (define it in <a href="https://github.com/Lissy93/dashy/blob/master/src/utils/defaults.js" target="_blank" rel="noopener noreferrer"><code>defaults.js</code></a>), so as to not cause breaking changes. Don&#x27;t commit your <code>.env</code> file to git, but instead take a few moments to document what you&#x27;ve added under the appropriate section. Try and follow the concepts outlined in the <a href="https://12factor.net/config" target="_blank" rel="noopener noreferrer">12 factor app</a>.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="environment-modes"></a>Environment Modes<a class="hash-link" href="#environment-modes" title="Direct link to heading">#</a></h3><p>You can set the environment using the <code>NODE_ENV</code> variable.
The correct environment will be selected based on the script you run by default
The following environments are supported.</p><ul><li><code>production</code></li><li><code>development</code></li><li><code>test</code></li></ul><p>For more info, see <a href="https://cli.vuejs.org/guide/mode-and-env.html#modes" target="_blank" rel="noopener noreferrer">Vue CLI Environment Modes</a>.</p><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="git-strategy"></a>Git Strategy<a class="hash-link" href="#git-strategy" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="git-flow"></a>Git Flow<a class="hash-link" href="#git-flow" title="Direct link to heading">#</a></h3><p>Like most Git repos, we are following the <a href="https://guides.github.com/introduction/flow" target="_blank" rel="noopener noreferrer">Github Flow</a> standard.</p><ol><li>Create a branch (or fork if you don&#x27;d have write acces)</li><li>Code some awesome stuff, then add and commit your changes</li><li>Create a Pull Request, complete the checklist and ensure the build succeeds</li><li>Follow up with any reviews on your code</li><li>Merge 🎉</li></ol><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="git-branch-naming"></a>Git Branch Naming<a class="hash-link" href="#git-branch-naming" title="Direct link to heading">#</a></h3><p>The format of your branch name should be something similar to: <code>[TYPE]/[TICKET]_[TITLE]</code>
For example, <code>FEATURE/420_Awesome-feature</code> or <code>FIX/690_login-server-error</code></p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="commit-emojis"></a>Commit Emojis<a class="hash-link" href="#commit-emojis" title="Direct link to heading">#</a></h3><p>Using a single emoji at the start of each commit message, to indicate the type task, makes the commit ledger easier to understand, plus it looks cool.</p><ul><li>🎨 <code>:art:</code> - Improve structure / format of the code.</li><li>⚡️ <code>:zap:</code> - Improve performance.</li><li>🔥 <code>:fire:</code> - Remove code or files.</li><li>🐛 <code>:bug:</code> - Fix a bug.</li><li>🚑️ <code>:ambulance:</code> - Critical hotfix</li><li>✨ <code>:sparkles:</code> - Introduce new features.</li><li>📝 <code>:memo:</code> - Add or update documentation.</li><li>🚀 <code>:rocket:</code> - Deploy stuff.</li><li>💄 <code>:lipstick:</code> - Add or update the UI and style files.</li><li>🎉 <code>:tada:</code> - Begin a project.</li><li>✅ <code>:white_check_mark:</code> - Add, update, or pass tests.</li><li>🔒️ <code>:lock:</code> - Fix security issues.</li><li>🔖 <code>:bookmark:</code> - Make a Release or Version tag.</li><li>🚨 <code>:rotating_light:</code> - Fix compiler / linter warnings.</li><li>🚧 <code>:construction:</code> - Work in progress.</li><li>⬆️ <code>:arrow_up:</code> - Upgrade dependencies.</li><li>👷 <code>:construction_worker:</code> - Add or update CI build system.</li><li>♻️ <code>:recycle:</code> - Refactor code.</li><li>🩹 <code>:adhesive_bandage:</code> - Simple fix for a non-critical issue.</li><li>🔧 <code>:wrench:</code> - Add or update configuration files.</li><li>🍱 <code>:bento:</code> - Add or update assets.</li><li>🗃️ <code>:card_file_box:</code> - Perform database schema related changes.</li><li>✏️ <code>:pencil2:</code> - Fix typos.</li><li>🌐 <code>:globe_with_meridians:</code> - Internationalization and translations.</li></ul><p>For a full list of options, see <a href="https://gitmoji.dev/" target="_blank" rel="noopener noreferrer">gitmoji.dev</a></p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="pr-guidelines"></a>PR Guidelines<a class="hash-link" href="#pr-guidelines" title="Direct link to heading">#</a></h3><p>Once you&#x27;ve made your changes, and pushed them to your fork or branch, you&#x27;re ready to open a pull request!</p><p>For a pull request to be merged, it must:</p><ul><li>Must be backwards compatible</li><li>The build, lint and tests (run by GH actions) must pass</li><li>There must not be any merge conflicts</li></ul><p>When you submit your PR, include the required info, by filling out the PR template. Including:</p><ul><li>A brief description of your changes</li><li>The issue, ticket or discussion number (if applicable)</li><li>For UI relate updates include a screenshot</li><li>If any dependencies were added, explain why it was needed, state the cost associated, and confirm it does not introduce any security issues</li><li>Finally, check the checkboxes, to confirm that the standards are met, and hit submit!</li></ul><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="resources-for-beginners"></a>Resources for Beginners<a class="hash-link" href="#resources-for-beginners" title="Direct link to heading">#</a></h2><p>New to Web Development? Glad you&#x27;re here! Dashy is a pretty simple app, so it should make a good candidate for your first PR. Presuming that you already have a basic knowledge of JavaScript, the following articles should point you in the right direction for getting up to speed with the technologies used in this project:</p><ul><li><a href="https://v3.vuejs.org/guide/introduction.html" target="_blank" rel="noopener noreferrer">Introduction to Vue.js</a></li><li><a href="https://www.taniarascia.com/getting-started-with-vue/" target="_blank" rel="noopener noreferrer">Vue.js Walkthrough</a></li><li><a href="https://blog.logrocket.com/the-definitive-guide-to-scss/" target="_blank" rel="noopener noreferrer">Definitive guide to SCSS</a></li><li><a href="https://docker-curriculum.com/" target="_blank" rel="noopener noreferrer">Complete beginners guide to Docker</a></li><li><a href="https://training.play-with-docker.com/" target="_blank" rel="noopener noreferrer">Docker Classroom - Interactive Tutorials</a></li><li><a href="https://www.freecodecamp.org/news/learn-typescript-in-5-minutes-13eda868daeb/" target="_blank" rel="noopener noreferrer">Quick start TypeScript guide</a></li><li><a href="https://www.typescripttutorial.net/" target="_blank" rel="noopener noreferrer">Complete TypeScript tutorial series</a></li><li><a href="https://blog.logrocket.com/vue-typescript-tutorial-examples/" target="_blank" rel="noopener noreferrer">Using TypeScript with Vue.js</a></li><li><a href="http://git-cheatsheet.com/" target="_blank" rel="noopener noreferrer">Git cheat sheet</a></li><li><a href="https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/" target="_blank" rel="noopener noreferrer">Basics of using NPM</a></li></ul><p>As well as Node, Git and Docker- you&#x27;ll also need an IDE (e.g. <a href="https://code.visualstudio.com/" target="_blank" rel="noopener noreferrer">VS Code</a> or <a href="https://www.vim.org/" target="_blank" rel="noopener noreferrer">Vim</a>) and a terminal (Windows users may find <a href="https://docs.microsoft.com/en-us/windows/wsl/" target="_blank" rel="noopener noreferrer">WSL</a> more convenient). </p><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="style-guide"></a>Style Guide<a class="hash-link" href="#style-guide" title="Direct link to heading">#</a></h2><p>Linting is done using <a href="https://eslint.org/" target="_blank" rel="noopener noreferrer">ESLint</a>, and using the <a href="https://github.com/vuejs/eslint-config-standard" target="_blank" rel="noopener noreferrer">Vue.js Styleguide</a>, which is very similar to the <a href="https://github.com/airbnb/javascript" target="_blank" rel="noopener noreferrer">AirBnB Stylguide</a>. You can run <code>yarn lint</code> to report and fix issues. While the dev server is running, issues will be reported to the console automatically, and any lint errors will trigger the build to fail. Note that all lint checks must pass before any PR can be merged. Linting is also run as a git pre-commit hook</p><p>The most significant things to note are:</p><ul><li>Indentation should be done with two spaces</li><li>Strings should use single quotes</li><li>All statements must end in a semi-colon</li><li>The final element in all objects must be preceded with a comma</li><li>Maximum line length is 100</li><li>There must be exactly one blank line between sections, before function names, and at the end of the file</li><li>With conditionals, put else on the same line as your if block’s closing brace</li><li>All multiline blocks must use braces</li><li>Avoid console statements in the frontend</li></ul><p>Styleguides:</p><ul><li>Vue: <a href="https://vuejs.org/v2/style-guide/" target="_blank" rel="noopener noreferrer">Vue styleguide</a></li><li>JavaScript: <a href="https://github.com/airbnb/javascript" target="_blank" rel="noopener noreferrer">github.com/airbnb/javascript</a> </li></ul><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="application-structure"></a>Application Structure<a class="hash-link" href="#application-structure" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="directory-structure"></a>Directory Structure<a class="hash-link" href="#directory-structure" title="Direct link to heading">#</a></h3><h4><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="files-in-the-root-"></a>Files in the Root: <code>./</code><a class="hash-link" href="#files-in-the-root-" title="Direct link to heading">#</a></h4><div class="codeBlockContainer_K1bP"><div class="codeBlockContent_hGly"><pre tabindex="0" class="prism-code language-undefined codeBlock_23N8 thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_39YC"><span class="token-line" style="color:#393A34"><span class="token plain">╮</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── package.json # Project meta-data, dependencies and paths to scripts</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── src/ # Project front-end source code</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── server.js # A Node.js server to serve up the /dist directory</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── vue.config.js # Vue.js configuration</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── Dockerfile # The blueprint for building the Docker container</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── docker-compose.yml # A Docker run command</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── .env # Location for any environmental variables</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── yarn.lock # Auto-generated list of current packages and version numbers</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── docs/ # Markdown documentation</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── README.md # Readme, basic info for getting started</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── LICENSE.md # License for use</span></span><span class="token-line" style="color:#393A34"><span class="token plain">╯</span></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_Ue-o clean-btn">Copy</button></div></div><h4><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="frontend-source-src"></a>Frontend Source: <code>./src/</code><a class="hash-link" href="#frontend-source-src" title="Direct link to heading">#</a></h4><div class="codeBlockContainer_K1bP"><div class="codeBlockContent_hGly"><pre tabindex="0" class="prism-code language-undefined codeBlock_23N8 thin-scrollbar" style="color:#393A34;background-color:#f6f8fa"><code class="codeBlockLines_39YC"><span class="token-line" style="color:#393A34"><span class="token plain">./src</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── App.vue # Vue.js starting file</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── assets # Static non-compiled assets</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── fonts # .ttf font files</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── locales # All app text, each language in a separate JSON file</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ╰── interface-icons # SVG icons used in the app </span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── components # All front-end Vue web components</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── Configuration # Components relating to the user config pop-up</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── AppInfoModal.vue # A modal showing core app info, like version, language, etc</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── CloudBackupRestore.vue # Form where the user manages cloud sync options</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── ConfigContainer.vue # Main container, wrapping all other config components</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── CustomCss.vue # Form where the user can input custom CSS</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── EditSiteMeta.vue # Form where the user can edit site meta data</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── JsonEditor.vue # JSON editor, where the user can modify the main config file</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ╰── RebuildApp.vue # A component allowing user to trigger a rebuild through the UI</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── FormElements # Basic form elements used throughout the app</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Button.vue # Standard button component</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ╰── Input.vue # Standard text field input component</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── LinkItems # Components for Sections and Link Items</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Collapsable.vue # The collapsible functionality of sections</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── ContextMenu.vue # The right-click menu, for showing Item opening methods and info</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── IframeModal.vue # Pop-up iframe modal, for viewing websites within the app</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Item.vue # Main link item, which is displayed within an item group</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── ItemGroup.vue # Item group is a section containing icons</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── ItemIcon.vue # The icon used by both items and sections</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method </span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── PageStrcture # Components relating the main structure of the page</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Footer.vue # Footer, visible at the bottom of all pages</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Header.vue # Header, visible at the top of pages, and includes title and nav</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── LoadingScreen.vue # Splash screen shown on first load</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ├── Nav.vue # Navigation bar, includes a list of links</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ╰── Settings # Components relating to the quick-settings, in the top-right</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── AuthButtons.vue # Logout button and other app info</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── KeyboardShortcutInfo.vue# Small pop-up displaying the available keyboard shortcuts</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── LanguageSwitcher.vue # Dropdown in a modal for changing app language</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── LayoutSelector.vue # Set of buttons, letting the user select their desired layout</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── SearchBar.vue # The input field in the header, used for searching the app</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── SettingsContainer.vue # Container that wraps all the quick-settings components</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ╰── ThemeSelector.vue # Drop-down menu enabling the user to select and change themes</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── main.js # Main front-end entry point</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── registerServiceWorker.js # Registers and manages service workers, for PWA apps</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── router.js # Defines all available application routes</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── styles # Directory of all globally used common SCSS styles</span></span><span class="token-line" style="color:#393A34"><span class="token plain">├── utils # Directory of re-used helper functions</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ArrowKeyNavigation.js # Functionality for arrow-key navigation</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── Auth.js # Handles all authentication related actions</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ClickOutside.js # A directive for detecting click, used to hide dropdown, modal or context menu</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ConfigAccumulator.js # Central place for managing and combining config</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ConfigHelpers.js # Helper functions for managing configuration</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── CloudBackup.js # Functionality for encrypting, processing and network calls</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ConfigSchema.json # The schema, used to validate the users conf.yml file</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ConfigValidator.js # A helper script that validates the config file against schema</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── defaults.js # Global constants and their default values</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── ErrorHandler.js # Helper function called when an error is returned</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ├── languages.js # Handles fetching, switching and validating languages</span></span><span class="token-line" style="color:#393A34"><span class="token plain">│ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes</span></span><span class="token-line" style="color:#393A34"><span class="token plain">╰── views # Directory of available pages, corresponding to available routes</span></span><span class="token-line" style="color:#393A34"><span class="token plain"> ├── Home.vue # The home page container</span></span><span class="token-line" style="color:#393A34"><span class="token plain"> ├── About.vue # About page</span></span><span class="token-line" style="color:#393A34"><span class="token plain"> ├── Login.vue # TAuthentication page</span></span><span class="token-line" style="color:#393A34"><span class="token plain"> ├── Minimal.vue # The minimal view</span></span><span class="token-line" style="color:#393A34"><span class="token plain"> ╰── Workspace.vue # The workspace view with apps in sidebar</span></span></code></pre><button type="button" aria-label="Copy code to clipboard" class="copyButton_Ue-o clean-btn">Copy</button></div></div><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="frontend-components"></a>Frontend Components<a class="hash-link" href="#frontend-components" title="Direct link to heading">#</a></h3><p>All frontend code is located in the <code>./src</code> directory, which is split into 5 sub-folders:</p><ul><li><strong>Components</strong> - All frontend web components are located here. Each component should have a distinct, well defined and simple task, and ideally should not be too long. The components directory is organised into a series of sub-directories, representing a specific area of the application<ul><li><strong>PageStrcture</strong> - Components relating to overall page structure (nav, footer, etc)</li><li>FormElements - Reusable form elements (button, input field, etc)</li><li>LinkItems - Components relating to Dashy&#x27;s sections and items (item group, item, item icon, etc)</li><li>Configuration - Components relating to Dashy&#x27;s configuration forms (cloud backup, JSON editor, etc)</li></ul></li><li><strong>Views</strong> - Each view directly corresponds to a route (defined in the router), and in effectively a page. They should have minimal logic, and just contain a few components</li><li><strong>Utils</strong> - These are helper functions, or logic that is used within the app does not include an UI elements</li><li><strong>Styles</strong> - Any SCSS that is used globally throughout that app, and is not specific to a single component goes here. This includes variables, color themes, typography settings, CSS reset and media queries</li><li><strong>Assets</strong> - Static assets that need to be bundled into the application, but do not require any manipulation go here. This includes interface icons and fonts</li></ul><p>The structure of the components directory is similar to that of the frontend application layout</p><p align="center"><img src="https://i.ibb.co/wJCt0Lq/dashy-page-structure.png" width="600"></p><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="development-tools"></a>Development Tools<a class="hash-link" href="#development-tools" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="performance---lighthouse"></a>Performance - Lighthouse<a class="hash-link" href="#performance---lighthouse" title="Direct link to heading">#</a></h3><p>The easiest method of checking performance is to use Chromium&#x27;s build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --&gt; Lighthouse and click on the &#x27;Generate Report&#x27; button at the bottom.</p><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="dependencies---bundlephobia"></a>Dependencies - BundlePhobia<a class="hash-link" href="#dependencies---bundlephobia" title="Direct link to heading">#</a></h3><p><a href="https://bundlephobia.com/" target="_blank" rel="noopener noreferrer">BundlePhobia</a> is a really useful app that lets you analyze the cost of adding any particular dependency to an application</p><hr><h2><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="notes"></a>Notes<a class="hash-link" href="#notes" title="Direct link to heading">#</a></h2><h3><a aria-hidden="true" tabindex="-1" class="anchor enhancedAnchor_2LWZ" id="known-warnings"></a>Known Warnings<a class="hash-link" href="#known-warnings" title="Direct link to heading">#</a></h3><p>When running the build command, several warnings appear. These are not errors, and do not affect the security or performance of the application. They will be addressed in a future update</p><p><code>WARN A new version of sass-loader is available. Please upgrade for best experience.</code> - Currently we&#x27;re using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI&#x27;s webpack configuration.</p><p><code>WARN asset size limit: The following asset(s) exceed the recommended size limit (244 KiB).</code> - For the PWA to support Windows 10, a splash screen asset is required, and is quite large. This throws a warning, however PWA assets are not loaded until needed, so shouldn&#x27;t have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.</p><p><code>glob-parent Security Alert</code> - This will be fixed soon. The version of glob-parent that is used by the latest version of Vue-CLI has a security issue associated with it. I am waiting on Vue to update their dependencies.</p></div><footer class="row docusaurus-mt-lg"><div class="col"><a href="https://github.com/Lissy93/dashy/edit/gh-pages/docs/docs/developing.md" target="_blank" rel="noreferrer noopener"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_2_ui" aria-hidden="true"><g><path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z"></path></g></svg>Edit this page</a></div><div class="col lastUpdated_3DPF"></div></footer></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages navigation"><div class="pagination-nav__item"><a class="pagination-nav__link" href="/docs/contributing"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">« Contributing</div></a></div><div class="pagination-nav__item pagination-nav__item--next"><a class="pagination-nav__link" href="/docs/development-guides"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Development Guides »</div></a></div></nav></div></div><div class="col col--3"><div class="tableOfContents_35-E thin-scrollbar"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#setting-up-the-dev-environment" class="table-of-contents__link">Setting up the Dev Environment</a><ul><li><a href="#prerequisites" class="table-of-contents__link">Prerequisites</a></li><li><a href="#running-the-project" class="table-of-contents__link">Running the Project</a></li><li><a href="#project-commands" class="table-of-contents__link">Project Commands</a></li><li><a href="#environmental-variables" class="table-of-contents__link">Environmental Variables</a></li><li><a href="#environment-modes" class="table-of-contents__link">Environment Modes</a></li></ul></li><li><a href="#git-strategy" class="table-of-contents__link">Git Strategy</a><ul><li><a href="#git-flow" class="table-of-contents__link">Git Flow</a></li><li><a href="#git-branch-naming" class="table-of-contents__link">Git Branch Naming</a></li><li><a href="#commit-emojis" class="table-of-contents__link">Commit Emojis</a></li><li><a href="#pr-guidelines" class="table-of-contents__link">PR Guidelines</a></li></ul></li><li><a href="#resources-for-beginners" class="table-of-contents__link">Resources for Beginners</a></li><li><a href="#style-guide" class="table-of-contents__link">Style Guide</a></li><li><a href="#application-structure" class="table-of-contents__link">Application Structure</a><ul><li><a href="#directory-structure" class="table-of-contents__link">Directory Structure</a></li><li><a href="#frontend-components" class="table-of-contents__link">Frontend Components</a></li></ul></li><li><a href="#development-tools" class="table-of-contents__link">Development Tools</a><ul><li><a href="#performance---lighthouse" class="table-of-contents__link">Performance - Lighthouse</a></li><li><a href="#dependencies---bundlephobia" class="table-of-contents__link">Dependencies - BundlePhobia</a></li></ul></li><li><a href="#notes" class="table-of-contents__link">Notes</a><ul><li><a href="#known-warnings" class="table-of-contents__link">Known Warnings</a></li></ul></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Intro</div><ul class="footer__items"><li class="footer__item"><a href="https://github.com/lissy93/dashy" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub</a></li><li class="footer__item"><a href="https://demo.dashy.to" target="_blank" rel="noopener noreferrer" class="footer__link-item">Live Demo</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/quick-start">Quick Start</a></li><li class="footer__item"><a class="footer__link-item" href="/docs">Documentation</a></li></ul></div><div class="col footer__col"><div class="footer__title">Setup Guide</div><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/deployment">Deploying</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/configuring">Configuring</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/management">Management</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/troubleshooting">Troubleshooting</a></li></ul></div><div class="col footer__col"><div class="footer__title">Feature Docs Pt 1</div><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/authentication">Authentication</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/alternate-views">Alternate Views</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/backup-restore">Backup &amp; Restore</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/icons">Icons</a></li></ul></div><div class="col footer__col"><div class="footer__title">Feature Docs Pt 2</div><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/multi-language-support">Language Switching</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/status-indicators">Status Indicators</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/searching">Searching &amp; Shortcuts</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/theming">Theming</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/developing">Developing</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/development-guides">Development Guides</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/contributing">Contributing</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/showcase">Showcase</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/credits">Credits</a></li></ul></div><div class="col footer__col"><div class="footer__title">Misc</div><ul class="footer__items"><li class="footer__item"><a class="footer__link-item" href="/docs/privacy">Privacy &amp; Security</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/license">License</a></li><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/LEGAL.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Legal</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/code-of-conduct">Code of Conduct</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/changelog">Changelog</a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright"><a href="https://dashy.to">Dashy</a> - The Self-Hosted Dashboard for your Homelab<br>License under <a href="https://github.com/Lissy93/dashy/blob/master/LICENSE">MIT</a>. Copyright © 2021 <a href="https://aliciasykes.com">Alicia Sykes</a></div></div></div></footer></div>
<script src="/assets/js/runtime~main.ce955c9b.js"></script>
<script src="/assets/js/main.7777a0ba.js"></script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink