Migrating to Zero YAML

The nango.yaml configuration file is deprecated and should not be used for new integrations. If you are still using it, this guide will help you migrate your existing Nango integrations from the YAML-based approach to our new Zero YAML system, which uses pure TypeScript with modern tooling.

What is Zero YAML?

Zero YAML is Nango’s new approach to building integrations that eliminates the need for separate nango.yaml configuration files. Instead, everything is defined in TypeScript using a configuration-as-code approach with full type safety. Key benefits:

Type Safety: Full TypeScript support with Zod schema validation
Better Developer Experience: Modern tooling, enhanced CLI output, and better error messages
Portability: Self-contained files that can be easily shared and version controlled
No Custom Syntax: Pure TypeScript—no need to learn YAML-specific conventions and our previous custom model syntax

Here’s a quick example of the new syntax:

import { createSync } from 'nango';
import * as z from 'zod';

const issueSchema = z.object({
    id: z.string(),
    title: z.string(),
    state: z.string()
});

const sync = createSync({
    description: 'Fetches GitHub issues',
    frequency: 'every hour',
    models: { GithubIssue: issueSchema },
    exec: async (nango) => {
        await nango.batchSave([{ id: 'foobar' }], 'GithubIssue');
    }
});

How Zero YAML Works

The new system is built around simplification

Simplified file Structure

Like a regular TypeScript codebase

├── index.ts                     # Declare what's deployed
├── package.json                 # Dependency management and types
├── github/                      # An integration
    ├── syncs/
    │     └── fetchIssues.ts     # A sync
    └── actions/
           └── createIssue.ts     # An action

Simplified configuration

Three core functions that replace YAML configuration. You’ll benefit from IntelliSense and type safety, directly in your IDE. No need to jump between files to find the right configuration.

createSync(): Defines data synchronization jobs
createAction(): Defines one-off jobs
createOnEvent(): Defines event-based jobs

Quick Migration Guide

Automatic Migration

The easiest way to migrate is using our automated migration command:

nango migrate-to-zero-yaml

This operation is destructive and will overwrite your existing files. Make sure to back up your existing files before running the command.

This command will:

Analyze your existing nango.yaml and TypeScript files
Generate new self-contained TypeScript files
Create the required package.json if it doesn’t exist
Set up the index.ts entry point
Preserve your existing logic and configuration

Post-Migration Steps

The migration command should automatically transform all your files. However, you should review the changes and make sure everything is correct.

Because the new format is stricter, some type issues can arise after the migration.

Migration Plan

We recommend:

Back up your current nango integrations folder
Use your dev env to migrate to test the new format
Deploy to prod env after you have assessed that everything works properly

What Has Changed?

Configuration: YAML → TypeScript Objects

Before (nango.yaml + separate .ts file):

# nango.yaml
integrations:
  github:
    issues:
      runs: every 1h
      sync_type: full
      endpoint: GET /issues
      description: Fetches GitHub issues
models:
  GithubIssue:
    id: string
    title: string

After (single self-contained file):

const sync = createSync({
    description: 'Fetches GitHub issues',
    frequency: 'every hour',
    models: { GithubIssue: issueSchema }
});

Models: YAML Definitions → Zod Schemas

Before:

models:
  GithubIssue:
    id: string
    title: string
    state: string

After:

const issueSchema = z.object({
    id: z.string(),
    title: z.string(),
    state: z.string()
});

Before and After Examples

Sync Example

Before (issues.ts + nango.yaml excerpt):

// issues.ts
import type { NangoSync, GithubIssue } from '../../models';

export default async function fetchData(nango: NangoSync) {
    // Sync logic here
}

# nango.yaml excerpt
integrations:
  github:
    issues:
      runs: every 1h
      sync_type: full
      endpoint: GET /issues

After (self-contained fetchIssues.ts):

import { createSync } from 'nango';
import * as z from 'zod';

const issueSchema = z.object({
    id: z.string(),
    title: z.string(),
    state: z.string()
});

const sync = createSync({
    description: 'Fetches GitHub issues',
    frequency: 'every hour',
    models: { GithubIssue: issueSchema },
    exec: async (nango) => {
        // Your existing sync logic here
    }
});

export default sync;

Action Example

Before (separate files):

// create-issue.ts
export default async function runAction(nango: NangoAction, input: CreateIssueInput) {
    // Action logic
}

After (self-contained):

import { createAction } from 'nango';
import * as z from 'zod';

const inputSchema = z.object({
    title: z.string(),
    body: z.string()
});

const action = createAction({
    description: 'Create a GitHub issue',
    input: inputSchema,
    output: z.void(),
    exec: async (nango, input) => {
        // Your action logic here
    }
});

export default action;

Index File Structure

The new index.ts file imports all your integrations:

// index.ts
import './github/syncs/fetchIssues.js';
import './github/actions/createIssue.js';
// Add more imports as needed

Migration Gotchas & FAQ

Gotchas

err - github/syncs/issues.ts:57:43
  Argument of type '{ id: number; owner: string; repo: string; issue_number: number; title: string; author: string; author_id: string; state: string; date_created: Date; date_last_modified: Date; body: string; }[]' is not assignable to parameter of type 'RawModel[]'.
  Type '{ id: number; owner: string; repo: string; issue_number: number; title: string; author: string; author_id: string; state: string; date_created: Date; date_last_modified: Date; body: string; }' is not assignable to type 'RawModel'.
    Types of property 'id' are incompatible.
      Type 'number' is not assignable to type 'string'.

Previously you were setting the ID property of a sync to a number when it should always be a string.

err - 1password-scim/actions/create-user.ts:26:45
  Property 'errors' does not exist on type 'ZodError<{ firstName: string; lastName: string; email: string; active?: boolean | undefined; externalId?: string | undefined; phoneNumbers?: { type: "work" | "mobile" | "other"; value: string; }[] | undefined; photos?: { ...; }[] | undefined; addresses?: { ...; }[] | undefined; title?: string | undefined; }>'.

Previously you were validating an input using Zod in this way

const parsedInput = scimCreateUserSchema.safeParse(input);

if (!parsedInput.success) {
  for (const error of parsedInput.error.errors) {
    await nango.log(
      `Invalid input provided to create a user: ${error.message} at path ${error.path.join(".")}`,
      { level: "error" },
    );
  }

  throw new nango.ActionError({
    message: "Invalid input provided to create a user",
  });
}

Instead of this, you can use a Nango helper:

const parsedInput = await nango.zodValidateInput({ zodSchema: scimCreateUserSchema, input });

Nango.yaml EOL

Q: When will nango.yaml stop being supported? A: nango.yaml integrations will be supported until the end of 2025. Zero YAML will be the only supported way to build integrations after that. An official roadmap will be published soon.

Package.json Requirement

Q: Why is package.json now mandatory? A: The new system uses modern JavaScript tooling that requires proper dependency management. The package.json ensures:

Consistent dependency versions across environments
Proper module resolution
Better integration with modern development tools

If you don’t have one, the migration command will create it automatically.

Note: Bundling custom dependencies is not yet possible but is now on our roadmap thanks to this update.

Backward Compatibility

Q: What still works the same? A: Your core integration logic remains unchanged. No new features or breaking changes. All CLI commands are still available.

Testing Migrated Integrations

Q: How do I test after migration? A: Use the same testing commands:

# Test a specific sync
nango dryrun <scriptName> <connectionId>

Rollback Process

Q: Can I rollback if something goes wrong? A: Yes, Nango’s platform remains compatible with nango.yaml at all times:

Go to your backup folder
nango deploy dev

Keep your original files until you’ve fully validated the migration.

The Zero YAML approach represents a significant step forward in Nango’s developer experience. By eliminating custom syntax and embracing pure TypeScript, we’ve made integrations more maintainable, shareable, and enjoyable to work with. Many more features will be possible thanks to this new syntax. If you encounter any issues during migration, our support team is ready to help. Happy integrating! 🚀

Questions, problems, feedback? Please reach out in the Slack community.

Functions guide - understand the current TypeScript-first project layout.
Functions CLI - deploy and dry-run migrated functions.
Testing - verify migrated integrations before rollout.

Getting started

Guides

Reference

Migrating to Zero YAML

What is Zero YAML?

How Zero YAML Works

Simplified file Structure

Simplified configuration

Quick Migration Guide

Automatic Migration

Post-Migration Steps

Migration Plan

What Has Changed?

Configuration: YAML → TypeScript Objects

Models: YAML Definitions → Zod Schemas

Before and After Examples

Sync Example

Action Example

Index File Structure

Migration Gotchas & FAQ

Gotchas

Nango.yaml EOL

Package.json Requirement

Backward Compatibility

Testing Migrated Integrations

Rollback Process

​What is Zero YAML?

​How Zero YAML Works

​Simplified file Structure

​Simplified configuration

​Quick Migration Guide

​Automatic Migration

​Post-Migration Steps

​Migration Plan

​What Has Changed?

​Configuration: YAML → TypeScript Objects

​Models: YAML Definitions → Zod Schemas

​Before and After Examples

​Sync Example

​Action Example

​Index File Structure

​Migration Gotchas & FAQ

​Gotchas

​Nango.yaml EOL

​Package.json Requirement

​Backward Compatibility

​Testing Migrated Integrations

​Rollback Process

​Related guides

What is Zero YAML?

How Zero YAML Works

Simplified file Structure

Simplified configuration

Quick Migration Guide

Automatic Migration

Post-Migration Steps

Migration Plan

What Has Changed?

Configuration: YAML → TypeScript Objects

Models: YAML Definitions → Zod Schemas

Before and After Examples

Sync Example

Action Example

Index File Structure

Migration Gotchas & FAQ

Gotchas

Nango.yaml EOL

Package.json Requirement

Backward Compatibility

Testing Migrated Integrations

Rollback Process

Related guides