- TypeScript 96.2%
- Just 2.1%
- JavaScript 1.5%
- Nix 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .claude/skills | ||
| .github/workflows | ||
| docs | ||
| e2e | ||
| empty-stub | ||
| scripts | ||
| test-results | ||
| tests | ||
| .editorconfig | ||
| .gitignore | ||
| .node-version | ||
| .npmrc | ||
| .pnpmfile.cjs | ||
| AGENTS.md | ||
| CLAUDE.md | ||
| dev.yaml | ||
| flake.lock | ||
| flake.nix | ||
| justfile | ||
| KNOWN_LIMITATIONS.md | ||
| LICENSE | ||
| package.json | ||
| pnpm-workspace.yaml | ||
| README.md | ||
| tsconfig.json | ||
| turbo.json | ||
| vitest.config.ts | ||
Quartz v5 Dev-Mode Workspace
Overview
This repository provides a unified development workspace for Quartz v5 core, infrastructure packages, and first-party plugins. It is designed to clone the ecosystem into a single pnpm workspace so changes can be validated across repos without running a Quartz site.
Prerequisites
- Node.js 22+
- pnpm 10+
- git
- Optional: Nix (for a fully reproducible environment)
Quick Start
git clone https://github.com/quartz-community/dev-mode.git
cd dev-mode
just setup # clones all repos, installs, builds
With Nix:
nix develop # drops into shell with Node (pinned in .node-version), pnpm, just, libvips
just setup
To build only what changed:
just build-affected
Available Presets
minimal: Core + infrastructure + essential transformerscontent-pipeline: All transformers and filtersui: All component pluginsfull(default): Everything
just setup minimal
just setup content-pipeline
Common Workflows
just add-plugin graph # add a single plugin
just remove-plugin graph # remove a plugin
just sync # pull latest for all repos
just validate # check workspace integrity
just typecheck # cross-repo type checking
just test-plugin search # test a specific plugin
just build-plugin graph # build a specific plugin
just check # full suite: typecheck + lint + format + test
Run just with no arguments to see all available commands.
Git Workflow
Always use just commands for git operations. Raw git commit / git push will skip formatting checks.
just commit <repo> "<message>" # stage (excluding dist/), commit
just push # runs full checks first, then pushes all dirty repos
just dirty # show which repos have uncommitted changes
just push runs just check (typecheck + lint + format + test) before pushing. This prevents unformatted code from reaching the remote.
Individual repos also have their own formatting:
cd repos/quartz && npm run format # prettier --write
cd repos/quartz && npm run check # tsc --noEmit + prettier --check
Plugin Development
Working on an existing plugin
- Clone the workspace:
just setup(orjust add-plugin <name>for a single plugin) - Edit plugin source in
repos/<name>/src/ - Build:
just build-plugin <name> - Test:
just test-plugin <name> - Type-check:
just typecheck
Testing with a live Quartz site
just dev # starts watcher + Quartz dev server with live-reload
Edit plugin code, changes rebuild automatically, browser refreshes.
Creating a new plugin
Use the plugin template:
gh repo create quartz-community/<name> --template quartz-community/quartz-plugin-template
just add-plugin <name>
Publishing
Plugins use changesets for versioning:
- Add a changeset: create a
.changeset/<name>.mdfile - Commit and push to
main - CI creates a "Version Package" PR
- Merge the PR — CI publishes to npm
- Update Quartz lockfile:
just update-quartz-lockfile && just push
How It Works
- pnpm workspace:
repos/*is a single workspace. Shared dependencies are managed at the root. - Override hook:
.pnpmfile.cjsrewritesgithub:quartz-community/*toworkspace:*for local linking. - Turbo pipeline:
turbo.jsondefines build order and affected runs. The dependency graph is created byscripts/generate-turbo-graph.tsbased on plugin dependencies.
Troubleshooting
- No lockfile:
pnpm-lock.yamlis intentionally not committed. Each setup recreates it. - Install skips scripts:
.npmrcsetsignore-scripts=true. If a package needs a postinstall, add it toonlyBuiltDependenciesinpnpm-workspace.yaml. - Missing repos: Run
just setuporjust add-plugin <name>to clone required packages. - Manifest sync:
just sync-manifestrequiresghCLI andGITHUB_TOKEN. - just not found: Install via your system package manager or use the Nix flake (
nix develop).
For Agent Tools
See AGENTS.md (loaded via CLAUDE.md) for workspace rules and the agent toolkit, docs/ARCHITECTURE.md
for how Quartz's pipeline fits together, and .claude/skills/ for step-by-step workflows
(plugin changes, bug repros, E2E tests, CSS changes, data flow, releases). just overview is the
one-screen starting point.
Sandboxed sites, repros and inspection
just site-build fixture:bug-repro # isolated build (never touches repos/quartz) → .dev/sites/
just site-smoke fixture:bug-repro # broken links, console/page/SPA errors, mobile overflow
just repro-new 1234-short-name --issue jackyzha0/quartz#1234 # self-contained bug repro
just repro-check 1234-short-name --expect-fail # confirm it reproduces
just inspect fixture:bug-repro docs/ --screenshot # look at a page
just visual-baseline && just visual-check # before/after CSS regression report
just catalog show graph # what a plugin does / reads / writes
just release-status # what needs releasing
License
MIT