flat8n

Native n8n workflow packager.

flat8n parses your project, resolves dependencies across multiple files, and bundles them into a single monolithic n8n workflow JSON ready for deployment.

Quick Start  •  Why You Need This  •  Features  •  API Reference  •  CLI Reference

Quick Start

[!TIP] Start a new project The modern, code-first way to scaffold a best-practice n8n project is:

npx @flat8n/cli init

[!NOTE] Run in an existing project If you already have workflows, just run the packager directly to start the dev server:

npx @flat8n/cli

Global installation:

npm install -g @flat8n/cli

Local installation for programmatic usage:

npm install @flat8n/cli

Why You Need This

Building an n8n workflow with dozens of nodes in a single file quickly becomes unmanageable. Finding specific nodes takes time, reusing logic across projects requires copy-pasting, and collaborating with a team in Git produces merge conflicts.

flat8n lets you split your workflow into small, manageable, logical pieces. When you run npx @flat8n/cli, it reads those separate files, links them together, and compiles them into one single monolithic workflow JSON. You import this single output file directly into n8n and execute it without external dependencies.

| Factor | Without flat8n | With flat8n | |---|---|---| | File Structure | One massive .json file. | Multiple modular, focused .json files. | | Git Collaboration | Constant merge conflicts on canvas coordinates. | Clean commits, easy pull-request reviews. | | Reusability | Copy-paste nodes between workflows. | Write once, reference anywhere via sub-workflows. | | Validation | Discover broken links at runtime in n8n. | CLI validates graph integrity upfront. | | Deployment | Manual import/export via the n8n UI. | Outputs a single bundled.json ready for CI/CD. |

Features

• Project Scaffolding — Run npx @flat8n/cli init to instantly generate a robust, domain-native folder structure for your modular workflows.
• Zero-config Packager — Run npx @flat8n/cli without arguments to automatically detect your workflows, bundle them into a single file in dist, and optionally boot a local n8n instance for testing.
• Dependency Linking — Write modular workflows and let flat8n parse them, build graph intermediate representation (IR), and inline referenced sub-workflows.
• Native Validation — Catch errors early. The compiler validates your output against native n8n workflow structures and verifies graph integrity.
• Parse Caching — The watcher only recompiles changed files, using metadata-based parse caching for fast rebuilds.
• Graph Analysis — Inspect workflow structures, node counts, and dependency chains programmatically or via CLI.

What This Looks Like

The Packager In Action

When you run the tool without parameters, it acts as a unified environment:

> npx @flat8n/cli
[+] Auto-detected workflows
[+] Watching for changes...
[+] Booting local n8n instance
[+] Deployed "bundled.json" to local n8n

Explicit Linking

If you prefer explicit linking over the auto-detect feature, pass arguments directly:

> flat8n link --entry workflow.json --dep child=child.json --out bundled.json

Programmatic Linking

import { link } from "flat8n";

const bundled = link({
  entry: "workflow.json",
  dependencies: {
    child: "child.json"
  }
});
// bundled is a deterministic, native monolithic n8n workflow JSON

API Reference

import { analyze, link, validate, watch } from "flat8n";

| Function | Description | |----------|-------------| | link() | Parses workflows, builds graph IR, inlines referenced workflows, validates output, and returns deterministic JSON. | | validate() | Checks native n8n workflow structure and graph integrity. | | analyze() | Returns graph stats and diagnostics. | | watch() | Recompiles file inputs with metadata-based parse caching. |

CLI Reference

| Scenario | Command | |----------|---------| | Scaffold a new n8n project | npx @flat8n/cli init | | Start the packager | npx @flat8n/cli | | Link and bundle a workflow | npx @flat8n/cli link --entry workflow.json --dep child=child.json --out bundled.json | | Validate a workflow's integrity | npx @flat8n/cli validate --entry workflow.json | | Analyze a workflow's graph | npx @flat8n/cli analyze --entry workflow.json --dep child=child.json |

Contributing

Please see CONTRIBUTING.md for details on how to contribute to the project, and our CODE_OF_CONDUCT.md for the code of conduct.

↑ back to top