Unified Quartz development enviroment.
  • TypeScript 96.2%
  • Just 2.1%
  • JavaScript 1.5%
  • Nix 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Emile Bangma 46de13c4d7
Merge pull request #8 from quartz-community/dev-mode/explorer-recent-notes-repro
test(repro): explorer squeezes recent notes in the left sidebar
2026-11-10 21:19:42 +01:00
.claude/skills release: warn when a repo's package-lock.json drifts from the workspace 2026-11-08 19:11:46 +01:00
.github/workflows ci: typecheck, test and lint don't rebuild (--only), report every failure (--continue=always), and dist/ is checked before sites are built 2026-11-09 18:04:11 +01:00
docs test: built-in core processing repro, smoke checks for untitled pages and published drafts, verbose builds 2026-11-07 13:15:39 +01:00
e2e test(repro): explorer squeezes recent notes in the left sidebar (fixed in explorer) 2026-11-10 20:30:17 +01:00
empty-stub feat: initial setup 2026-07-22 21:11:50 +02:00
scripts fix(sandbox): restore a sandbox's node_modules link when a build replaced it; theme packages repros use are root devDependencies 2026-11-10 00:26:40 +01:00
test-results feat: integration testing 2026-07-23 15:32:56 +02:00
tests fix(sandbox): restore a sandbox's node_modules link when a build replaced it; theme packages repros use are root devDependencies 2026-11-10 00:26:40 +01:00
.editorconfig feat: initial setup 2026-07-22 21:11:50 +02:00
.gitignore feat: sandboxed Quartz site builds and NixOS-safe browser resolution 2026-11-07 02:44:46 +01:00
.node-version chore: pin Node 22.23.4 (.node-version used by the flake, engines, check-env and CI); update nixpkgs 2026-11-07 20:41:32 +01:00
.npmrc feat: initial setup 2026-07-22 21:11:50 +02:00
.pnpmfile.cjs fix(sandbox): restore a sandbox's node_modules link when a build replaced it; theme packages repros use are root devDependencies 2026-11-10 00:26:40 +01:00
AGENTS.md fix(sandbox): restore a sandbox's node_modules link when a build replaced it; theme packages repros use are root devDependencies 2026-11-10 00:26:40 +01:00
CLAUDE.md chore: agents.md 2026-07-23 13:39:30 +02:00
dev.yaml feat: add quartz-community/tui as a standalone repo (own npm lockfile; dependencies need Node 24/bun), checked by just validate 2026-11-07 23:29:38 +01:00
flake.lock chore: pin Node 22.23.4 (.node-version used by the flake, engines, check-env and CI); update nixpkgs 2026-11-07 20:41:32 +01:00
flake.nix chore: pin Node 22.23.4 (.node-version used by the flake, engines, check-env and CI); update nixpkgs 2026-11-07 20:41:32 +01:00
justfile just commit-files: paths with spaces work (quoted positional arguments) 2026-11-09 04:33:42 +01:00
KNOWN_LIMITATIONS.md test: repros for Quartz layout/coupling fixes; show plugin attribution in inspect 2026-11-07 03:09:56 +01:00
LICENSE Batman 2026-07-22 20:03:54 +02:00
package.json fix(sandbox): restore a sandbox's node_modules link when a build replaced it; theme packages repros use are root devDependencies 2026-11-10 00:26:40 +01:00
pnpm-workspace.yaml feat: add quartz-community/tui as a standalone repo (own npm lockfile; dependencies need Node 24/bun), checked by just validate 2026-11-07 23:29:38 +01:00
README.md chore: pin Node 22.23.4 (.node-version used by the flake, engines, check-env and CI); update nixpkgs 2026-11-07 20:41:32 +01:00
tsconfig.json feat: initial setup 2026-07-22 21:11:50 +02:00
turbo.json fix(turbo): typecheck waits for its dependencies' builds (turbo's ^build can't see workspace deps; just check raced tsup emptying types/dist) 2026-11-08 01:38:28 +01:00
vitest.config.ts feat: workspace improvements — shared lib, reliability, DX, testing 2026-08-21 18:09:00 +02:00

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 transformers
  • content-pipeline: All transformers and filters
  • ui: All component plugins
  • full (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

  1. Clone the workspace: just setup (or just add-plugin <name> for a single plugin)
  2. Edit plugin source in repos/<name>/src/
  3. Build: just build-plugin <name>
  4. Test: just test-plugin <name>
  5. 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:

  1. Add a changeset: create a .changeset/<name>.md file
  2. Commit and push to main
  3. CI creates a "Version Package" PR
  4. Merge the PR — CI publishes to npm
  5. 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.cjs rewrites github:quartz-community/* to workspace:* for local linking.
  • Turbo pipeline: turbo.json defines build order and affected runs. The dependency graph is created by scripts/generate-turbo-graph.ts based on plugin dependencies.

Troubleshooting

  • No lockfile: pnpm-lock.yaml is intentionally not committed. Each setup recreates it.
  • Install skips scripts: .npmrc sets ignore-scripts=true. If a package needs a postinstall, add it to onlyBuiltDependencies in pnpm-workspace.yaml.
  • Missing repos: Run just setup or just add-plugin <name> to clone required packages.
  • Manifest sync: just sync-manifest requires gh CLI and GITHUB_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