quartz/docs/ci-cd.md

CI/CD Pipeline Configuration

This document describes how to configure CI/CD pipelines for Quartz projects using the Git-based plugin system.

Overview

Quartz uses a Git-based plugin system with a lockfile (quartz.lock.json) to track exact plugin versions. When building in CI/CD environments, you need to:

1. Install npm dependencies (including @quartz-community/types devDependency)
2. Install Git-based plugins from the lockfile
3. Build the Quartz site

Required Steps

1. Install npm dependencies

npm ci

This installs all dependencies including @quartz-community/types which is required for TypeScript compilation of the plugins.

2. Install Git-based plugins

npx quartz plugin install

This reads quartz.lock.json and clones the exact plugin versions specified.

3. Build the site

npx quartz build

Example CI/CD Configurations

GitHub Actions

name: Build and Deploy

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Install Quartz plugins
        run: npx quartz plugin install

      - name: Build Quartz
        run: npx quartz build

      - name: Deploy
        # Add your deployment step here

GitLab CI

stages:
  - build
  - deploy

build:
  stage: build
  image: node:22
  cache:
    paths:
      - node_modules/
      - .quartz/plugins/
  script:
    - npm ci
    - npx quartz plugin install
    - npx quartz build
  artifacts:
    paths:
      - public/

Netlify

For Netlify, use a custom build command:

npm ci && npx quartz plugin install && npx quartz build

Add this to your netlify.toml:

[build]
  command = "npm ci && npx quartz plugin install && npx quartz build"
  publish = "public"

[build.environment]
  NODE_VERSION = "22"

Vercel

For Vercel, configure the build settings:

• Build Command: npm ci && npx quartz plugin install && npx quartz build
• Output Directory: public
• Node.js Version: 22.x

Docker

The included Dockerfile already handles plugin installation:

FROM node:22-slim AS builder
WORKDIR /usr/src/app
COPY package.json .
COPY package-lock.json* .
RUN npm ci

# Install plugins from lockfile
COPY quartz.lock.json .
RUN npx quartz plugin install

FROM node:22-slim
WORKDIR /usr/src/app
COPY --from=builder /usr/src/app/ /usr/src/app/
COPY . .
CMD ["npx", "quartz", "build", "--serve"]

Important Notes

Lockfile Must Be Committed

Ensure quartz.lock.json is committed to your repository:

git add quartz.lock.json
git commit -m "Add plugin lockfile"

Cache Considerations

For faster builds, cache both node_modules and .quartz/plugins/:

GitHub Actions:

- name: Cache plugins
  uses: actions/cache@v4
  with:
    path: .quartz/plugins
    key: ${{ runner.os }}-plugins-${{ hashFiles('quartz.lock.json') }}

GitLab CI:

cache:
  paths:
    - node_modules/
    - .quartz/plugins/
  key: ${CI_COMMIT_REF_SLUG}

Plugin Updates in CI

To update plugins automatically in CI:

- name: Update plugins
  run: npx quartz plugin update

- name: Commit updated lockfile
  run: |
    git config user.name "CI Bot"
    git config user.email "ci@example.com"
    git add quartz.lock.json
    git diff --quiet && git diff --staged --quiet || git commit -m "Update plugins"
    git push    

Troubleshooting

"Cannot find module '@quartz-community/types'"

Ensure npm ci runs before npx quartz plugin install. The types package must be installed as a devDependency.

"No quartz.lock.json found"

Run npx quartz plugin add <repo> locally first to create the lockfile, then commit it.

"Plugin directory exists, skipping"

This is expected when caching .quartz/plugins/. The installer will skip existing plugins that match the lockfile.

Slow builds

Enable caching for both node_modules and .quartz/plugins/. The plugin installation requires cloning Git repositories which can be slow.

Summary

The key change from traditional npm-based plugin systems:

Step	Traditional	Git-based
Install deps	npm ci	npm ci
Install plugins	(included in npm ci)	npx quartz plugin install
Build	npx quartz build	npx quartz build

Always run npx quartz plugin install after npm ci and before npx quartz build.