Contribution Guide

This section contains documentation for developers and contributors working on n8n-as-code.

📚 Available Documentation

Architecture & Design

Architecture Overview: Understand the n8n-as-code monorepo architecture, component interactions, and design decisions.

Internal Packages

Sync Engine: Internal documentation for the sync engine embedded in n8nac and reused by the VS Code extension.
Skills Library: Internal documentation for @n8n-as-code/skills, the internal library exposed through n8nac skills.
Claude Adapter: Internal documentation for the Claude adapter generated from the Skills library.

🛠 Development Setup

Prerequisites

Node.js 18+
npm 9+
Git

Getting Started

Clone the repository
Run npm install in the root directory
Build all packages with npm run build
Run tests with npm test

📦 Package Structure

n8n-as-code is organized as a monorepo with the following packages:

Package	Purpose	Primary Users
CLI (`n8nac`)	Command-line interface + embedded sync engine	Terminal users, automation
Skills Library (`@n8n-as-code/skills`)	Internal AI tooling library exposed through `n8nac skills`	AI assistants, developers
Transformer (`@n8n-as-code/transformer`)	TypeScript workflow decorators, conversion, and code generation primitives	Workflow authors, package maintainers
VS Code Extension (`n8n-as-code`)	Integrated editor experience built on top of `n8nac` and `@n8n-as-code/skills`	VS Code users

There is no longer a standalone Claude Skill package in packages/. Claude-specific distribution is generated from packages/skills as an adapter artifact.

🧪 Testing

Test Structure

Unit Tests: Individual component testing with Jest
Integration Tests: End-to-end workflow tests
Snapshot Tests: Ensure generated files match expected format

Running Tests

# Run all tests
npm test

# Run tests for specific package
cd packages/skills && npm test
cd packages/cli && npm test

🔧 Building

Development Build

npm run build

Watch Mode (Development)

# CLI watch mode
cd packages/cli && npm run watch

# Rebuild the VS Code extension
cd packages/vscode-extension && npm run build

📦 Version Management

n8n-as-code uses a custom commit-driven release flow with independent package versioning. Each package evolves independently while the release automation keeps internal dependencies aligned.

Current Package Versions

Packages evolve independently with their own version numbers:

@n8n-as-code/transformer: 0.2.9
n8nac: 0.11.4 (embeds sync engine, exposes n8nac skills)
@n8n-as-code/skills: 0.16.16 (internal library, consumed by n8nac and the VS Code extension)
VS Code Extension: 0.20.1

Note: Each package has its own version number. The release workflow updates internal dependency pins automatically whenever an upstream package version changes.

Package Publication Strategy

The project uses a custom commit-driven release flow.

Package	Published To	Version Source
`@n8n-as-code/transformer`	NPM Registry	Conventional commits + dependency propagation
`@n8n-as-code/skills`	NPM Registry	Conventional commits + dependency propagation
`n8nac`	NPM Registry	Conventional commits + dependency propagation
`n8n-as-code` (VS Code Extension)	VS Code Marketplace / Open VSX	`packages/vscode-extension/package.json` with even-minor stable lines and odd-minor prerelease lines
Claude adapter artifacts	GitHub repository / plugin distribution flow	Built from `packages/skills/scripts/build-claude-adapter.js`
`n8n-as-code-monorepo` (root)	Not published	Not released
`docs`	Not published	Not released

Release Workflow

Push to `next`

Every push to next computes prerelease bumps from commit messages.
Internal dependency versions are re-pinned automatically.
Changed public packages are published to npm with the next dist-tag.
The VS Code extension follows the official Marketplace recommendation: stable releases use even minor lines and prereleases use odd minor lines.
The prerelease line is intentionally kept above the stable version that the same changes will later publish from main, so preview users are not forced back to stable.
Example: if the current stable extension is 0.21.0, the next stable release becomes 0.22.0 and prereleases on next become 0.23.1, 0.23.2, 0.23.3, and so on.
Open VSX prereleases remain disabled.

Push to `main`

If any package version in package.json is already ahead of its latest stable tag, main publishes that version directly instead of opening a new release PR.
A push to main creates or updates a single release PR only when no package is already ahead of its latest stable tag and commit history requires version bumps.
The release PR updates package versions and internal dependency versions together.
For the VS Code extension, stable releases always land on patch 0 of the next even minor line.
Example: after prereleases on 0.23.x, the next stable extension release becomes 0.22.0, and the following cycle starts with prereleases on 0.25.x.

Merge the release PR

The merged package.json versions become the stable source of truth.
Changed npm packages are published in dependency order.
The VS Code extension is published from the exact version committed in packages/vscode-extension/package.json.
Stable git tags are pushed for each released package.
The workflow force-aligns next back to main, or recreates next if it was deleted.

Example: How Internal Dependencies Stay Synchronized

Let's say you fix a bug in the sync engine (embedded in n8nac):

# 1. Push a conventional commit to next
git commit -m "fix(cli): handle sync edge case"

# 2. Merge next into main
# 3. Let the release PR bump versions automatically

Result:

n8nac: 0.11.4 → 0.11.5 ✅
@n8n-as-code/skills: (unchanged, no dependency on n8nac) ✅
VS Code Extension: 0.21.0 → 0.22.0 on main, while next prereleases are published on 0.23.x ✅

All packages that depend on n8nac will have their package.json updated to reference the newly released stable version.

Workflow Summary Diagram

Developer pushes conventional commits to next
       ↓
CI publishes prereleases from next
       ↓
next is merged into main
       ↓
CI creates or updates a release PR
       ↓
Maintainer merges the release PR
       ↓
CI automatically:
  ├─→ Publishes stable npm packages in dependency order
  ├─→ Tags released package versions
  ├─→ Publishes the VS Code extension from package.json
  └─→ Re-aligns next on top of main

Key Rules

Never manually edit release versions in PRs by hand unless you are intentionally repairing the release flow
Use conventional commits so the CI can derive major, minor, or patch automatically
Package-scoped docs(...) commits also count as patch releases when they touch files inside a released package
The VS Code extension uses even minor lines for stable releases and odd minor lines for prereleases
The prerelease line must stay numerically above the stable release that will be published next
The VS Code extension version line is driven from packages/vscode-extension/package.json
Internal dependencies are automatically re-pinned whenever an upstream package is bumped
Private packages remain safe - they can participate in version orchestration without npm publication
Use npm run check-versions to verify all internal dependencies are up-to-date
Git tags are created automatically for each published NPM package
Each package has independent releases - No global monorepo release