mirror of
https://github.com/Lissy93/dashy.git
synced 2026-03-18 18:51:30 +01:00
225 lines
No EOL
71 KiB
HTML
225 lines
No EOL
71 KiB
HTML
<!doctype html>
|
||
<html lang="en" dir="ltr" class="docs-wrapper plugin-docs plugin-id-default docs-version-current docs-doc-page docs-doc-id-developing" data-has-hydrated="false">
|
||
<head>
|
||
<meta charset="UTF-8">
|
||
<meta name="generator" content="Docusaurus v3.9.2">
|
||
<title data-rh="true">Developing | Dashy</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="keywords" content="dashy, dashboard, homelab, self-hosted, docker, homepage"><meta data-rh="true" property="og:type" content="website"><meta data-rh="true" property="og:url" content="https://dashy.to"><meta data-rh="true" property="og:image" content="https://dashy.to/img/dashy.png"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" name="twitter:title" content="Dashy — The Ultimate Homepage for your Homelab"><meta data-rh="true" name="twitter:description" content="Dashy is a self-hosted dashboard app for your homelab. Manage all your services, with status checks, widgets, themes and more."><meta data-rh="true" name="twitter:image" content="https://dashy.to/img/dashy.png"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Developing | Dashy"><meta data-rh="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-rh="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-rh="true" rel="icon" href="/img/favicon.ico"><link data-rh="true" rel="canonical" href="https://dashy.to/docs/developing"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/developing" hreflang="en"><link data-rh="true" rel="alternate" href="https://dashy.to/docs/developing" hreflang="x-default"><script data-rh="true" type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Developing","item":"https://dashy.to/docs/developing"}]}</script><link rel="preconnect" href="https://pixelflare.cc">
|
||
<link rel="preconnect" href="https://cdn.as93.net">
|
||
<link rel="dns-prefetch" href="https://api.github.com">
|
||
<link rel="dns-prefetch" href="https://no-track.as93.net">
|
||
<script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","name":"Dashy","url":"https://dashy.to","description":"The Ultimate Homepage for your Homelab","publisher":{"@type":"Person","name":"Alicia Sykes","url":"https://aliciasykes.com"}}</script>
|
||
<link rel="manifest" href="/manifest.json">
|
||
<meta name="theme-color" content="#54bff7">
|
||
<script src="https://no-track.as93.net/js/script.js" defer="defer" data-domain="dashy.to"></script><link rel="stylesheet" href="/assets/css/styles.df43b345.css">
|
||
<script src="/assets/js/runtime~main.fbc78bd5.js" defer="defer"></script>
|
||
<script src="/assets/js/main.3db68a15.js" defer="defer"></script>
|
||
</head>
|
||
<body class="navigation-with-keyboard">
|
||
<svg style="display: none;"><defs>
|
||
<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"/></symbol>
|
||
</defs></svg>
|
||
<script>!function(){var t=function(){try{return new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}}()||function(){try{return window.localStorage.getItem("theme")}catch(t){}}();document.documentElement.setAttribute("data-theme",t||"dark"),document.documentElement.setAttribute("data-theme-choice",t||"dark")}(),function(){try{const c=new URLSearchParams(window.location.search).entries();for(var[t,e]of c)if(t.startsWith("docusaurus-data-")){var a=t.replace("docusaurus-data-","data-");document.documentElement.setAttribute(a,e)}}catch(t){}}()</script><div id="__docusaurus"><div class="banner_woPo"><a class="link_ecgS" title="View the changelog, to see what's new!" href="/updates">Dashy <!-- -->V3.1.5<!-- --> is now live 🚀</a><a class="link2_y3x6" title="View the changelog, to see what's new!" href="/updates">See what's new…</a><button class="closeBtn_fC0A" title="Dismiss update, and don't show again" aria-label="Dismiss update, and don't show again">×</button></div><div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#__docusaurus_skipToContent_fallback">Skip to main content</a></div><nav aria-label="Main" class="theme-layout-navbar navbar navbar--fixed-top"><div class="navbar__inner"><div class="theme-layout-navbar-left navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" 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><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--light_NVdE"><img src="/img/dashy.png" alt="Dashy Logo" class="themedComponent_mlkZ themedComponent--dark_xIcU"></div><b class="navbar__title text--truncate">Dashy</b></a><a href="https://github.com/lissy93/dashy" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><a href="https://demo.dashy.to" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link">Live Demo<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a><a class="navbar__item navbar__link" href="/docs/quick-start">Quick Start</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="/docs">Documentation</a></div><div class="theme-layout-navbar-right navbar__items navbar__items--right"><div class="toggle_vylO colorModeToggle_DEke"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="system mode" aria-label="Switch between dark and light mode (currently system mode)"><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" aria-hidden="true" class="toggleIcon_g3eP systemToggleIcon_QzmC"><path fill="currentColor" d="m12 21c4.971 0 9-4.029 9-9s-4.029-9-9-9-9 4.029-9 9 4.029 9 9 9zm4.95-13.95c1.313 1.313 2.05 3.093 2.05 4.95s-0.738 3.637-2.05 4.95c-1.313 1.313-3.093 2.05-4.95 2.05v-14c1.857 0 3.637 0.737 4.95 2.05z"></path></svg></button></div><div class="navbarSearchContainer_Bca1"><div class="navbar__search searchBarContainer_NW3z" dir="ltr"><input placeholder="Search" aria-label="Search" class="navbar__search-input searchInput_YFbd" value=""><div class="loadingRing_RJI3 searchBarLoadingRing_YnHq"><div></div><div></div><div></div><div></div></div></div></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="theme-layout-main main-wrapper mainWrapper_z2l0"><div class="docsWrapper_hBAB"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_sjWU" type="button"></button><div class="docRoot_UBD9"><aside class="theme-doc-sidebar-container docSidebarContainer_YfHR"><div class="sidebarViewport_aRkj"><div class="sidebar_njMd"><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_SIkG"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/quick-start"><span title="Running Dashy" class="categoryLinkLabel_W154">Running Dashy</span></a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/icons"><span title="Feature Docs" class="categoryLinkLabel_W154">Feature Docs</span></a></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret menu__link--active" role="button" aria-expanded="true" href="/docs/showcase"><span title="Community" class="categoryLinkLabel_W154">Community</span></a></div><ul class="menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/showcase"><span title="*Dashy Showcase* 🌟" class="linkLabel_WmDU">*Dashy Showcase* 🌟</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/contributing"><span title="Contributing" class="linkLabel_WmDU">Contributing</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" tabindex="0" href="/docs/developing"><span title="Developing" class="linkLabel_WmDU">Developing</span></a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-2 menu__list-item"><a class="menu__link" tabindex="0" href="/docs/development-guides"><span title="Development Guides" class="linkLabel_WmDU">Development Guides</span></a></li></ul></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="categoryLink_byQd menu__link menu__link--sublist menu__link--sublist-caret" role="button" aria-expanded="false" href="/docs/privacy"><span title="Misc" class="categoryLinkLabel_W154">Misc</span></a></div></li></ul></nav></div><div class="sidebar-ad"><script async="" src="//cdn.carbonads.com/carbon.js?serve=CWYIC53L&placement=dashyto" id="_carbonads_js"></script></div></div></aside><main class="docMainContainer_TBSr"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_VOVn"><div class="docItemContainer_Djhp"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_Z_bl" aria-label="Breadcrumbs"><ul class="breadcrumbs"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="/"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_YNFT"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li class="breadcrumbs__item"><span class="breadcrumbs__link">Community</span></li><li class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link">Developing</span></li></ul></nav><div class="tocCollapsible_ETCw theme-doc-toc-mobile tocMobile_ITEo"><button type="button" class="clean-btn tocCollapsibleButton_TO0P">On this page</button></div><div class="theme-doc-markdown markdown"><header><h1>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're adding new features, you may want to check out the <a class="" href="/docs/development-guides">Development Guides</a> docs, for tutorials covering basic tasks.</p>
|
||
<ul>
|
||
<li class=""><a href="#setting-up-the-dev-environment" class="">Setting up the Development Environment</a>
|
||
<ul>
|
||
<li class=""><a href="#prerequisites" class="">Prerequisites</a></li>
|
||
<li class=""><a href="#running-the-project" class="">Running the App</a></li>
|
||
<li class=""><a href="#project-commands" class="">Project Commands</a></li>
|
||
<li class=""><a href="#environmental-variables" class="">Environmental Variables</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class=""><a href="#git-strategy" class="">Git Strategy</a>
|
||
<ul>
|
||
<li class=""><a href="#git-flow" class="">Flow</a></li>
|
||
<li class=""><a href="#git-branch-naming" class="">Branches</a></li>
|
||
<li class=""><a href="#commit-emojis" class="">Commit emojis</a></li>
|
||
<li class=""><a href="#pr-guidelines" class="">PR Guidelines</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class=""><a href="#resources-for-beginners" class="">Resources for Beginners</a></li>
|
||
<li class=""><a href="#app-info" class="">App Info</a></li>
|
||
<li class=""><a href="#style-guide" class="">Code Style Guide</a></li>
|
||
<li class=""><a href="#application-structure" class="">Application Structure</a></li>
|
||
<li class=""><a href="#development-tools" class="">Development Tools</a></li>
|
||
<li class=""><a href="#notes" class="">Misc / Notes</a></li>
|
||
</ul>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="setting-up-the-dev-environment">Setting up the Dev Environment<a href="#setting-up-the-dev-environment" class="hash-link" aria-label="Direct link to Setting up the Dev Environment" title="Direct link to Setting up the Dev Environment" translate="no"></a></h2>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="prerequisites">Prerequisites<a href="#prerequisites" class="hash-link" aria-label="Direct link to Prerequisites" title="Direct link to Prerequisites" translate="no"></a></h3>
|
||
<p>You will need either the latest or LTS version of <strong><a href="https://nodejs.org/" target="_blank" rel="noopener noreferrer" class="">Node.js</a></strong> to build and serve the application and <strong><a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer" class="">Git</a></strong> to easily fetch the code, and push any changes. If you plan on running or deploying the container, you'll also need <strong><a href="https://docs.docker.com/get-docker/" target="_blank" rel="noopener noreferrer" class="">Docker</a></strong>. To avoid any unexpected issues, ensure you've got at least <strong><a href="https://www.npmjs.com/get-npm" target="_blank" rel="noopener noreferrer" class="">NPM</a></strong> V 7.5 or <strong><a href="https://classic.yarnpkg.com/en/docs/install/#windows-stable" target="_blank" rel="noopener noreferrer" class="">Yarn</a></strong> 1.22 (you may find <a href="https://github.com/nvm-sh/nvm" target="_blank" rel="noopener noreferrer" class="">NVM</a> helpful for switching/ managing versions).</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="running-the-project">Running the Project<a href="#running-the-project" class="hash-link" aria-label="Direct link to Running the Project" title="Direct link to Running the Project" translate="no"></a></h3>
|
||
<ol>
|
||
<li class="">Get Code: <code>git clone https://github.com/Lissy93/dashy.git</code></li>
|
||
<li class="">Navigate into the directory: <code>cd dashy</code></li>
|
||
<li class="">Install dependencies: <code>yarn</code></li>
|
||
<li class="">Start dev server: <code>yarn dev</code></li>
|
||
</ol>
|
||
<p>Dashy should now be being served on <a href="http://localhost:8080/" target="_blank" rel="noopener noreferrer" class="">http://localhost:8080/</a>. Hot reload is enabled, so making changes to any of the files will trigger them to be rebuilt and the page refreshed.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="project-commands">Project Commands<a href="#project-commands" class="hash-link" aria-label="Direct link to Project Commands" title="Direct link to Project Commands" translate="no"></a></h3>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="basics">Basics<a href="#basics" class="hash-link" aria-label="Direct link to Basics" title="Direct link to Basics" translate="no"></a></h4>
|
||
<ul>
|
||
<li class=""><strong><code>yarn build</code></strong> - In the interest of speed, the application is pre-compiled, this means that the config file is read during build-time, and therefore the app needs to rebuilt for any new changes to take effect. Luckily this is very straight forward. Just run <code>yarn build</code> or <code>docker exec -it [container-id] yarn build</code></li>
|
||
<li class=""><strong><code>yarn start</code></strong> - Starts a web server, and serves up the production site from <code>./dist</code> (must run build command first)</li>
|
||
</ul>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="development">Development<a href="#development" class="hash-link" aria-label="Direct link to Development" title="Direct link to Development" translate="no"></a></h4>
|
||
<ul>
|
||
<li class=""><strong><code>yarn dev</code></strong> - Starts the development server with hot reloading</li>
|
||
<li class=""><strong><code>yarn lint</code></strong> - Lints code to ensure it follows a consistent, neat style</li>
|
||
<li class=""><strong><code>yarn test</code></strong> - Runs tests, and outputs results</li>
|
||
</ul>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="utils-and-checks">Utils and Checks<a href="#utils-and-checks" class="hash-link" aria-label="Direct link to Utils and Checks" title="Direct link to Utils and Checks" translate="no"></a></h4>
|
||
<ul>
|
||
<li class=""><strong><code>yarn validate-config</code></strong> - If you have quite a long configuration file, you may wish to check that it's all good to go, before deploying the app. This can be done with <code>yarn validate-config</code> or <code>docker exec -it [container-id] yarn validate-config</code>. Your config file needs to be in <code>/user-data/conf.yml</code> (or within your Docker container at <code>/app/user-data/conf.yml</code>). This will first check that your YAML is valid, and then validates it against Dashy's <a href="https://github.com/Lissy93/dashy/blob/master/src/utils/ConfigSchema.js" target="_blank" rel="noopener noreferrer" class="">schema</a>.</li>
|
||
<li class=""><strong><code>yarn health-check</code></strong> - Checks that the application is up and running on it's specified port, and outputs current status and response times. Useful for integrating into your monitoring service, if you need to maintain high system availability</li>
|
||
</ul>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="alternate-start-commands">Alternate Start Commands<a href="#alternate-start-commands" class="hash-link" aria-label="Direct link to Alternate Start Commands" title="Direct link to Alternate Start Commands" translate="no"></a></h4>
|
||
<ul>
|
||
<li class=""><strong><code>yarn build-and-start</code></strong> - Builds the app, runs checks and starts the production server. Commands are run in parallel, and so is faster than running them in independently. Uses the <code>yarn build</code> and <code>yarn start</code> commands</li>
|
||
<li class=""><strong><code>yarn build-watch</code></strong> - If you find yourself making frequent changes to your configuration, and do not want to have to keep manually rebuilding, then this option is for you. It will watch for changes to any files within the projects root, and then trigger a rebuild. Note that if you are developing new features, then <code>yarn dev</code> would be more appropriate, as it's significantly faster at recompiling (under 1 second), and has hot reloading, linting and testing integrated</li>
|
||
<li class=""><strong><code>yarn pm2-start</code></strong> - Starts the Node server using <a href="https://pm2.keymetrics.io/" target="_blank" rel="noopener noreferrer" class="">PM2</a>, a process manager for Node.js applications, that helps them stay alive. PM2 has some built-in basic monitoring features, and an optional <a href="https://pm2.io/" target="_blank" rel="noopener noreferrer" class="">management solution</a>. If you are running the app on bare metal, it is recommended to use this start command</li>
|
||
</ul>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="notes">Notes<a href="#notes" class="hash-link" aria-label="Direct link to Notes" title="Direct link to Notes" translate="no"></a></h4>
|
||
<ul>
|
||
<li class="">If you are using NPM, replace <code>yarn</code> with <code>npm run</code></li>
|
||
<li class="">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>
|
||
<li class="">You can manage the app using the <a href="https://cli.vuejs.org/guide/cli-service.html" target="_blank" rel="noopener noreferrer" class="">Vue-CLI Service</a>, with <code>npx vue-cli-service [command]</code>. Or to start the Vue Management UI, run <code>npx vue ui</code>, and open <code>http://localhost:8000</code></li>
|
||
</ul>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="environmental-variables">Environmental Variables<a href="#environmental-variables" class="hash-link" aria-label="Direct link to Environmental Variables" title="Direct link to Environmental Variables" translate="no"></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 either in your environment, or using the <a href="https://github.com/Lissy93/dashy/blob/master/.env" target="_blank" rel="noopener noreferrer" class=""><code>.env</code></a> file.</p>
|
||
<ul>
|
||
<li class=""><code>NODE_ENV</code> - Current environment, can be either development, production or test</li>
|
||
<li class=""><code>PORT</code> - The port to expose the running application on</li>
|
||
<li class=""><code>HOST</code> - The host that Dashy is running on, domain or IP</li>
|
||
<li class=""><code>BASE_URL</code> - The default base path for serving up static assets</li>
|
||
<li class=""><code>VUE_APP_DOMAIN</code> - Usually the same as BASE_URL, but accessible in frontend</li>
|
||
<li class=""><code>INTEGRITY</code> - Should enable SRI for build script and link resources</li>
|
||
<li class=""><code>IS_DOCKER</code> - Computed automatically on build. Indicates if running in container</li>
|
||
<li class=""><code>VUE_APP_VERSION</code> - Again, set automatically using package.json during build time</li>
|
||
<li class=""><code>BACKUP_DIR</code> - Directory for conf.yml backups</li>
|
||
</ul>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="environment-modes">Environment Modes<a href="#environment-modes" class="hash-link" aria-label="Direct link to Environment Modes" title="Direct link to Environment Modes" translate="no"></a></h3>
|
||
<p>You can set the environment using the <code>NODE_ENV</code> variable. By default, the correct environment should be selected based on the script you run to start the app. The following environments are supported: <code>production</code>, <code>development</code> and <code>test</code>. For more info, see <a href="https://cli.vuejs.org/guide/mode-and-env.html#modes" target="_blank" rel="noopener noreferrer" class="">Vue CLI Environment Modes</a>.</p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="git-strategy">Git Strategy<a href="#git-strategy" class="hash-link" aria-label="Direct link to Git Strategy" title="Direct link to Git Strategy" translate="no"></a></h2>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="git-flow">Git Flow<a href="#git-flow" class="hash-link" aria-label="Direct link to Git Flow" title="Direct link to Git Flow" translate="no"></a></h3>
|
||
<p>Like most Git repos, we are following the <a href="https://guides.github.com/introduction/flow" target="_blank" rel="noopener noreferrer" class="">Github Flow</a> standard.</p>
|
||
<ol>
|
||
<li class="">Create a branch (or fork if you don'd have write access)</li>
|
||
<li class="">Code some awesome stuff 🧑💻</li>
|
||
<li class="">Add, commit and push your changes to your branch/ fork</li>
|
||
<li class="">Head over to GitHub and create a Pull Request</li>
|
||
<li class="">Fill in the required sections in the template, and hit submit</li>
|
||
<li class="">Follow up with any reviews on your code</li>
|
||
<li class="">Merge 🎉</li>
|
||
</ol>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="git-branch-naming">Git Branch Naming<a href="#git-branch-naming" class="hash-link" aria-label="Direct link to Git Branch Naming" title="Direct link to Git Branch Naming" translate="no"></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 class="anchor anchorTargetStickyNavbar_Vzrq" id="commit-emojis">Commit Emojis<a href="#commit-emojis" class="hash-link" aria-label="Direct link to Commit Emojis" title="Direct link to Commit Emojis" translate="no"></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 class="">🎨 <code>:art:</code> - Improve structure / format of the code.</li>
|
||
<li class="">⚡️ <code>:zap:</code> - Improve performance.</li>
|
||
<li class="">🔥 <code>:fire:</code> - Remove code or files.</li>
|
||
<li class="">🐛 <code>:bug:</code> - Fix a bug.</li>
|
||
<li class="">🚑️ <code>:ambulance:</code> - Critical hotfix</li>
|
||
<li class="">✨ <code>:sparkles:</code> - Introduce new features.</li>
|
||
<li class="">📝 <code>:memo:</code> - Add or update documentation.</li>
|
||
<li class="">🚀 <code>:rocket:</code> - Deploy stuff.</li>
|
||
<li class="">💄 <code>:lipstick:</code> - Add or update the UI and style files.</li>
|
||
<li class="">🎉 <code>:tada:</code> - Begin a project.</li>
|
||
<li class="">✅ <code>:white_check_mark:</code> - Add, update, or pass tests.</li>
|
||
<li class="">🔒️ <code>:lock:</code> - Fix security issues.</li>
|
||
<li class="">🔖 <code>:bookmark:</code> - Make a Release or Version tag.</li>
|
||
<li class="">🚨 <code>:rotating_light:</code> - Fix compiler / linter warnings.</li>
|
||
<li class="">🚧 <code>:construction:</code> - Work in progress.</li>
|
||
<li class="">⬆️ <code>:arrow_up:</code> - Upgrade dependencies.</li>
|
||
<li class="">👷 <code>:construction_worker:</code> - Add or update CI build system.</li>
|
||
<li class="">♻️ <code>:recycle:</code> - Refactor code.</li>
|
||
<li class="">🩹 <code>:adhesive_bandage:</code> - Simple fix for a non-critical issue.</li>
|
||
<li class="">🔧 <code>:wrench:</code> - Add or update configuration files.</li>
|
||
<li class="">🍱 <code>:bento:</code> - Add or update assets.</li>
|
||
<li class="">🗃️ <code>:card_file_box:</code> - Perform database schema related changes.</li>
|
||
<li class="">✏️ <code>:pencil2:</code> - Fix typos.</li>
|
||
<li class="">🌐 <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" class="">gitmoji.dev</a></p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="pr-guidelines">PR Guidelines<a href="#pr-guidelines" class="hash-link" aria-label="Direct link to PR Guidelines" title="Direct link to PR Guidelines" translate="no"></a></h3>
|
||
<p>Once you've made your changes, and pushed them to your fork or branch, you're ready to open a pull request!</p>
|
||
<p>For a pull request to be merged, it must:</p>
|
||
<ul>
|
||
<li class="">Must be backwards compatible</li>
|
||
<li class="">The build, lint and tests (run by GH actions) must pass</li>
|
||
<li class="">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 class="">A brief description of your changes</li>
|
||
<li class="">The issue, ticket or discussion number (if applicable)</li>
|
||
<li class="">For UI relate updates include a screenshot</li>
|
||
<li class="">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 class="">Finally, check the checkboxes, to confirm that the standards are met, and hit submit!</li>
|
||
</ul>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="resources-for-beginners">Resources for Beginners<a href="#resources-for-beginners" class="hash-link" aria-label="Direct link to Resources for Beginners" title="Direct link to Resources for Beginners" translate="no"></a></h2>
|
||
<p>New to Web Development? Glad you'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 class=""><a href="https://opensource.guide/how-to-contribute/" target="_blank" rel="noopener noreferrer" class="">Open Source for Beginners</a></li>
|
||
<li class=""><a href="https://v3.vuejs.org/guide/introduction.html" target="_blank" rel="noopener noreferrer" class="">Introduction to Vue.js</a></li>
|
||
<li class=""><a href="https://www.taniarascia.com/getting-started-with-vue/" target="_blank" rel="noopener noreferrer" class="">Vue.js Walkthrough</a></li>
|
||
<li class=""><a href="https://github.com/lukehoban/es6features" target="_blank" rel="noopener noreferrer" class="">ES6 Features</a></li>
|
||
<li class=""><a href="https://blog.logrocket.com/the-definitive-guide-to-scss/" target="_blank" rel="noopener noreferrer" class="">Definitive guide to SCSS</a></li>
|
||
<li class=""><a href="https://docker-curriculum.com/" target="_blank" rel="noopener noreferrer" class="">Complete beginners guide to Docker</a></li>
|
||
<li class=""><a href="https://training.play-with-docker.com/" target="_blank" rel="noopener noreferrer" class="">Docker Classroom - Interactive Tutorials</a></li>
|
||
<li class=""><a href="https://www.freecodecamp.org/news/learn-typescript-in-5-minutes-13eda868daeb/" target="_blank" rel="noopener noreferrer" class="">Quick start TypeScript guide</a></li>
|
||
<li class=""><a href="https://www.typescripttutorial.net/" target="_blank" rel="noopener noreferrer" class="">Complete TypeScript tutorial series</a></li>
|
||
<li class=""><a href="https://blog.logrocket.com/vue-typescript-tutorial-examples/" target="_blank" rel="noopener noreferrer" class="">Using TypeScript with Vue.js</a></li>
|
||
<li class=""><a href="http://git-cheatsheet.com/" target="_blank" rel="noopener noreferrer" class="">Git cheat sheet</a></li>
|
||
<li class=""><a href="https://www.freecodecamp.org/news/what-is-npm-a-node-package-manager-tutorial-for-beginners/" target="_blank" rel="noopener noreferrer" class="">Basics of using NPM</a></li>
|
||
</ul>
|
||
<p>As well as Node, Git and Docker- you'll also need an IDE (e.g. <a href="https://code.visualstudio.com/" target="_blank" rel="noopener noreferrer" class="">VS Code</a> or <a href="https://www.vim.org/" target="_blank" rel="noopener noreferrer" class="">Vim</a>) and a terminal (Windows users may find <a href="https://docs.microsoft.com/en-us/windows/wsl/" target="_blank" rel="noopener noreferrer" class="">WSL</a> more convenient).</p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="app-info">App Info<a href="#app-info" class="hash-link" aria-label="Direct link to App Info" title="Direct link to App Info" translate="no"></a></h2>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="style-guide">Style Guide<a href="#style-guide" class="hash-link" aria-label="Direct link to Style Guide" title="Direct link to Style Guide" translate="no"></a></h3>
|
||
<p>Linting is done using <a href="https://eslint.org/" target="_blank" rel="noopener noreferrer" class="">ESLint</a>, and using the <a href="https://github.com/vuejs/eslint-config-standard" target="_blank" rel="noopener noreferrer" class="">Vue.js Styleguide</a>, which is very similar to the <a href="https://github.com/airbnb/javascript" target="_blank" rel="noopener noreferrer" class="">AirBnB Styleguide</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 class="">Indentation should be done with two spaces</li>
|
||
<li class="">Strings should use single quotes</li>
|
||
<li class="">All statements must end in a semi-colon</li>
|
||
<li class="">The final element in all objects must be preceded with a comma</li>
|
||
<li class="">Maximum line length is 100</li>
|
||
<li class="">There must be exactly one blank line between sections, before function names, and at the end of the file</li>
|
||
<li class="">With conditionals, put else on the same line as your if block's closing brace</li>
|
||
<li class="">All multiline blocks must use braces</li>
|
||
<li class="">Avoid console statements in the frontend</li>
|
||
</ul>
|
||
<p>Styleguides:</p>
|
||
<ul>
|
||
<li class="">Vue: <a href="https://vuejs.org/v2/style-guide/" target="_blank" rel="noopener noreferrer" class="">Vue styleguide</a></li>
|
||
<li class="">JavaScript: <a href="https://github.com/airbnb/javascript" target="_blank" rel="noopener noreferrer" class="">github.com/airbnb/javascript</a></li>
|
||
</ul>
|
||
<hr>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="application-structure">Application Structure<a href="#application-structure" class="hash-link" aria-label="Direct link to Application Structure" title="Direct link to Application Structure" translate="no"></a></h3>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="files-in-the-root-">Files in the Root: <code>./</code><a href="#files-in-the-root-" class="hash-link" aria-label="Direct link to files-in-the-root-" title="Direct link to files-in-the-root-" translate="no"></a></h4>
|
||
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">╮</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── package.json # Project meta-data, dependencies and paths to scripts</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── src/ # Project front-end source code</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── server.js # A Node.js server to serve up the /dist directory</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── services/ # All server-side endpoints and utilities</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── vue.config.js # Vue.js configuration</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── Dockerfile # The blueprint for building the Docker container</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── docker-compose.yml # A Docker run command</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── .env # Location for any environmental variables</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── yarn.lock # Auto-generated list of current packages and version numbers</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── docs/ # Markdown documentation</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── README.md # Readme, basic info for getting started</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── LICENSE.md # License for use</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">╯</span><br></span></code></pre></div></div>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="frontend-source-src">Frontend Source: <code>./src/</code><a href="#frontend-source-src" class="hash-link" aria-label="Direct link to frontend-source-src" title="Direct link to frontend-source-src" translate="no"></a></h4>
|
||
<div class="language-text codeBlockContainer_Ckt0 theme-code-block" style="--prism-color:#F8F8F2;--prism-background-color:#282A36"><div class="codeBlockContent_QJqH"><pre tabindex="0" class="prism-code language-text codeBlock_bY9V thin-scrollbar" style="color:#F8F8F2;background-color:#282A36"><code class="codeBlockLines_e6Vv"><span class="token-line" style="color:#F8F8F2"><span class="token plain">./src</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── App.vue # Vue.js starting file</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── assets # Static non-compiled assets</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── fonts # .ttf font files</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── locales # All app text, each language in a separate JSON file</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── interface-icons # SVG icons used in the app</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── components # All front-end Vue web components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Charts # Charting components for dynamically displaying widget data</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Gauge.vue # A speed-dial style chart for showing 0 - 100 values</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── PercentageChart.vue # A horizontal bar for showing percentage breakdowns</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Configuration # Components relating to the user config pop-up</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── AppInfoModal.vue # A modal showing core app info, like version, language, etc</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── AppVersion.vue # Shows current version from package.json, compares with GitHub</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── CloudBackupRestore.vue # Form where the user manages cloud sync options</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ConfigContainer.vue # Main container, wrapping all other config components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── CustomCss.vue # Form where the user can input custom CSS</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditSiteMeta.vue # Form where the user can edit site meta data</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── JsonEditor.vue # JSON editor, where the user can modify the main config file</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── RebuildApp.vue # A component allowing user to trigger a rebuild through the UI</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── FormElements # Basic form elements used throughout the app</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Button.vue # Standard button component</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Radio.vue # Standard radio button input</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Select.vue # Standard dropdown input selector</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Input.vue # Standard text field input component</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── Toggle.vue # Standard on / off toggle switch</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── InteractiveEditor # Components for the interactive UI config editor</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── AddNewSectionLauncher # Button that launches the EditSection form, used for adding new section</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditAppConfig.vue # Form for editing appConfig</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditPageInfo.vue # Form for editing pageInfo</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditSection.vue # Form for adding / editing sections</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditItem.vue # Form for adding or editing items</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditModeSaveMenu.vue # The bar at the bottom of screen in edit mode, containing save buttons</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── EditModeTopBanner.vue # The bar at the top of screen in edit mode</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ExportConfigMenu.vue # Modal for viewing / exporting edited config</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── MoveItemTo.vue # Form for moving / copying items to other sections</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── SaveCancelButtons.vue # Buttons visible in all the edit menus, to save or cancel changes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── LinkItems # Components for Sections and Link Items</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Collapsable.vue # The collapsible functionality of sections</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── IframeModal.vue # Pop-up iframe modal, for viewing websites within the app</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Item.vue # Main link item, which is displayed within an item group</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ItemGroup.vue # Item group is a section containing icons</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ItemIcon.vue # The icon used by both items and sections</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ItemOpenMethodIcon.vue # A small icon, visible on hover, indicating opening method</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── ItemContextMenu.vue # The right-click menu, for showing Item opening methods and info</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── SectionContextMenu.vue # The right-click menu, for showing Section edit/ open options</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── StatusIndicator.vue # Traffic light dot, showing if app is online or down</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Minimal View # Components used for the startpage / minimal alternative view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── MinimalHeading.vue # Title part of minimal view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── MinimalSearch.vue # Search bar for minimal view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── MinimalSection.vue # Tabbed-Item section for minimal view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── PageStrcture # Components relating the main structure of the page</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Footer.vue # Footer, visible at the bottom of all pages</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Header.vue # Header, visible at the top of pages, and includes title and nav</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── LoadingScreen.vue # Splash screen shown on first load</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── Nav.vue # Navigation bar, includes a list of links</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── PageTitle.vue # Page title and sub-title, visible within the Header</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Workspace # Components used for the multi-tasking/ Workspace view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── MultiTaskingWeb.vue # When multi-tasking enabled, generates new iframe</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── SideBar.vue # The left sidebar for the workspace view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── SideBarItem.vue # App item for the sidebar view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── SideBarSection.vue # Collapsible collection of items within workspace sidebar</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ├── WebContent.vue # Workspace iframe view, displays content of current app</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── WidgetView.vue # Workspace container for displaying widgets in main content</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Widgets # Directory contains all custom widget components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ │ ╰── .... # Too many to list, see widget docs instead</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── Settings # Components relating to the quick-settings, in the top-right</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── AuthButtons.vue # Logout button and other app info</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigLauncher.vue # Icon that when clicked will launch the Configuration component</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── CustomThemeMaker.vue # Color pickers for letting user build their own theme</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ItemSizeSelector.vue # Set of buttons used to set and save item size</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── KeyboardShortcutInfo.vue# Small pop-up displaying the available keyboard shortcuts</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── LanguageSwitcher.vue # Dropdown in a modal for changing app language</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── LayoutSelector.vue # Set of buttons, letting the user select their desired layout</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── SearchBar.vue # The input field in the header, used for searching the app</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── SettingsContainer.vue # Container that wraps all the quick-settings components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── ThemeSelector.vue # Drop-down menu enabling the user to select and change themes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── main.js # Main front-end entry point</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── registerServiceWorker.js # Registers and manages service workers, for PWA apps</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── router.js # Defines all available application routes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── styles # Directory of all globally used common SCSS styles</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── color-palette.scss # All color variable names and default values</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── color-themes.scss # All variable values for built-in themes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── dimensions.scss # Dimensions and sizes as variables</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── global-styles.scss # Basics and style resets used globally</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── media-queries.scss # Screen sizes and media queries</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── style-helpers.scss # SCSS functions used for modifying values</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── typography.scss # Font and text styles used globally</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── user-defined-themes.scss # Empty, put any custom styles or themes here</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── mixins # Reusable component bases, extended by other views / components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ChartingMixin.js # Functions for rendering charts in widget components</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── GlancesMixin.js # Functions for fetching system info from Glances for widgets</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── HomeMixin.js # Functions for homepage, used by default, minimal and workspace views</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── WidgetMixin.js # Functions for all widgets, like data fetching, updating and error handling</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">├── utils # Directory of re-used helper functions</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ArrowKeyNavigation.js # Functionality for arrow-key navigation</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Auth.js # Handles all authentication related actions</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── CheckSectionVisibility.js # Checks which parts of the page should be visible/ hidden based on config</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ClickOutside.js # A directive for detecting click, used to hide dropdown, modal or context menu</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigHelpers.js # Helper functions for managing configuration</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── CloudBackup.js # Functionality for encrypting, processing and network calls</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigSchema.json # The schema, used to validate the users conf.yml file</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigAccumulator.js # Central place for managing and combining config</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigHelpers.json # Collection of helper functions to process config using accumulator</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ConfigValidator.js # A helper script that validates the config file against schema</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── CoolConsole.js # Prints info, warning and error messages to browser console, with a cool style</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── defaults.js # Global constants and their default values</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── emojis.json # List of emojis with unicode and shortcode, used for emoji icon feature</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── EmojiUnicodeRegex.js # Regular expression to validate emoji unicode format, for emoji icons</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── ErrorHandler.js # Helper function called when an error is returned</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── InitServiceWorker.js # Initializes and manages service worker, if enabled</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── Search.js # Helper functions for searching/ filtering items in all views</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── JsonToYaml.js # Function that parses and converts raw JSON into valid YAML</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── KeycloakAuth.js # Singleton class to manage Keycloak authentication</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ├── languages.js # Handles fetching, switching and validating languages</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">│ ╰── ThemeHelper.js # Function that handles the fetching and setting of user themes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain">╰── views # Directory of available pages, corresponding to available routes</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> ├── Home.vue # The home page container</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> ├── About.vue # About page</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> ├── Login.vue # TAuthentication page</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> ├── Minimal.vue # The minimal view</span><br></span><span class="token-line" style="color:#F8F8F2"><span class="token plain"> ╰── Workspace.vue # The workspace view with apps in sidebar</span><br></span></code></pre></div></div>
|
||
<h4 class="anchor anchorTargetStickyNavbar_Vzrq" id="visualisation-of-source-directory">Visualisation of Source Directory<a href="#visualisation-of-source-directory" class="hash-link" aria-label="Direct link to Visualisation of Source Directory" title="Direct link to Visualisation of Source Directory" translate="no"></a></h4>
|
||
<p><img decoding="async" loading="lazy" src="https://raw.githubusercontent.com/Lissy93/dashy/master/docs/assets/repo-visualization.svg" alt="File Breakdown" class="img_ev3q"></p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="development-tools">Development Tools<a href="#development-tools" class="hash-link" aria-label="Direct link to Development Tools" title="Direct link to Development Tools" translate="no"></a></h2>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="performance---lighthouse">Performance - Lighthouse<a href="#performance---lighthouse" class="hash-link" aria-label="Direct link to Performance - Lighthouse" title="Direct link to Performance - Lighthouse" translate="no"></a></h3>
|
||
<p>The easiest method of checking performance is to use Chromium's build in auditing tool, Lighthouse. To run the test, open Developer Tools (usually F12) --> Lighthouse and click on the 'Generate Report' button at the bottom.</p>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="dependencies---bundlephobia">Dependencies - BundlePhobia<a href="#dependencies---bundlephobia" class="hash-link" aria-label="Direct link to Dependencies - BundlePhobia" title="Direct link to Dependencies - BundlePhobia" translate="no"></a></h3>
|
||
<p><a href="https://bundlephobia.com/" target="_blank" rel="noopener noreferrer" class="">BundlePhobia</a> is a really useful app that lets you analyze the cost of adding any particular dependency to an application</p>
|
||
<hr>
|
||
<h2 class="anchor anchorTargetStickyNavbar_Vzrq" id="notes-1">Notes<a href="#notes-1" class="hash-link" aria-label="Direct link to Notes" title="Direct link to Notes" translate="no"></a></h2>
|
||
<h3 class="anchor anchorTargetStickyNavbar_Vzrq" id="known-warnings">Known Warnings<a href="#known-warnings" class="hash-link" aria-label="Direct link to Known Warnings" title="Direct link to Known Warnings" translate="no"></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're using an older version of SASS loader, since the more recent releases do not seem to be compatible with the Vue CLI'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't have any impact on application performance. A similar warning is thrown for the Raleway font, and that is looking to be addressed.</p></div><footer class="theme-doc-footer docusaurus-mt-lg"><div class="row margin-top--sm theme-doc-footer-edit-meta-row"><div class="col noPrint_WFHX"><a href="https://github.com/Lissy93/dashy/edit/gh-pages/docs/docs/developing.md" target="_blank" rel="noopener noreferrer" class="theme-edit-this-page"><svg fill="currentColor" height="20" width="20" viewBox="0 0 40 40" class="iconEdit_Z9Sw" 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_JAkA"><span class="theme-last-updated">Last updated<!-- --> on <b><time datetime="2026-03-10T16:09:41.000Z" itemprop="dateModified">Mar 10, 2026</time></b></span></div></div></footer></article><nav class="docusaurus-mt-lg pagination-nav" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="/docs/contributing"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Contributing</div></a><a class="pagination-nav__link pagination-nav__link--next" href="/docs/development-guides"><div class="pagination-nav__sublabel">Next</div><div class="pagination-nav__label">Development Guides</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_bqdL thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="#setting-up-the-dev-environment" class="table-of-contents__link toc-highlight">Setting up the Dev Environment</a><ul><li><a href="#prerequisites" class="table-of-contents__link toc-highlight">Prerequisites</a></li><li><a href="#running-the-project" class="table-of-contents__link toc-highlight">Running the Project</a></li><li><a href="#project-commands" class="table-of-contents__link toc-highlight">Project Commands</a></li><li><a href="#environmental-variables" class="table-of-contents__link toc-highlight">Environmental Variables</a></li><li><a href="#environment-modes" class="table-of-contents__link toc-highlight">Environment Modes</a></li></ul></li><li><a href="#git-strategy" class="table-of-contents__link toc-highlight">Git Strategy</a><ul><li><a href="#git-flow" class="table-of-contents__link toc-highlight">Git Flow</a></li><li><a href="#git-branch-naming" class="table-of-contents__link toc-highlight">Git Branch Naming</a></li><li><a href="#commit-emojis" class="table-of-contents__link toc-highlight">Commit Emojis</a></li><li><a href="#pr-guidelines" class="table-of-contents__link toc-highlight">PR Guidelines</a></li></ul></li><li><a href="#resources-for-beginners" class="table-of-contents__link toc-highlight">Resources for Beginners</a></li><li><a href="#app-info" class="table-of-contents__link toc-highlight">App Info</a><ul><li><a href="#style-guide" class="table-of-contents__link toc-highlight">Style Guide</a></li><li><a href="#application-structure" class="table-of-contents__link toc-highlight">Application Structure</a></li></ul></li><li><a href="#development-tools" class="table-of-contents__link toc-highlight">Development Tools</a><ul><li><a href="#performance---lighthouse" class="table-of-contents__link toc-highlight">Performance - Lighthouse</a></li><li><a href="#dependencies---bundlephobia" class="table-of-contents__link toc-highlight">Dependencies - BundlePhobia</a></li></ul></li><li><a href="#notes-1" class="table-of-contents__link toc-highlight">Notes</a><ul><li><a href="#known-warnings" class="table-of-contents__link toc-highlight">Known Warnings</a></li></ul></li></ul></div></div></div></div></main></div></div></div><footer class="theme-layout-footer footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Intro</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://github.com/lissy93/dashy" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://demo.dashy.to" target="_blank" rel="noopener noreferrer" class="footer__link-item">Live Demo<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></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="theme-layout-footer-column col footer__col"><div class="footer__title">Setup Guide</div><ul class="footer__items clean-list"><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="theme-layout-footer-column col footer__col"><div class="footer__title">Feature Docs Pt 1</div><ul class="footer__items clean-list"><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 & Restore</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/icons">Icons</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Feature Docs Pt 2</div><ul class="footer__items clean-list"><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 & Shortcuts</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/theming">Theming</a></li></ul></div><div class="theme-layout-footer-column col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><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="theme-layout-footer-column col footer__col"><div class="footer__title">Misc</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/privacy">Privacy & 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<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/CODE_OF_CONDUCT.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Code of Conduct<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></a></li><li class="footer__item"><a href="https://github.com/Lissy93/dashy/blob/master/.github/CHANGELOG.md" target="_blank" rel="noopener noreferrer" class="footer__link-item">Changelog<svg width="13.5" height="13.5" aria-label="(opens in new tab)" class="iconExternalLink_nPIU"><use href="#theme-svg-external-link"></use></svg></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 © 2026 <a href="https://aliciasykes.com">Alicia Sykes</a></div></div></div></footer></div>
|
||
</body>
|
||
</html> |