Skip to main content
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',
    endpoints: [{ method: 'GET', path: '/issues', group: '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:
  1. Analyze your existing nango.yaml and TypeScript files
  2. Generate new self-contained TypeScript files
  3. Create the required package.json if it doesn’t exist
  4. Set up the index.ts entry point
  5. 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:
  1. Back up your current nango integrations folder
  2. Use your dev env to migrate to test the new format
  3. 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',
    syncType: 'full',
    endpoints: [{ method: 'GET', path: '/issues', group: 'Issues' }],
    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',
    syncType: 'full',
    endpoints: [{ method: 'GET', path: '/issues', group: 'Issues' }],
    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',
    endpoint: { method: 'POST', path: '/issues', group: 'Issues' },
    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:
  1. Go to your backup folder
  2. 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.