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

Other Installation Methods

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

Available Functions

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

Available Commands

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