zaine/quartz
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update plugin CLI and troubleshooting for pre-built distribution

Browse Source
This commit is contained in:
saberzero1
2026-04-28 00:03:53 +02:00
parent 9fcc3f260c
commit a76af2866b
2 changed files with 15 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/cli/plugin.md
View File

@@ -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. 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`: If `plugin install` fails, hangs, or OOMs on your machine, lower the concurrency with `--concurrency` / `-c`:
```shell ```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 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: To switch a local plugin back to a git source:

6
docs/troubleshooting.md
View File

@@ -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 ### 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. 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. 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 ### `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. 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`: Lower the parallelism with `--concurrency` / `-c`: