chore: improve dx for scripting & setup (#969)

* chore: rm vs code visual customizations * chore(api): fix vscode eslint extension * chore(web): update env.example for local development * chore: add justfiles to simplify workflows * chore: stub monorepo readme * chore: add nvmrc to monorepo root * refactor: improve error handling in `just ignore` * doc(web): explain TAILWIND_BASE_FONT_SIZE in .env.example * chore: add logo to readme
2026-02-09 09:29:12 -06:00 · 2024-12-02 10:07:56 -05:00
parent 547b75a55e
commit 0055637602
9 changed files with 319 additions and 21 deletions
--- a/.github/unraid.svg
+++ b/.github/unraid.svg
@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.2" viewBox="0 0 1000 1000"><defs><linearGradient id="a" x1="-900" x2="-100" y1="-100" y2="-900" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e32929"/><stop offset="1" stop-color="#ff8d30"/></linearGradient></defs><path fill="url(#a)" d="M1000 500.1v376.4c0 57.5-43.4 110.1-100 120.9-8.4 1.6-17.1 2.5-25.6 2.5-250.1.1-500.2.1-750.3.1-61.3 0-114.8-47-122.8-108q-.3-2.1-.6-4.1-.2-2-.3-4.1-.2-2-.3-4v-4.1C0 624.9 0 374.2 0 123.5 0 66 43.4 13.3 100 2.6 108.4 1 117.1.1 125.6.1 375.9 0 626.2 0 876.5 0 934 0 986.7 43.4 997.4 100c1.5 8.4 2.5 17.1 2.5 25.6.1 124.8.1 249.7.1 374.5z"/><path fill="#fff" d="M481.6 392.1h36.5v216.2h-36.5zm-356 0h36.5v216.2h-36.5zm178 242h36.5v82.5h-36.5zm-89.3-92.7h36.5v133.7h-36.5zm178 0h36.5V675h-36.5zm445.8-149.3h36.5v216.1h-36.5zm-178-107.8h36.5v82.6h-36.5zm89.3 41.5h36.5v133.1h-36.5zm-178.6 0h36.5v133h-36.5z"/></svg>
--- a/.nvmrc
+++ b/.nvmrc
@@ -0,0 +1 @@
+20
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -6,26 +6,6 @@
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  },
-  "workbench.colorCustomizations": {
-    "activityBar.activeBackground": "#78797d",
-    "activityBar.background": "#78797d",
-    "activityBar.foreground": "#e7e7e7",
-    "activityBar.inactiveForeground": "#e7e7e799",
-    "activityBarBadge.background": "#df9fac",
-    "activityBarBadge.foreground": "#15202b",
-    "commandCenter.border": "#e7e7e799",
-    "sash.hoverBorder": "#78797d",
-    "statusBar.background": "#5f6063",
-    "statusBar.foreground": "#e7e7e7",
-    "statusBarItem.hoverBackground": "#78797d",
-    "statusBarItem.remoteBackground": "#5f6063",
-    "statusBarItem.remoteForeground": "#e7e7e7",
-    "titleBar.activeBackground": "#5f6063",
-    "titleBar.activeForeground": "#e7e7e7",
-    "titleBar.inactiveBackground": "#5f606399",
-    "titleBar.inactiveForeground": "#e7e7e799"
-  },
-  "peacock.color": "#5f6063",
  "i18n-ally.localesPaths": [
    "locales"
  ],
--- a/api/.vscode/settings.json
+++ b/api/.vscode/settings.json
@@ -0,0 +1,7 @@
+{
+    "eslint.lintTask.options": "--flag unstable_ts_config",
+    "eslint.options": {
+        "flags": ["unstable_ts_config"],
+        "overrideConfigFile": ".eslintrc.ts"
+    }
+}
--- a/api/justfile
+++ b/api/justfile
@@ -0,0 +1,9 @@
+set fallback
+
+default:
+    @just --list --justfile {{justfile()}} --list-heading $'\nAPI project recipes:\n'
+    @just list-commands
+
+setup:
+    npm install
+    npm run container:build
--- a/42
+++ b/42
@@ -0,0 +1,42 @@
+# The first recipe in a justfile is considered the default recipe,
+# which means it runs when `just` is called with no arguments
+
+default: list-commands
+
+list-commands:
+    @just --list --justfile {{justfile()}} --list-heading $'\nMonorepo recipes:\n'  
+
+# Prepares the repo for development
+setup:
+    # ignore personal vscode settings. to contribute a change, use `just stop-ignore $file`
+    @just ignore .vscode/settings.json api/.vscode/settings.json web/.vscode/settings.json
+    # ignore api local-state files
+    @just ignore api/dev/states/myservers.cfg api/dev/Unraid.net/myservers.cfg
+
+    just api/setup
+    just web/setup
+
+
+# starts ignoring a file already tracked by git. (gitignore will not apply to these files)
+[group('git')]
+[no-cd]
+ignore +files:
+    #!/usr/bin/env bash
+    for file in {{ files }}; do
+        if [ ! -f "$file" ]; then
+            echo "Warning: $file does not exist"
+            continue
+        fi
+        git update-index --skip-worktree "$file"
+    done
+
+# resumes normal tracking of an ignored tracked file.
+[group('git')]
+[no-cd]
+stop-ignoring file:
+    git update-index --no-skip-worktree {{ file }}
+
+# lists tracked files where further changes are being ignored.
+[group('git')]
+list-ignored:
+    -git ls-files -v | grep '^S'
--- a/readme.md
+++ b/readme.md
@@ -0,0 +1,244 @@
+<!-- Adapted from: https://github.com/othneildrew/Best-README-Template -->
+<!-- Improved compatibility of back to top link: See: https://github.com/othneildrew/Best-README-Template/pull/73 -->
+<a id="readme-top"></a>
+
+<!-- PROJECT SHIELDS -->
+<!--
+*** I'm using markdown "reference style" links for readability.
+*** Reference links are enclosed in brackets [ ] instead of parentheses ( ).
+*** See the bottom of this document for the declaration of the reference variables
+*** for contributors-url, forks-url, etc. This is an optional, concise syntax you may use.
+*** https://www.markdownguide.org/basic-syntax/#reference-style-links
+-->
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+[![MIT License][license-shield]][license-url]
+[![LinkedIn][linkedin-shield]][linkedin-url]
+
+
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <a href="https://github.com/unraid/api">
+    <img src=".github/unraid.svg" alt="Logo" width="80" height="80">
+  </a>
+
+<h3 align="center">Unraid Connect</h3>
+
+  <p align="center">
+    Monorepo for Unraid Connect and the Unraid API.
+    <br />
+    <a href="https://docs.unraid.net/"><strong>Explore the docs »</strong></a>
+    <br />
+    <br />
+    <a href="https://github.com/unraid/api">View Demo</a>
+    ·
+    <a href="https://github.com/unraid/api/issues/new?labels=bug&template=bug-report---.md">Report Bug</a>
+    ·
+    <a href="https://github.com/unraid/api/issues/new?labels=enhancement&template=feature-request---.md">Request Feature</a>
+  </p>
+</div>
+
+
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#built-with">Built With</a></li>
+      </ul>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#roadmap">Roadmap</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+    <li><a href="#contact">Contact</a></li>
+    <li><a href="#acknowledgments">Acknowledgments</a></li>
+  </ol>
+</details>
+
+
+<!-- ABOUT THE PROJECT -->
+## About The Project
+
+<!-- [![Product Name Screen Shot][product-screenshot]](https://unraid.net) 
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p> -->
+
+### Built With
+
+* [![Unraid][Unraid]][Unraid-url]
+* [![Node.js][Node.js]][Node-url]
+* [![Nuxt][Nuxt.js]][Nuxt-url]
+* [![PHP][PHP]][PHP-url]
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- GETTING STARTED -->
+## Getting Started
+
+This section will guide you through the steps necessary to get the monorepo projects running and
+communicating with each other.
+
+### Prerequisites
+
+Make sure the following software is installed before proceeding.
+
+- Bash
+- Docker (for macOS folks, Orbstack works too)
+- [Node.js (v20)][Node-url]
+- [Just](https://github.com/casey/just)
+- An [Unraid][Unraid-url] server for development
+
+Next, create an SSH key if you haven't already.
+Once you have your key pair, add your public SSH key to your Unraid server:
+
+1. Log in to your Unraid development server.
+2. Use the navigation menu to go to 'Users'.
+3. Click on the user you logged in with (e.g. `root`)
+4. Paste your SSH public key into 'SSH authorized keys' and click 'Save'.
+
+### Installation
+
+1. Clone and enter the repo
+   ```sh
+   # Optionally, give the cloned folder a more specific name
+   gh repo clone unraid/api api-monorepo
+   cd api-monorepo
+   ```
+2. Run the monorepo setup command.
+   ```sh
+   just setup
+   ```
+   This will run installation scripts, container builds, and some git scripts to reduce noise (i.e. personal editor customizations, etc).
+3. Run the API container
+   ```sh
+   cd api
+   npm run container:start
+   ```
+4. This should bring you inside the API container. There, run the following command to start the server:
+   ```js
+   npm run dev
+   ```
+5. In another terminal, open the project and navigate to the web directory. Then, run the dev server:
+   ```sh
+   cd web
+   npm install # just in case
+   npm run dev
+   ```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+<!-- USAGE EXAMPLES -->
+## Usage
+
+Use this space to show useful examples of how a project can be used. Additional screenshots, code examples and demos work well in this space. You may also link to more resources.
+
+_For more examples, please refer to the [Documentation](https://docs.unraid.net/)_
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- ROADMAP -->
+<!-- ## Roadmap
+
+- [ ] Feature 1
+- [ ] Feature 2
+- [ ] Feature 3
+    - [ ] Nested Feature
+
+See the [open issues](https://github.com/unraid/api/issues) for a full list of proposed features (and known issues).
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p> -->
+
+<!-- CONTRIBUTING -->
+<!-- ## Contributing
+
+Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+
+If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+Don't forget to give the project a star! Thanks again!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+### Top contributors:
+
+<a href="https://github.com/unraid/api/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=unraid/api" alt="contrib.rocks image" />
+</a> -->
+
+
+
+<!-- LICENSE -->
+<!-- ## License
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p> -->
+
+
+<!-- CONTACT -->
+## Contact
+
+[@UnraidOfficial](https://twitter.com/UnraidOfficial) - support@unraid.net.com
+
+Project Link: [https://github.com/unraid/api](https://github.com/unraid/api)
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+<!-- ACKNOWLEDGMENTS -->
+## Acknowledgments
+
+* []()
+* []()
+* []()
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+
+
+<!-- MARKDOWN LINKS & IMAGES -->
+<!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->
+[contributors-shield]: https://img.shields.io/github/contributors/unraid/api.svg?style=for-the-badge
+[contributors-url]: https://github.com/unraid/api/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/unraid/api.svg?style=for-the-badge
+[forks-url]: https://github.com/unraid/api/network/members
+[stars-shield]: https://img.shields.io/github/stars/unraid/api.svg?style=for-the-badge
+[stars-url]: https://github.com/unraid/api/stargazers
+[issues-shield]: https://img.shields.io/github/issues/unraid/api.svg?style=for-the-badge
+[issues-url]: https://github.com/unraid/api/issues
+[license-shield]: https://img.shields.io/github/license/unraid/api.svg?style=for-the-badge
+[license-url]: https://github.com/unraid/api/blob/master/LICENSE.txt
+[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?style=for-the-badge&logo=linkedin&colorB=555
+[linkedin-url]: https://www.linkedin.com/company/unraid
+[product-screenshot]: images/screenshot.png
+[Nuxt.js]: https://img.shields.io/badge/Nuxt-002E3B?style=for-the-badge&logo=nuxtdotjs&logoColor=#00DC82
+[Node.js]: https://img.shields.io/badge/node.js-6DA55F?style=for-the-badge&logo=node.js&logoColor=white
+[PHP]: https://img.shields.io/badge/php-%23777BB4.svg?style=for-the-badge&logo=php&logoColor=white
+[Unraid]: https://img.shields.io/badge/unraid-%23F15A2C.svg?style=for-the-badge&logo=unraid&logoColor=white
+[Unraid-url]: https://unraid.net
+[Nuxt-url]: https://nuxt.com/
+[Node-url]: https://nodejs.org/
+[PHP-url]: https://php.net/
--- a/web/.env.example
+++ b/web/.env.example
@@ -4,4 +4,9 @@ VITE_UNRAID_NET=https://unraid.ddev.site
 VITE_OS_RELEASES="https://releases.unraid.net/os"
 VITE_CALLBACK_KEY=aNotSoSecretKeyUsedToObfuscateQueryParams
 VITE_ALLOW_CONSOLE_LOGS=true
-VITE_TAILWIND_BASE_FONT_SIZE=10
+# Base font size in pixels for Tailwind CSS. Used by the tailwind-rem-to-rem plugin to scale rem values.
+# This lets us use rem's in our css instead of pixels while remaining webgui-compatible without additional hacks.
+# This should match your root font size. Default: 16
+# For an Unraid Webgui deployment, set this to 10.
+VITE_TAILWIND_BASE_FONT_SIZE=16
+VITE_WEBGUI=http://localhost:3001
--- a/web/justfile
+++ b/web/justfile
@@ -0,0 +1,9 @@
+set fallback
+
+default:
+    @just --list --justfile {{justfile()}} --list-heading $'\nWeb project recipes:\n'
+    @just list-commands
+
+setup:
+    cp .env.example .env
+    npm install
				`@@ -0,0 +1 @@`
				<svg xmlns="http://www.w3.org/2000/svg" version="1.2" viewBox="0 0 1000 1000"><defs><linearGradient id="a" x1="-900" x2="-100" y1="-100" y2="-900" gradientUnits="userSpaceOnUse"><stop offset="0" stop-color="#e32929"/><stop offset="1" stop-color="#ff8d30"/></linearGradient></defs><path fill="url(#a)" d="M1000 500.1v376.4c0 57.5-43.4 110.1-100 120.9-8.4 1.6-17.1 2.5-25.6 2.5-250.1.1-500.2.1-750.3.1-61.3 0-114.8-47-122.8-108q-.3-2.1-.6-4.1-.2-2-.3-4.1-.2-2-.3-4v-4.1C0 624.9 0 374.2 0 123.5 0 66 43.4 13.3 100 2.6 108.4 1 117.1.1 125.6.1 375.9 0 626.2 0 876.5 0 934 0 986.7 43.4 997.4 100c1.5 8.4 2.5 17.1 2.5 25.6.1 124.8.1 249.7.1 374.5z"/><path fill="#fff" d="M481.6 392.1h36.5v216.2h-36.5zm-356 0h36.5v216.2h-36.5zm178 242h36.5v82.5h-36.5zm-89.3-92.7h36.5v133.7h-36.5zm178 0h36.5V675h-36.5zm445.8-149.3h36.5v216.1h-36.5zm-178-107.8h36.5v82.6h-36.5zm89.3 41.5h36.5v133.1h-36.5zm-178.6 0h36.5v133h-36.5z"/></svg>