Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
234 lines (157 loc) · 7.4 KB

CONTRIBUTING.md

File metadata and controls

234 lines (157 loc) · 7.4 KB

Contributing to n8n-nodes-alterlab

Thank you for your interest in contributing to the AlterLab n8n community node. This is an open-source project and contributions of all kinds are welcome — bug fixes, new features, documentation improvements, and issue reports.

Please read this guide before opening an issue or submitting a pull request.

Table of Contents

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. By participating, you agree to abide by its terms. Please report unacceptable behavior to support@alterlab.io.

Getting Started

Prerequisites:

  • Node.js 18 or later
  • npm 8 or later
  • An AlterLab account and API key (see API Key for Testing)
  • A local or self-hosted n8n instance for end-to-end testing

Fork and clone the repository:

git clone https://github.com/<your-username>/n8n-nodes-alterlab.git
cd n8n-nodes-alterlab

Install dependencies:

npm install

Development Environment

The project is a standard n8n community node package written in TypeScript. The directory structure is:

nodes/           # Node source files (.ts)
credentials/     # Credential definitions (.ts)
dist/            # Compiled output (generated by build — do not edit)
assets/          # Images referenced in README
gulpfile.js      # Copies SVG icons to dist during build
tsconfig.json    # TypeScript configuration

Available scripts:

Script Command Description
Build npm run build Compiles TypeScript and copies icons to dist/
Watch npm run dev Rebuilds on file changes (development mode)
Type-check npm run lint Runs tsc --noEmit without emitting output

Run npm run build after any source change before testing with n8n.

Building and Testing

Build the package:

npm run build

This runs tsc followed by gulp build:icons. The compiled output lands in dist/.

Type-check without building:

npm run lint

This catches TypeScript errors without writing any files. Run this before opening a pull request.

Watch mode during development:

npm run dev

This watches nodes/ and credentials/ and recompiles on save. Note that gulp build:icons does not run in watch mode — run npm run build once at the start to copy icons, then use npm run dev for iterative development.

Testing with a Live n8n Instance

The most reliable way to test changes is to link the package into a local n8n installation using npm link.

Step 1 — Link the package globally:

cd n8n-nodes-alterlab
npm run build
npm link

Step 2 — Link into your n8n instance:

n8n loads community nodes from its custom extensions directory. The default path is ~/.n8n/custom/. Link the package there:

cd ~/.n8n/custom
npm link n8n-nodes-alterlab

If the custom/ directory does not exist:

mkdir -p ~/.n8n/custom
cd ~/.n8n/custom
npm init -y
npm link n8n-nodes-alterlab

Step 3 — Start n8n:

npx n8n

The AlterLab node should appear in the node picker under "AlterLab". If it does not appear, restart n8n after rebuilding.

Step 4 — After code changes:

Rebuild and restart n8n to pick up the changes:

npm run build
# then restart n8n

Code Style

The project uses TypeScript strict mode ("strict": true in tsconfig.json). The following conventions apply throughout the codebase:

TypeScript:

  • Use explicit types on function parameters and return values. Avoid implicit any.
  • Use interface for object shapes that describe data structures; use type for unions and intersections.
  • Prefer const over let. Never use var.
  • Use async/await rather than raw Promise chains.
  • Destructure objects and arrays where it improves readability.

n8n node conventions:

  • Node display names use title case: "AlterLab", not "alterlab" or "Alterlab".
  • Parameter names use camelCase in TypeScript, but the name field in node parameter definitions must match exactly what the n8n UI displays.
  • Use this.getNodeParameter() to read parameters inside execute(). Do not access parameters directly from the node description.
  • Always include a description field on every parameter definition — it appears as a tooltip in the UI.
  • Use NodeOperationError for user-facing errors (these surface cleanly in the n8n UI). Use NodeApiError when wrapping API responses.
  • The execute() method must return INodeExecutionData[][]. Process all input items in a loop — do not assume a single item.

Credential conventions:

  • Credential classes extend ICredentialType.
  • All credential properties must declare a type, name, displayName, and (where applicable) default.
  • OAuth2 credentials must include authenticate and test definitions.

General:

  • Do not leave commented-out code in pull requests.
  • Do not introduce new dependencies without discussion in the issue thread first. The dependencies field in package.json is intentionally empty — this package has zero runtime dependencies.

Submitting a Pull Request

  1. Fork the repository on GitHub.
  2. Create a branch from main using a descriptive name: 
    git checkout -b fix/credential-oauth-refresh
# or
git checkout -b feat/add-proxy-country-list
  3. Make your changes. Keep each pull request focused on a single concern.
  4. Build and type-check: 
    npm run build
npm run lint
  5. Commit with a short, clear message in the imperative mood: Fix OAuth2 token refresh on expired credentials, not Fixed the thing.
  6. Push your branch and open a pull request against main.
  7. Fill in the pull request template. Incomplete pull requests will be delayed.

Pull requests that change node behavior should include a description of how you tested the change against a live n8n instance. Purely TypeScript-level fixes can include type-check output as evidence.

Reporting Issues

Before opening an issue, please:

  • Search existing issues to check whether it has already been reported.
  • Confirm the issue is reproducible on the latest published version of the package.

Use the GitHub issue templates:

  • Bug report — for crashes, incorrect output, authentication failures, or other defects.
  • Feature request — for new capabilities, new extraction profiles, or parameter additions.

For support questions (not bugs), use support@alterlab.io or the AlterLab documentation.

API Key for Testing

Testing against the AlterLab API requires an account and API key.

Sign up at app.alterlab.io — new accounts receive $1 free balance, which is enough for several thousand test scrapes at the lowest tier.

Do not commit API keys or credentials to the repository. If you accidentally expose a key, revoke it immediately from your dashboard and generate a new one.