diff --git a/api/docs/developer/workflows.md b/api/docs/developer/workflows.md index f5325341a..bf07d2bb2 100644 --- a/api/docs/developer/workflows.md +++ b/api/docs/developer/workflows.md @@ -62,15 +62,18 @@ To build all packages in the monorepo: pnpm build ``` -### Watch Mode Building +### Plugin Building (Docker Required) -For continuous building during development: +The plugin build requires Docker. This command automatically builds all dependencies (API, web) before starting Docker: ```bash -pnpm build:watch +cd plugin +pnpm run docker:build-and-run +# Then inside the container: +pnpm build ``` -This is useful when you want to see your changes reflected without manually rebuilding. This will also allow you to install a local plugin to test your changes. +This serves the plugin at `http://YOUR_IP:5858/` for installation on your Unraid server. ### Package-Specific Building diff --git a/api/scripts/build.ts b/api/scripts/build.ts index 9e7082e0c..a790f3803 100755 --- a/api/scripts/build.ts +++ b/api/scripts/build.ts @@ -83,6 +83,10 @@ try { if (parsedPackageJson.dependencies?.[dep]) { delete parsedPackageJson.dependencies[dep]; } + // Also strip from peerDependencies (npm doesn't understand workspace: protocol) + if (parsedPackageJson.peerDependencies?.[dep]) { + delete parsedPackageJson.peerDependencies[dep]; + } }); } diff --git a/package.json b/package.json index 55c76803a..3401e2c37 100644 --- a/package.json +++ b/package.json @@ -7,7 +7,7 @@ "build:watch": "pnpm -r --parallel --filter '!@unraid/ui' build:watch", "codegen": "pnpm -r codegen", "i18n:extract": "pnpm --filter @unraid/api i18n:extract && pnpm --filter @unraid/web i18n:extract", - "dev": "pnpm -r dev", + "dev": "pnpm -r --parallel dev", "unraid:deploy": "pnpm -r unraid:deploy", "test": "pnpm -r test", "test:watch": "pnpm -r --parallel test:watch", diff --git a/packages/unraid-shared/package.json b/packages/unraid-shared/package.json index 9c4205bd5..d5c908528 100644 --- a/packages/unraid-shared/package.json +++ b/packages/unraid-shared/package.json @@ -18,7 +18,8 @@ "dist" ], "scripts": { - "build": "rimraf dist && tsc --project tsconfig.build.json", + "build": "pnpm clean && tsc --project tsconfig.build.json", + "clean": "rimraf dist", "prepare": "npm run build", "test": "vitest run", "test:watch": "vitest", diff --git a/plugin/README.md b/plugin/README.md index 71634a4d7..934dfadc7 100644 --- a/plugin/README.md +++ b/plugin/README.md @@ -4,50 +4,32 @@ Tool for building and testing Unraid plugins locally as well as packaging them f ## Development Workflow -### 1. Watch for Changes +### 1. Build the Plugin -The watch command will automatically sync changes from the API, UI components, and web app into the plugin source: - -```bash -# Start watching all components -pnpm run watch:all - -# Or run individual watchers: -pnpm run api:watch # Watch API changes -pnpm run ui:watch # Watch Unraid UI component changes -pnpm run wc:watch # Watch web component changes -``` - -This will copy: - -- API files to `./source/dynamix.unraid.net/usr/local/unraid-api` -- UI components to `./source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/unraid-components` -- Web components to the same UI directory - -### 2. Build the Plugin +> **Note:** Building the plugin requires Docker. Once your changes are ready, build the plugin package: ```bash -# Build using Docker - on non-Linux systems +# Start Docker container (builds dependencies automatically) pnpm run docker:build-and-run -# Or build with the build script -pnpm run build:validate +# Inside the container, build the plugin +pnpm build ``` -This will create the plugin files in `./deploy/release/` +This will: -### 3. Serve and Install +1. Build the API release (`api/deploy/release/`) +2. Build the web standalone components (`web/dist/`) +3. Start Docker container with HTTP server on port 5858 +4. Build the plugin package (when you run `pnpm build`) -Start a local HTTP server to serve the plugin files: +The plugin files will be created in `./deploy/` and served automatically. -```bash -# Serve the plugin files -pnpm run http-server -``` +### 2. Install on Unraid -Then install the plugin on your Unraid development machine by visiting: +Install the plugin on your Unraid development machine by visiting: `http://SERVER_NAME.local/Plugins` @@ -59,8 +41,7 @@ Replace `SERVER_NAME` with your development machine's hostname. ## Development Tips -- Run watchers in a separate terminal while developing -- The http-server includes CORS headers for local development +- The HTTP server includes CORS headers for local development - Check the Unraid system log for plugin installation issues ## Environment Setup @@ -81,22 +62,10 @@ Replace `SERVER_NAME` with your development machine's hostname. ### Build Commands -- `build` - Build the plugin package -- `build:validate` - Build with environment validation +- `build` - Build the plugin package (run inside Docker container) - `docker:build` - Build the Docker container - `docker:run` - Run the builder in Docker -- `docker:build-and-run` - Build and run in Docker - -### Watch Commands - -- `watch:all` - Watch all component changes -- `api:watch` - Watch API changes -- `ui:watch` - Watch UI component changes -- `wc:watch` - Watch web component changes - -### Server Commands - -- `http-server` - Serve the plugin files locally +- `docker:build-and-run` - Build dependencies and start Docker container ### Environment Commands diff --git a/plugin/scripts/dc.sh b/plugin/scripts/dc.sh index 31737035b..b0a4dc78a 100755 --- a/plugin/scripts/dc.sh +++ b/plugin/scripts/dc.sh @@ -33,6 +33,23 @@ if [ ! -d "$WEB_DIST_DIR" ]; then mkdir -p "$WEB_DIST_DIR" fi +# Build dependencies before starting Docker (always rebuild to prevent staleness) +echo "Building dependencies..." + +echo "Building API release..." +if ! (cd .. && pnpm --filter @unraid/api build:release); then + echo "Error: API build failed. Aborting." + exit 1 +fi + +echo "Building web standalone..." +if ! (cd .. && pnpm --filter @unraid/web build); then + echo "Error: Web build failed. Aborting." + exit 1 +fi + +echo "Dependencies built successfully." + # Stop any running plugin-builder container first echo "Stopping any running plugin-builder containers..." docker ps -q --filter "name=${CONTAINER_NAME}" | xargs -r docker stop diff --git a/readme.md b/readme.md index aa84b94f0..65bbb4391 100644 --- a/readme.md +++ b/readme.md @@ -210,22 +210,34 @@ Once you have your key pair, add your public SSH key to your Unraid server: ### Development Modes -The project supports two development modes: +#### Mode 1: Local Plugin Build (Docker) -#### Mode 1: Build Watcher with Local Plugin - -This mode builds the plugin continuously and serves it locally for installation on your Unraid server: +Build and test a full plugin locally using Docker: ```sh -# From the root directory (api/) -pnpm build:watch +cd plugin +pnpm run docker:build-and-run +# Then inside the container: +pnpm build ``` -This command will output a local plugin URL that you can install on your Unraid server by navigating to Plugins → Install Plugin. Be aware it will take a *while* to build the first time. +This builds all dependencies (API, web), starts a Docker container, and serves the plugin at `http://YOUR_IP:5858/`. Install it on your Unraid server via Plugins → Install Plugin. -#### Mode 2: Development Servers +#### Mode 2: Direct Deployment -For active development with hot-reload: +Deploy individual packages directly to an Unraid server for faster iteration: + +```sh +# Deploy API changes +cd api && pnpm unraid:deploy + +# Deploy web changes +cd web && pnpm unraid:deploy +``` + +#### Mode 3: Development Servers + +For active development with hot-reload (no Unraid server needed): ```sh # From the root directory - runs all dev servers concurrently @@ -238,22 +250,11 @@ Or run individual development servers: # API server (GraphQL backend at http://localhost:3001) cd api && pnpm dev -# Web interface (Nuxt frontend at http://localhost:3000) +# Web interface (Nuxt frontend at http://localhost:3000) cd web && pnpm dev ``` -### Building the Full Plugin - -To build the complete plugin package (.plg file): - -```sh -# From the root directory (api/) -pnpm build:plugin - -# The plugin will be created in plugin/dynamix.unraid.net.plg -``` - -To deploy the plugin to your Unraid server: +### Deploying to Unraid ```sh # Replace SERVER_IP with your Unraid server's IP address