From a76af2866ba6d50966279522b7f4dd66241a6d38 Mon Sep 17 00:00:00 2001 From: saberzero1 Date: Tue, 28 Apr 2026 00:03:53 +0200 Subject: [PATCH] docs: update plugin CLI and troubleshooting for pre-built distribution --- docs/cli/plugin.md | 10 +++++++++- docs/troubleshooting.md | 6 ++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/cli/plugin.md b/docs/cli/plugin.md index e6f0531..ba42893 100644 --- a/docs/cli/plugin.md +++ b/docs/cli/plugin.md @@ -142,6 +142,9 @@ npx quartz plugin install --latest By default, `plugin install` and `plugin add` clone, fetch, and build plugins in parallel across all your CPU cores. On memory-constrained machines (low-end laptops, Raspberry Pi, small VPS instances, restrictive CI runners) this can exhaust RAM or overwhelm the system because each worker may kick off its own `npm install` / `npm run build` at the same time. +> [!note] +> Most community plugins now ship with a pre-built `dist/` directory. When Quartz finds this, it skips the installation and build steps entirely, making the process much faster and lighter on resources. This section is primarily relevant for plugins in development or those that don't provide pre-built distribution. + If `plugin install` fails, hangs, or OOMs on your machine, lower the concurrency with `--concurrency` / `-c`: ```shell @@ -208,7 +211,12 @@ For local plugin development or airgapped environments, you can add a plugin fro npx quartz plugin add ./my-local-plugin ``` -Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `install --latest`, local plugins are rebuilt (npm install + npm run build) without any git operations. The `install --latest --dry-run` command will show local plugins with a "local" status instead of checking for remote updates. +Local plugins are symlinked into `.quartz/plugins/`, so changes reflect immediately. When you run `install --latest`, local plugins are rebuilt (npm install + npm run build) without any git operations. + +> [!note] +> Local symlinked plugins typically use this build-on-install fallback because the `dist/` directory is usually gitignored during development. + +The `install --latest --dry-run` command will show local plugins with a "local" status instead of checking for remote updates. To switch a local plugin back to a git source: diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 04db9d0..ba06cfc 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -64,6 +64,9 @@ This means the plugin is referenced in `quartz.ts` but not installed. Either: ### Plugins fail to build on a fresh clone +> [!important] +> Most community plugins now ship with a pre-built `dist/` directory and skip the build step entirely. The build failure scenario described below mainly applies to plugins in development or older plugins that haven't adopted pre-built distribution. + On a brand-new clone, `npx quartz plugin install` (or the plugin step run automatically by `npx quartz create`) may report a handful of plugins failing to build — typically around 10–15 of them. The git clone and checkout still succeed, but `npm run build` inside the plugin errors out. This happens because `quartz.lock.json` pins each plugin to a specific commit, and those older plugin commits may have been authored against earlier versions of `@quartz-community/types` / `@quartz-community/utils` whose published artifacts are no longer shipped in the dependency's git repo. The plugin's `tsup`/`tsc` build then cannot resolve the expected type declarations. @@ -78,6 +81,9 @@ This rewrites `quartz.lock.json` with the newest commits (which in turn pin newe ### `plugin install` hangs, OOMs, or fails on low-end hardware +> [!note] +> Pre-built plugins are much faster and lighter on resources because they skip the `npm install` and `npm run build` steps. + By default, `npx quartz plugin install` clones, fetches, and builds plugins in parallel across all your CPU cores. Each parallel worker may run its own `npm install` and `npm run build`, which is memory-intensive. On low-end laptops, Raspberry Pi, small VPS instances, or restrictive CI runners this can exhaust RAM, trigger the OOM killer, or make the system appear to hang. Lower the parallelism with `--concurrency` / `-c`: