nangohq/migrating-to-zero-yaml

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

1. Confirm you are in the Nango project root and nango.yaml exists.
2. Make sure there is a rollback path before destructive edits (git branch/commit or external backup).
3. Read nango.yaml and inventory:
   • integrations
   • syncs
   • actions
   • on-event handlers
   • models
4. Inspect the existing TypeScript files that those YAML entries point to.
5. 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

1. Read nango.yaml and build a migration inventory.
2. Create or update Zero YAML scaffolding:
   • package.json
   • tsconfig.json
3. Generate models.ts from the YAML models.
4. Rewrite each sync file into createSync(...).
5. Rewrite each action file into createAction(...).
6. Rewrite each lifecycle handler into createOnEvent(...).
7. Generate index.ts side-effect imports for every migrated script.
8. Fix helper-file imports and small TypeScript breakages.
9. Compile and validate.
10. 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:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "include": ["index.ts", "**/*.ts"],
  "exclude": ["node_modules", "dist", "build", ".nango"],
  "compilerOptions": {
    "module": "node16",
    "target": "esnext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node16",
    "exactOptionalPropertyTypes": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "sourceMap": true,
    "noEmit": true
  }
}

Generate models.ts

Create a root models.ts file that turns YAML model definitions into Zod schemas plus exported inferred types.

Use this pattern:

import * as z from 'zod';

export const Ticket = z.object({
    id: z.string(),
    title: z.string()
});

export type Ticket = z.infer<typeof Ticket>;

export const models = {
    Ticket
};

Conversion rules:

• string -> z.string()
• number -> z.number()
• boolean -> z.boolean()
• Date -> z.date()
• 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.

Use this shape:

import { createSync } from 'nango';
import * as z from 'zod';
import { Metadata, Ticket } from '../../models.js';

const sync = createSync({
    description: 'Sync tickets',
    version: '0.0.1',
    frequency: 'every hour',
    autoStart: true,
    syncType: 'full',
    trackDeletes: false,
    endpoints: [{ method: 'GET', path: '/tickets', group: 'Tickets' }],
    metadata: Metadata,
    models: { Ticket },
    exec: async (nango) => {
        // keep existing logic
    }
});

export type NangoSyncLocal = Parameters<typeof sync['exec']>[0];
export default sync;

Rewrite actions

For each YAML action, wrap the existing default-exported function in createAction(...).

Map YAML config like this:

• description -> description
• version -> version (default 0.0.1)
• endpoint -> endpoint
• input -> input
• output -> output
• scopes -> scopes
• existing default export function body -> exec

If the action has no input or output schema, use z.void().

Use this shape:

import { createAction } from 'nango';
import * as z from 'zod';
import { CreateTicketInput, CreateTicketOutput } from '../../models.js';

const action = createAction({
    description: 'Create ticket',
    version: '0.0.1',
    endpoint: { method: 'POST', path: '/tickets', group: 'Tickets' },
    input: CreateTicketInput,
    output: CreateTicketOutput,
    exec: async (nango, input) => {
        // keep existing logic
    }
});

export type NangoActionLocal = Parameters<typeof action['exec']>[0];
export default action;

Rewrite on-event handlers

For each YAML lifecycle handler, wrap the existing default export in createOnEvent(...).

Map like this:

• event name -> event
• description -> preserve an existing description if one exists; otherwise use <event> event handler
• existing default export function body -> exec

Use this shape:

import { createOnEvent } from 'nango';

export default createOnEvent({
    event: 'post-connection-creation',
    description: 'post-connection-creation event handler',
    exec: async (nango) => {
        // keep existing logic
    }
});

Import and typing fixes

The old migrator also cleaned up imports. Do the same manually.

• Remove NangoSync, NangoAction, ProxyConfiguration, and ActionError imports from old models imports.
• Import runtime types from nango instead.
• Keep generated model imports pointing to ../../models.js or the correct relative path.
• Use side-effect imports with .js in index.ts.

Important mechanical fixes:

• Replace local NangoSync parameter annotations with NangoSyncLocal after wrapping the file.
• Replace local NangoAction parameter annotations with NangoActionLocal after wrapping the file.
• Remove type arguments from:
  • nango.batchSave<T>(...)
  • nango.batchUpdate<T>(...)
  • nango.batchDelete<T>(...)
  • nango.getMetadata<T>()

Those generic arguments often compile in the old format but become noisy or unnecessary after migration.

Generate index.ts

Create a root index.ts with side-effect imports for every migrated script. Include the .js extension.

Example:

import './github/syncs/fetch-issues.js';
import './github/actions/create-issue.js';
import './github/on-events/post-connection-creation.js';

Do not use named or default imports here.

Helper-file cleanup

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.

Validation loop

After the mechanical migration:

• run nango compile
• fix straightforward TypeScript/import/schema issues
• run nango dryrun <script-name> <connection-id> --validate -e dev --no-interactive --auto-confirm
• for actions, add --input '{...}' or --input '{}'
• if validation passes, run nango dryrun <script-name> <connection-id> --save -e dev --no-interactive --auto-confirm
• run nango generate:tests && npm test
• never hand-edit generated *.test.json

If a migrated sync/action still needs a true behavioral refactor after this point, stop and treat that as a separate task.

Useful docs

• Zero YAML migration doc: https://www.nango.dev/docs/implementation-guides/platform/migrations/migrate-to-zero-yaml
• Testing: https://www.nango.dev/docs/implementation-guides/platform/functions/testing
• Functions SDK: https://www.nango.dev/docs/reference/functions
• Checkpoints migration: https://www.nango.dev/docs/implementation-guides/platform/migrations/migrate-to-checkpoints
• Deletion detection: https://www.nango.dev/docs/implementation-guides/use-cases/syncs/deletion-detection