Deploy notes

Audience: LLM agents working in this repository. Companion doc: none — repo-maintenance only. Verified in: iter/docs-polish-dx

Use this document when deployment behavior or CI build commands are involved. Deployment configuration for demo.grist-widgets.com (Cloudflare Pages) is not documented in this repo — it lives in the Cloudflare dashboard.

Expected deploy targets

This repository is structured so that at minimum these artifacts are deployable:

• docs site from apps/docs
• widgets app from apps/playground
• template app from templates/grist-widget-template-vite

Cloudflare Pages (3 projects)

Recommended setup is one Pages project per target:

• docs project
• widgets project
• templates project

The safest default is:

• set Root directory to repository root
• use pnpm --filter ... commands with real workspace names
• set Build output directory to a path relative to repository root

docs project

• Build command:

pnpm install --frozen-lockfile && pnpm build:docs

• Build output directory:

apps/docs/.vitepress/dist

widgets project

Use this command even if widgets currently builds without importing core directly. It prevents future breakages once widgets starts using grist-widget-sdk.

• Build command:

pnpm install --frozen-lockfile && pnpm build:playground

• Build output directory:

apps/playground/dist

templates project

Template code imports grist-widget-sdk, so core must be built first.

• Build command:

pnpm install --frozen-lockfile && pnpm --filter grist-widget-sdk build && pnpm --filter grist-widget-template-vite build

• Build output directory:

templates/grist-widget-template-vite/dist

Common Cloudflare errors and fixes

• No projects matched the filters: the --filter value does not match package.json:name.
• Output directory ".../.../dist" not found: Root directory + output path are duplicated. If Root is already apps/playground, output should be dist (not apps/playground/dist).
• Cannot find module 'grist-widget-sdk': build grist-widget-sdk first in the same command chain.
• No Wrangler configuration file found and No functions dir at /functions found: expected for static Pages deployments.

Build commands (workspace-safe)

From repository root:

pnpm build        # all workspaces except docs
pnpm build:docs   # VitePress only

Per workspace:

pnpm build:docs
pnpm build:playground

Build ordering guarantees

turbo.json uses:

• build.dependsOn: ["^build"]
• test.dependsOn: ["^build"]

This ensures dependent apps build against freshly built upstream workspace packages such as grist-widget-sdk.

Static hosting notes

• apps/playground/public/_redirects enables SPA fallback routing for static hosting.
• apps/docs outputs static docs from VitePress to .vitepress/dist.

Agent checklist before touching deploy config

• Confirm workspace/package names still match commands.
• Confirm output paths used by hosting provider still match build output.
• Confirm no deploy instructions reference removed directories.