### Setup n8n Repository

Source: https://github.com/n8n-io/n8n/blob/master/AGENTS.md

Use `pnpm agent:setup` for a fresh checkout to install, build, and test all packages. It optimizes resource usage and logs output for easier debugging. You can run individual steps or get a JSON summary for scripting.

```bash
pnpm agent:setup                 # install → build → test (full suite)
pnpm agent:setup install         # one step at a time
pnpm agent:setup --json          # JSON summary on stdout (for scripts/agents)
```

--------------------------------

### setup-workflow

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/docs/tools.md

Opens the user interface for per-node credential and parameter setup, guiding the user through interactive configuration.

```APIDOC
## setup-workflow

### Description
Open the UI for per-node credential and parameter setup. Uses a suspend/resume state machine where each node triggers a HITL confirmation for the user to configure it interactively.

### Parameters
#### Query Parameters
- **workflowId** (string) - Required - Workflow to set up

### Response
#### Success Response (200)
- **completedNodes** (array) - List of nodes successfully set up
- **skippedNodes** (array) - List of nodes skipped during setup
- **failedNodes** (array) - List of nodes that failed setup.
```

--------------------------------

### Pure Frontend Development Setup

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Start the backend server without watching, and run the frontend development server. This setup is for focusing solely on frontend development.

```bash
# Terminal 1: Start the backend server (no watching)
pnpm start

# Terminal 2: Run frontend dev server
cd packages/editor-ui
pnpm dev
```

--------------------------------

### New Guide Structure Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

Illustrates the structure for defining a new node type guide, including patterns for matching nodes and the content of the guide. This guide can be added to the registry for dynamic prompt assembly.

```typescript
export const MY_NODE_GUIDE: NodeTypeGuide = {
  patterns: ['n8n-nodes-base.myNode'],  // Which nodes to match
  condition: (ctx) => true,              // Optional: extra conditions
  content: `Your guide content here...`,
};
```

--------------------------------

### Run Queue Stack

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Starts a local n8n instance with a queue system enabled. Uses Testcontainers for setup.

```bash
pnpm --filter n8n-containers stack:queue
```

--------------------------------

### Conditional Guide Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/src/prompts/README.md

Shows how to define a guide that conditionally applies based on context. The `condition` property allows for dynamic inclusion of guide content.

```typescript
export const RESOURCE_LOCATOR_GUIDE: NodeTypeGuide = {
  patterns: ['*'],  // Matches all nodes
  condition: (ctx) => ctx.hasResourceLocatorParams === true,
  content: `...`,
};
```

--------------------------------

### Run SQLite Stack

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Starts a local n8n instance configured with SQLite as the database. Uses Testcontainers for setup.

```bash
pnpm --filter n8n-containers stack:sqlite
```

--------------------------------

### Run Postgres Stack

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Starts a local n8n instance configured with PostgreSQL as the database. Uses Testcontainers for setup.

```bash
pnpm --filter n8n-containers stack:postgres
```

--------------------------------

### Re-run Test Setup

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/playwright/tests/cli-workflows/README.md

Execute the test setup process. Use this if the setup did not run correctly or needs to be re-initiated.

```bash
pnpm test:workflows:setup
```

--------------------------------

### Basic McpServer Setup

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/README.md

Provides the basic TypeScript setup for initializing and using the McpServer, including handling setup requests and POST messages.

```typescript
import { McpServer } from './McpServer';

const mcpServer = McpServer.instance(logger);

// Handle SSE setup
await mcpServer.handleSetupRequest(req, resp, serverName, postUrl, tools);

// Handle POST messages
const result = await mcpServer.handlePostMessage(req, resp, tools, serverName);
```

--------------------------------

### Build Windows Installer

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/local-gateway/README.md

Build a distributable installer for Windows (x64). The installer will be written to the `out/` directory.

```bash
pnpm --filter=@n8n/local-gateway dist:win
```

--------------------------------

### Basic Synchronization Setup with MockTransport

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/crdt/README.md

Shows how to set up synchronization between two documents using mock transports for testing purposes. Changes are automatically propagated once sync providers are started.

```typescript
import { createSyncProvider, MockTransport } from '@n8n/crdt';

// Create linked transports
const transportA = new MockTransport();
const transportB = new MockTransport();
MockTransport.link(transportA, transportB);

// Create sync providers
const syncA = createSyncProvider(docA, transportA);
const syncB = createSyncProvider(docB, transportB);

// Start sync
await syncA.start();
await syncB.start();

// Changes now propagate automatically
```

--------------------------------

### Install @n8n/cli

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/cli/README.md

Install the CLI globally or use it directly with npx for zero installation.

```bash
# Use directly with npx (zero install)
npx @n8n/cli workflow list

# Or install globally
npm install -g @n8n/cli
```

--------------------------------

### Build macOS Installer

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/local-gateway/README.md

Build a distributable installer for macOS (universal: arm64 + x64). The installer will be written to the `out/` directory.

```bash
pnpm --filter=@n8n/local-gateway dist:mac
```

--------------------------------

### Start Basic n8n Stack (SQLite)

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/containers/README.md

Starts a basic n8n testing environment using SQLite as the database.

```bash
pnpm stack
```

--------------------------------

### Start n8n Stack for Cloud Plan Simulation

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/containers/README.md

Starts an n8n testing environment simulating a specific cloud plan, like 'starter'.

```bash
pnpm stack --plan starter
```

--------------------------------

### Run Multi-Main Stack

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Starts a local n8n instance with multiple main processes. Uses Testcontainers for setup.

```bash
pnpm --filter n8n-containers stack:multi-main
```

--------------------------------

### Run Development Server with Custom User Folder

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Start the development server using a different user folder to test with a clean n8n setup without losing the existing local configuration. This is useful for testing features in isolation.

```bash
packages/cli$ N8N_USER_FOLDER=~/.n8n3/ pnpm run dev
packages/cli$ N8N_USER_FOLDER=~/.n8n4/ pnpm run dev
```

--------------------------------

### Start n8n Stack with PostgreSQL

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/containers/README.md

Starts an n8n testing environment configured to use PostgreSQL.

```bash
pnpm stack --postgres
```

--------------------------------

### Add a New Benchmark

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/performance/README.md

Example of how to add a new benchmark using Vitest. Setup runs once and is not measured. Benchmarks should focus on a single operation.

```typescript
// benchmarks/my-feature/thing.bench.ts
import { bench, describe } from 'vitest';

// Setup runs once, not measured
const data = createTestData();

describe('My Feature', () => {
  bench('operation name', () => {
    doTheThing(data);
  });
});
```

--------------------------------

### JSON Configuration Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/CONFIGURATION.md

An example of a workflow comparison configuration in JSON format. This snippet demonstrates the equivalent structure to the YAML example for basic settings like version, name, description, costs, and similarity groups.

```json
{
  "version": "1.0",
  "name": "my-config",
  "description": "My custom configuration",
  "costs": {
    "nodes": {
      "insertion": 10.0,
      "deletion": 10.0
    }
  },
  "similarity_groups": {
    "triggers": [
      "n8n-nodes-base.webhook",
      "n8n-nodes-base.manualTrigger"
    ]
  }
}

```

--------------------------------

### Install Dependencies

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/task-runner-python/README.md

Installs project dependencies using the 'just' task runner. Use 'just sync-all' to sync all dependencies.

```shell
just sync # or
just sync-all
```

--------------------------------

### Install HTTP Server

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/README.md

Installs the http-server package globally using npm.

```bash
npm install -g http-server
```

--------------------------------

### Install json-schema-to-zod

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/json-schema-to-zod/README.md

Install the package using npm.

```sh
npm install @n8n/json-schema-to-zod
```

--------------------------------

### Install uv

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md

Installs the uv dependency manager for macOS/Linux or Windows.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Install @n8n/expression-runtime

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/expression-runtime/README.md

Install the expression runtime package using pnpm.

```bash
pnpm add @n8n/expression-runtime
```

--------------------------------

### Install @n8n/tournament

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/tournament/README.md

Install the @n8n/tournament package using pnpm.

```sh
pnpm add @n8n/tournament
```

--------------------------------

### Start HTTPS Server

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/README.md

Starts an HTTPS server to serve the chat bundle from the specified directory, enabling CORS.

```bash
http-server packages/frontend/@n8n/chat/dist -g -S -C cert.pem -K key.pem --port 8443 --cors
```

--------------------------------

### Install and Run Tests with Python

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md

Commands to install development dependencies and run the test suite, including options for running with code coverage.

```bash
# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov
```

--------------------------------

### Install just

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/README.md

Installs the 'just' command runner via Homebrew, NPM, or a cross-platform curl script.

```bash
# on macOS via homebrew
brew install just
# or gloabl install via NPM
npm install -g rust-just
# or cross platform via curl to DEST
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to DEST
```

--------------------------------

### Start Multi-Main Cluster

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/containers/README.md

Starts an n8n testing environment with multiple main instances and workers for simulating a cluster.

```bash
pnpm stack --mains 2 --workers 1
```

--------------------------------

### Start n8n with .env file (regular instance)

Source: https://github.com/n8n-io/n8n/blob/master/packages/cli/src/modules/mcp/evaluations/README.md

Command to start a regular n8n instance using a specified .env file. Useful for using existing users and projects.

```bash
dotenvx run -f .env.mcp-evals -- pnpm start
```

--------------------------------

### Install Playwright Browsers Locally

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/playwright/README.md

Installs the necessary Playwright browsers for local testing. This command should be run within the playwright directory.

```bash
pnpm install-browsers:local
```

--------------------------------

### Incorrect package.json: Node path without dist/

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/eslint-plugin-community-nodes/docs/rules/n8n-object-validation.md

This example shows an incorrect package.json where a node path does not start with 'dist/'. The rule requires all node and credential paths to start with 'dist/'.

```json
{
  "name": "n8n-nodes-example",
  "n8n": {
    "n8nNodesApiVersion": 1,
    "nodes": ["./dist/nodes/Foo/Foo.node.js"]
  }
}
```

--------------------------------

### Navigate to Project Directory

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/create-node/README.md

After creating a new node, change into the newly generated project directory to begin development.

```bash
cd ./my-awesome-api-node
```

--------------------------------

### Start Specific Services for Local Development

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/playwright/README.md

Boots only the necessary services (e.g., postgres, redis, mailpit, proxy) for local development, avoiding full Docker rebuilds. This command writes service connection details to packages/cli/bin/.env.

```bash
# Terminal 1 — boot only the services. Writes packages/cli/bin/.env with the
# host:port + credentials. Containers stay running in the background.
pnpm --filter n8n-containers services --services postgres,redis,mailpit,proxy
```

--------------------------------

### Run Start Event Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/docs/streaming-protocol.md

Illustrates the 'run-start' event, which signifies the beginning of processing a user message. The agentId here identifies the orchestrator.

```json
{
  "type": "run-start",
  "runId": "run_abc123",
  "agentId": "agent-001",
  "payload": {
    "messageId": "msg_xyz"
  }
}
```

--------------------------------

### API Endpoint for Breaking Changes Report

Source: https://github.com/n8n-io/n8n/blob/master/packages/cli/src/modules/breaking-changes/README.md

Shows the GET request format and an example JSON response for detecting breaking changes.

```http
GET /breaking-changes/report?version=v2
```

```json
{
 "report": {
  "generatedAt": "2025-10-17T00:00:00.000Z",
  "targetVersion": "v2",
  "currentVersion": "1.x.x",
  "instanceResults": [
   {
    "ruleId": "process-env-access-v2",
    "ruleTitle": "Process Environment Access Restrictions",
    "ruleDescription": "Access to process.env is now restricted",
    "ruleSeverity": "high",
    "instanceIssues": [
     {
      "title": "Environment access detected",
      "description": "Workflows using process.env may be affected",
      "level": "warning"
     }
    ],
    "recommendations": [
     {
      "action": "Review environment variable usage",
      "description": "Update workflows to use secure environment variable access"
     }
    ]
   }
  ],
  "workflowResults": [
   {
    "ruleId": "removed-nodes-v2",
    "ruleTitle": "Removed Deprecated Nodes",
    "ruleDescription": "Several deprecated nodes have been removed",
    "ruleSeverity": "critical",
    "affectedWorkflows": [
     {
      "id": "wf-001",
      "name": "Customer Onboarding",
      "active": true,
      "numberOfExecutions": 142,
      "lastUpdatedAt": "2025-10-15T10:30:00.000Z",
      "lastExecutedAt": "2025-10-16T14:22:00.000Z",
      "issues": [
       {
        "title": "Node 'n8n-nodes-base.spontit' with name 'Spontit' has been removed",
        "description": "The node type 'n8n-nodes-base.spontit' is no longer available",
        "level": "error",
        "nodeId": "node-123",
        "nodeName": "Spontit"
       }
      ]
     }
    ],
    "recommendations": [
     {
      "action": "Update affected workflows",
      "description": "Replace removed nodes with their updated versions or alternatives"
     }
    ]
   }
  ]
 },
 "shouldCache": false
}
```

--------------------------------

### Docker Compose Setup for SearXNG and n8n

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/docs/configuration.md

Example Docker Compose configuration to run SearXNG alongside n8n, enabling Instance AI to use SearXNG for search.

```yaml
services:
  searxng:
    image: searxng/searxng:latest
    ports:
      - "8888:8080"  # optional: expose to host
  n8n:
    environment:
      N8N_INSTANCE_AI_MODEL: anthropic/claude-opus-4-8
      N8N_INSTANCE_AI_SEARXNG_URL: http://searxng:8080
```

--------------------------------

### Backend Module Entrypoint Example

Source: https://github.com/n8n-io/n8n/blob/master/scripts/backend-module/backend-module-guide.md

Demonstrates the structure of a backend module's entrypoint file (`.module.ts`), including initialization, shutdown, entity registration, settings, and context provision.

```typescript
import {
  BackendModule,
  ModuleInterface,
  OnShutdown,
} from '@nestjs/common';
import { Container } from '@wix/}',

@BackendModule({ name: 'my-feature' })
export class MyFeatureModule implements ModuleInterface {
  async init() {
    await import('./my-feature.controller');

    const { MyFeatureService } = await import('./my-feature.service');

    Container.get(MyFeatureService).start();
  }

  @OnShutdown()
  async shutdown() {
    const { MyFeatureService } = await import('./my-feature.service');

    await Container.get(MyFeatureService).shutdown();
  }

  async entities() {
    const { MyEntity } = await import('./my-feature.entity.ts');
    return [MyEntity]
  }

  async settings() {
    const { MyFeatureService } = await import('./my-feature.service');

    return Container.get(MyFeatureService).settings();
  }

  async context() {
    const { MyFeatureService } = await import('./my-feature.service');

    return { myFeatureProxy: Container.get(MyFeatureService) };
  }
}
```

--------------------------------

### Using Different Output Formats

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/cli/README.md

Demonstrates how to use the CLI with different output formats for various use cases, including JSON for scripting and ID-only for piping.

```bash
# Human-readable table
n8n-cli workflow list

# JSON for scripts
n8n-cli workflow list --format=json | jq '.[] | select(.active) | .id'

# Pipe IDs into another command
n8n-cli workflow list --format=id-only | xargs -I{} n8n-cli workflow deactivate {}
```

--------------------------------

### Quick Start: Pairwise Evals

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/evaluations/README.md

Run pairwise evaluations for Instance AI. This includes a small LangSmith smoke set, the full LangSmith dataset, and rerunning specific failed examples.

```bash
# From packages/@n8n/instance-ai/

# 1. Small LangSmith smoke set against a running n8n instance
LANGSMITH_API_KEY=... N8N_AI_ANTHROPIC_KEY="$ANTHROPIC_API_KEY" \
  pnpm eval:pairwise --judges 1 --max-examples 3
```

```bash
# 2. Full LangSmith dataset
LANGSMITH_API_KEY=... N8N_AI_ANTHROPIC_KEY="$ANTHROPIC_API_KEY" \
  pnpm eval:pairwise --judges 3
```

```bash
# 3. Rerun a specific subset (one example ID per line; #-prefixed lines ignored)
pnpm eval:pairwise \
  --example-ids-file .output/pairwise/failed-ids.txt \
  --output-dir .output/pairwise/rerun
```

--------------------------------

### Mocking API Endpoints with Nock

Source: https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/TESTING_PROMPT_WORKFLOW.md

Use nock to mock HTTP requests for testing. This example shows mocking GET, POST, and matching headers, query parameters, and request bodies.

```typescript
beforeAll(() => {
  const mock = nock('https://api.example.com');
  
  // Mock with headers
  mock.get('/protected-endpoint')
    .matchHeader('Authorization', 'Bearer test-token')
    .reply(200, { data: 'protected' });
  
  // Mock with query parameters
  mock.get('/search')
    .query({ q: 'test', limit: 10 })
    .reply(200, { results: [] });
  
  // Mock with request body validation
  mock.post('/validate', (body) => {
    return body.name && body.email;
  })
  .reply(200, { valid: true });
});
```

--------------------------------

### Basic API Mocking with Nock

Source: https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/TESTING_PROMPT_WORKFLOW.md

Demonstrates how to mock basic HTTP GET and POST requests using the Nock library for testing API interactions. Includes examples for successful responses and error handling.

```typescript
beforeAll(() => {
  const mock = nock('https://api.example.com');
  
  // Mock GET request
  mock.get('/users')
    .reply(200, {
      users: [
        { id: 1, name: 'User 1' },
        { id: 2, name: 'User 2' }
      ]
    });
  
  // Mock POST request
  mock.post('/users', {
    name: 'Test User',
    email: 'test@example.com'
  })
  .reply(201, {
    id: 123,
    name: 'Test User',
    email: 'test@example.com',
    status: 'active'
  });
  
  // Mock error responses
  mock.get('/error-endpoint')
    .reply(500, { error: 'Internal Server Error' });
});
```

--------------------------------

### Evaluation Lifecycle Hooks

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/README.md

Defines the interface for lifecycle hooks, providing centralized logging and control points throughout the evaluation process. These hooks are called at various stages, from starting an evaluation to completing individual examples.

```typescript
interface EvaluationLifecycle {
  onStart(config): void;
  onExampleStart(index, total, prompt): void;
  onWorkflowGenerated(workflow, durationMs): void;
  onEvaluatorComplete(name, feedback): void;
  onEvaluatorError(name, error): void;
  onExampleComplete(index, result): void;
  onEnd(summary): void;
}
```

--------------------------------

### Setup Integration LLM Instance

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/src/chains/test/integration/README.md

Set up a real LLM instance for testing using the `setupIntegrationLLM()` function. This function requires only the API key and does not need node loading.

```typescript
const llm = await setupIntegrationLLM();
```

--------------------------------

### Mocking HTTP Requests with ProxyServer

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/playwright/README.md

Use the ProxyServer service to mock API requests. The `@capability:proxy` tag ensures tests run only when proxy infrastructure is available. This example mocks a GET request and verifies it was made.

```typescript
import { test, expect } from '../fixtures/base';

// The `@capability:proxy` tag ensures tests only run when proxy infrastructure is available.
test.describe('Proxy tests @capability:proxy', () => {
  test('should mock HTTP requests', async ({ proxyServer, n8n }) => {
    // Create mock expectations
    await proxyServer.createGetExpectation('/api/data', { result: 'mocked' });

    // Execute workflow that makes HTTP requests
    await n8n.canvas.openNewWorkflow();
    // ... test implementation

    // Verify requests were proxied
    expect(await proxyServer.wasGetRequestMade('/api/data')).toBe(true);
  });
});
```

--------------------------------

### Start n8n with .env file in watch mode

Source: https://github.com/n8n-io/n8n/blob/master/packages/cli/src/modules/mcp/evaluations/README.md

Command to start the n8n development server with Instance AI enabled, using a specified .env file.

```bash
dotenvx run -f .env.mcp-evals -- pnpm dev:ai
```

--------------------------------

### GitHub Actions Example for Workflow Deployment

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/cli/docs/guides/ci-cd.md

This GitHub Actions workflow deploys n8n workflows from a local 'workflows' directory to your n8n instance. It checks out the code, sets up Node.js, installs the n8n CLI, and then iterates through JSON files in the 'workflows' directory to create or update them in n8n.

```yaml
name: Deploy Workflows
on:
  push:
    branches: [main]
    paths: ['workflows/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install n8n CLI
        run: npm install -g @n8n/cli

      - name: Deploy workflows
        env:
          N8N_URL: ${{ secrets.N8N_URL }}
          N8N_API_KEY: ${{ secrets.N8N_API_KEY }}
        run: |
          for file in workflows/*.json; do
            name=$(jq -r '.name' "$file")
            echo "Deploying: $name"
            n8n-cli workflow create --file="$file" --quiet
          done

```

--------------------------------

### Build and Start Production Mode

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Build the n8n project for production and start the server. This is used to check if the development changes work in a production-like environment.

```bash
pnpm build
pnpm start
```

--------------------------------

### Configure Filesystem Gateway for Instance AI

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/docs/configuration.md

Sets up Instance AI to use a filesystem gateway, requiring a specific API key. The user needs to run a separate command to start the gateway daemon.

```bash
N8N_INSTANCE_AI_GATEWAY_API_KEY=my-secret-key
```

--------------------------------

### Start Development Mode

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/local-gateway/README.md

Start the local gateway in development mode, which includes watch mode for both the main and renderer processes. This command can be run from the repo root or within the package directory.

```bash
pnpm --filter=@n8n/local-gateway dev
```

```bash
cd packages/@n8n/local-gateway
pnpm dev
```

--------------------------------

### YAML Configuration Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/CONFIGURATION.md

A comprehensive example of a workflow comparison configuration in YAML format. It includes settings for version, name, description, costs, similarity groups, ignore rules, parameter comparison, and output.

```yaml
version: "1.0"
name: "my-config"
description: "My custom configuration"

costs:
  nodes:
    insertion: 10.0
    deletion: 10.0
    # ... more costs

similarity_groups:
  triggers:
    - "n8n-nodes-base.webhook"
    - "n8n-nodes-base.manualTrigger"

ignore:
  node_types:
    - "n8n-nodes-base.stickyNote"

parameter_comparison:
  numeric_tolerance:
    - parameter: "options.temperature"
      tolerance: 0.1

output:
  max_edits: 15

```

--------------------------------

### Install n8n-core

Source: https://github.com/n8n-io/n8n/blob/master/packages/core/README.md

Install the n8n-core package using npm.

```bash
npm install n8n-core
```

--------------------------------

### Start n8n with Instance AI Enabled

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/README.md

Enables and configures Instance AI for local n8n development. Sets necessary environment variables for model, API key, and sandbox provider.

```bash
export N8N_ENABLED_MODULES=instance-ai
export N8N_AI_ENABLED=true

export N8N_INSTANCE_AI_MODEL=anthropic/claude-sonnet-4-5
export N8N_INSTANCE_AI_MODEL_API_KEY="$ANTHROPIC_API_KEY"

export N8N_INSTANCE_AI_SANDBOX_ENABLED=true

pnpm dev:ai
```

--------------------------------

### Components Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Example of a component interacting with UI elements.

```typescript
await this.nodePanel.selectNode('Webhook')
```

--------------------------------

### Flows/Composables Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Example of a flow interacting with application workflows.

```typescript
await app.workflows.createAndRun('my-workflow')
```

--------------------------------

### Load Configuration from Preset (CLI)

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/ai-workflow-builder.ee/evaluations/programmatic/python/CONFIGURATION.md

Use the Python CLI to load a predefined configuration preset for workflow comparison. This is a quick way to start with standard settings.

```bash
# Python CLI
uvx --from . python -m compare_workflows workflow1.json workflow2.json --preset standard
```

--------------------------------

### Frontend-only Development

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Start the frontend development server, including editor-ui and design-system. This is useful for optimizing resource usage when only working on the frontend.

```bash
pnpm dev:fe
```

--------------------------------

### Install Playwright Janitor

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Install the Playwright Janitor package as a development dependency.

```bash
pnpm add -D @n8n/playwright-janitor
```

--------------------------------

### Full Implementation Example: Project Creation Flow

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/playwright/CONTRIBUTING.md

A comprehensive example demonstrating the interaction between Page Objects, Composables, and Tests in Playwright. This illustrates the layered architecture for managing complex features.

```typescript
// 1. Page Object (ProjectSettingsPage.ts)
export class ProjectSettingsPage extends BasePage {
  // Simple action methods only
  async fillProjectName(name: string) {
    // Prefer stable ID selectors on the wrapper element and then target the inner control
    await this.page.locator('#projectName input').fill(name);
  }

  async clickSaveButton() {
    await this.clickButtonByName('Save');
  }
}

// 2. Composable (ProjectComposer.ts)
export class ProjectComposer {
  async createProject(projectName?: string) {
    await this.n8n.page.getByTestId('universal-add').click();
    await Promise.all([
      this.n8n.page.waitForResponse('**/rest/projects/*'),
      this.n8n.page.getByTestId('navigation-menu-item').filter({ hasText: 'Project' }).click(),
    ]);
    await this.n8n.notifications.waitForNotificationAndClose('saved successfully');
    await this.n8n.page.waitForLoadState();
    const projectNameUnique = projectName ?? `Project ${Date.now()}`;
    await this.n8n.projectSettings.fillProjectName(projectNameUnique);
    await this.n8n.projectSettings.clickSaveButton();
    const projectId = this.extractProjectIdFromPage('projects', 'settings');
    return { projectName: projectNameUnique, projectId };
  }
}

// 3. Test (projects/projects.spec.ts)
test('should filter credentials by project ID', async ({ n8n, api }) => {
  const { projectName, projectId } = await n8n.projectComposer.createProject();
  await n8n.projectComposer.addCredentialToProject(
    projectName,
    'Notion API',
    'apiKey',
    NOTION_API_KEY,
  );

  const credentials = await n8n.api.credentials.getCredentialsByProject(projectId);
  expect(credentials).toHaveLength(1);
});
```

--------------------------------

### Install n8n-node-dev CLI

Source: https://github.com/n8n-io/n8n/blob/master/packages/node-dev/README.md

Install the n8n-node-dev package globally using npm.

```bash
npm install n8n-node-dev -g
```

--------------------------------

### setup-credentials

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/instance-ai/docs/tools.md

Opens the credential picker UI, allowing the user to securely configure credentials. The AI does not handle secrets directly; user interaction is with the n8n frontend.

```APIDOC
## setup-credentials

### Description
Open the credential picker UI for the user to configure credentials securely. The LLM never sees secrets — the user interacts with the n8n frontend directly.

### Parameters
#### Query Parameters
- `credentialType` (string) - Required - Credential type to set up

### Response
#### Success Response (200)
- `credentialId` (string) - The ID of the newly configured credential.
- `credentialType` (string) - The type of the configured credential.
- `needsBrowserSetup` (boolean) - Optional - Indicates if further browser setup is required. If true, the `credential-setup-with-computer-use` skill should be loaded, and Computer Use `browser_*` tools used before calling `setup-credentials` again.
```

--------------------------------

### Start Backend Development

Source: https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md

Run the n8n backend in development mode. This command watches for changes and restarts the backend automatically.

```bash
cd packages/cli
pnpm dev
```

--------------------------------

### Install ESLint Plugin

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/eslint-plugin-community-nodes/README.md

Install the ESLint plugin and ESLint itself as development dependencies.

```sh
npm install --save-dev eslint @n8n/eslint-plugin-community-nodes
```

--------------------------------

### Page Objects Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Example of a page object interacting with UI components.

```typescript
await this.canvas.addNode('HTTP Request')
```

--------------------------------

### Node Test Harness Setup

Source: https://github.com/n8n-io/n8n/blob/master/packages/nodes-base/TESTING_PROMPT_WORKFLOW.md

Sets up tests for a node using the NodeTestHarness. Requires credentials and workflow file paths. Can assert binary data.

```typescript
import { NodeTestHarness } from '@nodes-testing/node-test-harness';
import nock from 'nock';

describe('NodeName', () => {
  const credentials = {
    nodeApi: {
      accessToken: 'test-token',
      baseUrl: 'https://api.example.com',
    },
  };

  describe('Basic Operations', () => {
    beforeAll(() => {
      const mock = nock(credentials.nodeApi.baseUrl);
      
      mock.get('/users')
        .reply(200, {
          users: [
            { id: 1, name: 'User 1', email: 'user1@example.com' },
            { id: 2, name: 'User 2', email: 'user2@example.com' }
          ]
        });
      
      mock.post('/users', {
        name: 'Test User',
        email: 'test@example.com'
      })
      .reply(201, {
        id: 123,
        name: 'Test User',
        email: 'test@example.com',
        status: 'active'
      });
    });

    new NodeTestHarness().setupTests({
      credentials,
      workflowFiles: ['basic.workflow.json']
    });
  });

  describe('Error Handling', () => {
    beforeAll(() => {
      const mock = nock(credentials.nodeApi.baseUrl);
      mock.get('/users')
        .reply(500, { error: 'Internal Server Error' });
    });

    new NodeTestHarness().setupTests({
      credentials,
      workflowFiles: ['error.workflow.json']
    });
  });

  describe('Binary Data Operations', () => {
    beforeAll(() => {
      const mock = nock(credentials.nodeApi.baseUrl);
      mock.post('/upload')
        .reply(200, {
          fileId: '123',
          fileName: 'test.txt',
          fileSize: 1024,
          mimeType: 'text/plain'
        });
    });

    new NodeTestHarness().setupTests({
      credentials,
      workflowFiles: ['binary.workflow.json'],
      assertBinaryData: true
    });
  });
});
```

--------------------------------

### Playwright API Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Example of using raw Playwright API methods for interaction.

```typescript
page.getByTestId(), page.locator(), page.click()
```

--------------------------------

### Playwright Test Example

Source: https://github.com/n8n-io/n8n/blob/master/packages/testing/janitor/README.md

Example of a Playwright test interacting with the application via flows.

```typescript
test('user can login', async ({ app }) => { ... })
```

--------------------------------

### Build Chat Bundle

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/README.md

Navigates to the chat package directory and builds the chat bundle using pnpm.

```bash
cd packages/frontend/@n8n/chat && pnpm run build 
```

--------------------------------

### Install n8n-workflow Package

Source: https://github.com/n8n-io/n8n/blob/master/packages/workflow/README.md

Install the n8n-workflow package using npm. This is the base code for n8n.

```bash
npm install n8n-workflow
```

--------------------------------

### Quick Start: Create and Use a CRDT Document

Source: https://github.com/n8n-io/n8n/blob/master/packages/@n8n/crdt/README.md

Demonstrates how to initialize a CRDT provider, create a document, use map data structures, and observe deep changes. Plain objects are synced as atomic values.

```typescript
import { createCRDTProvider, CRDTEngine } from '@n8n/crdt';

// Create provider
const provider = createCRDTProvider({ engine: CRDTEngine.yjs });

// Create document
const doc = provider.createDoc('workflow-123');

// Use data structures
const nodes = doc.getMap('nodes');
nodes.set('node-1', { position: { x: 100, y: 200 } });

// Plain objects are returned as-is (no automatic CRDT wrapping)
const node = nodes.get('node-1'); // Returns { position: { x: 100, y: 200 } }

// To update nested data, replace the whole object
nodes.set('node-1', { position: { x: 150, y: 200 } });

// Observe changes
nodes.onDeepChange((changes) => {
    for (const change of changes) {
        console.log(change.path, change.action, change.value);
        // ['node-1'], 'update', { position: { x: 150, y: 200 } }
    }
});
```