Migrating to Zero YAML

The nango.yaml configuration file is no longer supported. Since September 15, 2026, Tenklo rejects deployments that use it. This guide helps you migrate your existing integrations from the YAML-based approach to Zero YAML, which uses pure TypeScript with modern tooling.

What is Zero YAML?Copy Anchor Link

Zero YAML is Tenklo'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 WorksCopy Anchor Link

The new system is built around simplification

Simplified file StructureCopy Anchor Link

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 configurationCopy Anchor Link

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 GuideCopy Anchor Link

Automatic MigrationCopy Anchor Link

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

nango migrate-to-zero-yaml

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 StepsCopy Anchor Link

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

Migration PlanCopy Anchor Link

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?Copy Anchor Link

Configuration: YAML → TypeScript ObjectsCopy Anchor Link

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 SchemasCopy Anchor Link

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 ExamplesCopy Anchor Link

Sync ExampleCopy Anchor Link

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 ExampleCopy Anchor Link

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 StructureCopy Anchor Link

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 & FAQCopy Anchor Link

GotchasCopy Anchor Link

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 Tenklo helper:

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

Nango.yaml EOLCopy Anchor Link

Q: Is nango.yaml still supported?

A: No. Support ended on September 15, 2026. Deployments that use a nango.yaml are rejected with an error that points to this guide. Functions deployed before then keep running until you redeploy them, which requires migrating first.

Package.json RequirementCopy Anchor Link

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.

Backward CompatibilityCopy Anchor Link

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 IntegrationsCopy Anchor Link

Q: How do I test after migration?

A: Use the same testing commands:

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

Rollback ProcessCopy Anchor Link

Q: Can I rollback if something goes wrong?

A: Not to nango.yaml, since deployments that use it are rejected. Validate the migrated integration before it reaches production: run nango dryrun against a test connection, then deploy to a development environment with nango deploy dev. Keep a copy of your original files as a reference until you have validated the migration.

The Zero YAML approach represents a significant step forward in Tenklo'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! 🚀

Related guidesCopy Anchor Link

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