Manually migrates legacy `nango.yaml` Nango projects to Zero YAML TypeScript by generating `models.ts`, `index.ts`, package/tsconfig scaffolding, and wrapping legacy scripts in `createSync()`, `createAction()`, or `createOnEvent()`. Use when a Nango repo still has `nango.yaml` and needs manual Zero YAML migration.
Instrucciones de origen · Vista previa de solo lectura
name
migrating-to-zero-yaml
description
Manually migrates legacy `nango.yaml` Nango projects to Zero YAML TypeScript by generating `models.ts`, `index.ts`, package/tsconfig scaffolding, and wrapping legacy scripts in `createSync()`, `createAction()`, or `createOnEvent()`. Use when a Nango repo still has `nango.yaml` and needs manual Zero YAML migration.
Migrating to Zero YAML
This skill replaces the old CLI migrator with an LLM-driven mechanical migration. Keep behavior as close as possible to the existing YAML project, then validate and stop. Do not turn this into a broader cleanup unless the user asks.
Critical rule
Do not tell the user to run nango migrate-to-zero-yaml.
Perform the migration manually in code.
Preserve existing behavior first.
Do not opportunistically migrate lastSyncDate, syncType, trackDeletes, or validation patterns unless the user asks or compilation forces you to touch them.
If the repo is already Zero YAML, stop and switch to a regular Zero YAML refactor workflow instead of forcing a migration.
Preconditions
Confirm you are in the Nango project root and nango.yaml exists.
Make sure there is a rollback path before destructive edits (git branch/commit or external backup).
Read nango.yaml and inventory:
integrations
syncs
actions
on-event handlers
models
Inspect the existing TypeScript files that those YAML entries point to.
Keep the migration mechanical. Avoid redesigning APIs, renaming scripts, or changing business logic.
End state you are aiming for
The migrated project should have:
package.json
tsconfig.json
root models.ts
root index.ts
integration files exporting createSync(), createAction(), or createOnEvent()
helper files importing Nango runtime types from nango
no nango.yaml in the final migrated state
Migration workflow
Read nango.yaml and build a migration inventory.
Create or update Zero YAML scaffolding:
package.json
tsconfig.json
Generate models.ts from the YAML models.
Rewrite each sync file into createSync(...).
Rewrite each action file into createAction(...).
Rewrite each lifecycle handler into createOnEvent(...).
Generate index.ts side-effect imports for every migrated script.
Fix helper-file imports and small TypeScript breakages.
Compile and validate.
Remove nango.yaml only after the replacement project is in place and there is still a rollback path outside the file.
Scaffolding rules
package.json
If the project does not have a package file, create one. If it already exists, preserve existing fields and add the Zero YAML essentials:
type: "module"
engines.node: ">=20.0"
scripts:
compile: "nango compile"
dev: "nango dev"
devDependencies.nango
devDependencies.zod
Prefer preserving the repo's package manager and existing workspace fields.
tsconfig.json
Use the standard Zero YAML TypeScript config shape:
any -> z.any() or z.unknown() if you need a safer fallback
optional field -> .optional()
array -> z.array(...)
nested object -> nested z.object(...)
union -> z.union([...])
model reference -> reuse the referenced schema
dynamic object fields -> z.record(...) or .catchall(...)
Practical rule: if the old YAML model is hard to express exactly, preserve migration momentum with the broadest safe schema that still lets the project compile. Tighten later only if needed.
Define models in dependency order. If you hit circular references, use z.lazy(() => ModelName).
Rewrite syncs
For each YAML sync, keep the existing file path when possible and wrap the current default-exported function in createSync(...).
Map YAML config to Zero YAML config like this:
description -> description
version -> version (default to 0.0.1 if missing)
runs -> frequency
auto_start -> autoStart
sync_type -> syncType
track_deletes -> trackDeletes
endpoints -> endpoints
scopes -> scopes
webhook subscriptions -> webhookSubscriptions
YAML input model -> metadata
YAML output models -> models
existing default export function body -> exec
If no YAML input model exists for the sync, default metadata to z.object({}) for migration parity.
If the file exports onWebhookPayloadReceived, move that function into the createSync(...) config as onWebhook.
Search the rest of the repo for TypeScript helper files outside the migrated integration entrypoints.
If they import Nango runtime types from old model files, move those imports to nango and leave model imports in place only for actual model schemas/types.
Do not rewrite unrelated business logic in helper files.
Keep the migration parity-first
The manual migration should behave like the old CLI migrator:
preserve script names
preserve file locations when possible
preserve function bodies
preserve syncType
preserve trackDeletes
preserve nango.lastSyncDate usage if it already exists
Only do a second modernization pass if the user explicitly asks.
