Skip to main content

​
SDK docs generated-content pipeline

The sdk/ section has a sync script (sync-sdk-docs.ts) that auto-generates certain documentation files from source files. This prevents manual drift and ensures code examples are type-checked. Writing standards: Follow the canonical standards in writing-standards-dev-docs. Do not use em-dashes or Title Case headings even if older SDK pages do.

​
When to use

  • Editing anything under sdk/, snippets/sdk/, or src/sdk/
  • Adding a new code example to SDK docs
  • Troubleshooting why an SDK doc edit was reverted
  • Understanding what can and cannot be hand-edited

​
The one rule

Any file whose first line is: 
{/* DO NOT EDIT - Generated from <source> by sync-sdk-docs.ts */}
is build output. Hand edits are silently overwritten on the next sync. The header names the source — trust it.

​
Regeneration command

pnpm run sync-sdk   # = tsc -p src && npx tsx sync-sdk-docs.ts
The script warns when the installed @zapier/zapier-sdk or @zapier/zapier-sdk-cli packages are behind the latest npm release. Follow its advice (pnpm update --latest <pkg>, re-run sync) when freshness matters. Treat package updates as dependency changes — get approval before running installs.

​
Source to output map

Output in snippets/sdk/SourceTo change it
example-*.mdx, cli-*.mdx (code snippets), installation.mdx, init-*.mdxsrc/sdk/snippets/<same-name>.ts or .shEdit the source, run pnpm run sync-sdk
api-reference.mdx, experimental-api-reference.mdxREADME of node_modules/@zapier/zapier-sdkUpstream: change the SDK package’s README, publish, update the package here, re-sync
cli-commands.mdx, experimental-cli-commands.mdxREADME of node_modules/@zapier/zapier-sdk-cliSame upstream path, CLI package
setup-prompt-cards.mdx, setup-prompt-display.mdxsrc/sdk/setup-prompt.txt + src/sdk/web-setup-prompt.txtEdit the .txt prompts, re-sync
cli-setup-prompt-cards.mdx, cli-setup-prompt-display.mdxsrc/sdk/cli-prompt.txt + src/sdk/cli-web-prompt.txtEdit the .txt prompts, re-sync
Hand-maintained exceptions in snippets/sdk/ (no DO NOT EDIT header):
  • vars.mdx — re-exports appCount / appCountExact from /snippets/app-directory-stats.mdx. Editable, rarely needs it.
Hand-written pages: Everything under sdk/*.mdx (the actual pages) is hand-written and freely editable. sdk/reference.mdx and sdk/cli-reference.mdx are thin shells that import generated snippets — edit their framing prose, but never inline reference content into them.

​
How the experimental split works

sync-sdk-docs.ts splits the package READMEs by H2 section: headings ending in (Experimental) route to the experimental-* outputs; everything else goes to the stable outputs. Whether a method or command appears in the stable or experimental reference is decided upstream in the package README, not in this repo.

​
Adding a new code example

  1. Create a new source file in src/sdk/snippets/ (e.g., example-foo.ts or example-foo.sh).
  2. File extension determines the code fence language (.ts → typescript, .sh → bash).
  3. Run pnpm run sync-sdk — this type-checks .ts files and generates snippets/sdk/example-foo.mdx.
  4. Import the generated component in the consuming page:
import ExampleFoo from "/snippets/sdk/example-foo.mdx";

<ExampleFoo />
Follow the code example standards in code-examples.

​
Pre-flight before any edit

  1. head -1 the target file. DO NOT EDIT header → find the source in the table above.
  2. If the source is a package README → the change is upstream; report it in your summary instead of editing locally.
  3. After regenerating, git diff and confirm only the intended snippets changed. A stale installed package version can produce unrelated reference churn — flag it instead of committing the churn.

​
App count variables

Do not hardcode “8,000+ apps” in prose. Import from /snippets/sdk/vars.mdx: 
import { appCount, appCountExact } from "/snippets/sdk/vars.mdx";

Connect to {appCount} apps.
A literal count appears only inside generated content and one legacy spot — do not add new ones.