Microlink

Analytics Developer Tools SEO

v0.1.9

Last updated Aug 7, 2026

Microlink.io integration for n8n

6 Weekly Downloads

34 Monthly Downloads

View on NPM GitHub Repository

Included Nodes

Microlink

Description

n8n-nodes-microlink

> Microlink.io integration for n8n — fetch metadata, screenshots, PDFs, Markdown, plain text, audio/video sources, performance insights, logo data (including logo.palette), and more from any URL.

—

Installation

– In n8n (recommended)
– Local development

Credentials
Operations

– Extract
– Screenshot
– PDF
– Markdown
– Text
– Audio
– Video
– Insights
– Logo

Parameters Reference

– Top-level Parameters
– Response Mode
– Options
– Viewport Options
– PDF Options
– Screenshot Options
– JSON Options
– Additional Query Parameters

Internal Utilities

– isPlainObject
– flattenObject
– parseLooseValue
– Testing

– Transpiling TypeScript
– Running Tests
– Test Architecture
– Why These Tests
– Coverage

Publishing to n8n
License

—

Installation

In n8n (recommended)

1. Open your n8n instance.
2. Go to Settings > Community Nodes.
3. Enter n8n-nodes-microlink and click Install.
4. The Microlink node will appear in the node panel.

Local development

git clone https://github.com/microlinkhq/n8n-nodes-microlink.git
cd n8n-nodes-microlink
npm install
npm run build

To link the node into a local n8n instance for testing:

From this project's root
npm link
From your n8n installation directory
npm link n8n-nodes-microlink
Start n8n
npx n8n start

When developing locally, rebuild after source changes:

npm run build

—

Credentials

Create Microlink API credentials inside n8n:

The node automatically selects the correct endpoint based on whether an API key is present. When a key is provided, every request includes an x-api-key header.

—

Operations

The Microlink node exposes nine operations, each targeting a different capability of the Microlink API.

Extract

Default operation. Returns metadata and structured data for any URL — title, description, author, image, logo, publisher, language, and more.

Operation: Extract
URL: https://github.com
Response Mode: Auto

Returns the full Microlink API JSON response with status and data fields.

Screenshot

Generates a browser-rendered screenshot of the target page. Combines with viewport options and screenshot options for resolution, full-page captures, element targeting, overlays, and format control.

Operation: Screenshot
URL: https://example.com
Options → Screenshot Full Page: true
Options → Screenshot Type: jpeg

PDF

Generates a PDF document of the target page. Combines with viewport options and PDF options for rendering size, paper format, margins, landscape mode, and page ranges.

Operation: PDF
URL: https://example.com
Options → PDF Format: A4
Options → PDF Landscape: true

Markdown

Returns the page content converted to Markdown. This operation uses a specialized configuration under the hood — it sets force=true, meta=false, embed=markdown, and extracts the markdown via Microlink’s data + embed pattern.

Operation: Markdown
URL: https://example.com/blog/post

Returns the Markdown string directly as { data: "# Page Titlen..." }.

Text

Returns the page content converted to plain text. This operation mirrors Markdown behavior but uses text extraction under the hood — it sets force=true, meta=false, embed=text, and extracts text via Microlink’s data + embed pattern.

Operation: Text
URL: https://example.com/blog/post

Returns the plain text string directly as { data: "Page Title ..." }.

Audio

Detects and returns playable audio sources from the target page (e.g., podcasts, music embeds, audio players).

Operation: Audio
URL: https://soundcloud.com/artist/track

Video

Detects and returns playable video sources from the target page (e.g., YouTube, Vimeo, embedded players).

Operation: Video
URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ

Insights

Retrieves performance metrics and technology stack information for the target URL — Lighthouse scores, technology detection, and more.

Operation: Insights
URL: https://example.com

Logo

Returns logo metadata from the target page, including logo.palette.

Operation: Logo
URL: https://example.com

—

Parameters Reference

Top-level Parameters

Response Mode

| Mode | Behavior |
|——|———-|
| Auto | Returns JSON by default. If embed is set in the query string (explicitly or via the Markdown operation), returns text instead. |
| JSON | Always returns the full Microlink API JSON response. |
| Text | Returns the raw response body as { data: }. |
| Binary | Downloads the response as binary data (e.g., screenshot image, PDF file) and attaches it to the configured binary property. Sets encoding: null on the HTTP request. |

Options

All options are optional. Empty strings and zero values are automatically excluded from the request.
For screenshot, pdf, and insights, when nested options are present (e.g. screenshot.fullPage, pdf.width, insights.lighthouse), the node omits the top-level boolean (screenshot=true, pdf=true, insights=true) so nested values are not overridden.

#### Browser & Rendering

#### Data & Response

#### Caching & Network

Viewport Options

These options map to Microlink’s viewport.* API parameters and are compatible with screenshot and PDF rendering.

PDF Options

Screenshot Options

JSON Options

For complex structured parameters, the node provides dedicated JSON fields that are automatically flattened into dot-notation query parameters.

| Option | API Prefix | Description |
|——–|————|————-|
| Data (JSON) | data.* | Custom data extraction rules. Example: { "author": { "selector": ".author", "attr": "text" } } becomes data.author.selector=.author&data.author.attr=text. |
| Meta (JSON) | meta.* | Custom meta extraction rules. |
| Headers (JSON) | headers.* | Custom HTTP headers to send with the request. |
| Viewport (JSON) | viewport.* | Custom viewport dimensions and settings (advanced/nested form). |
| Insights (JSON) | insights.* | Insights configuration object. |

Additional Query Parameters

For any Microlink API parameter not covered by the built-in options, use Additional Query Parameters. Each entry is a key-value pair.

Keys support dot-notation (e.g., data.author.selector).
Values are automatically parsed: "true" / "false" become booleans, numeric strings become numbers, and JSON strings are parsed and flattened.
Additional parameters are applied last and override any previously set options.

This is also how to pass fields that support boolean or object payloads:

Key:   screenshot
Value: trueKey:   screenshot
Value: {"fullPage":true}

Key: data.price.selector Value: .product-price

Key: force Value: true

—

Internal Utilities

The node exports four internal utilities used to build query strings from the nested options structure. These are also available for import if you need to use them in other contexts.

isPlainObject

isPlainObject(value) → boolean

Returns true if value is a non-null, non-array object. Used throughout the node to decide whether a value should be recursively flattened or passed as-is.

flattenObject

flattenObject(prefix, obj, target) → void

Recursively flattens a nested object into dot-notation key-value pairs on the target object. Arrays are serialized to JSON strings.

| Input | Output |
|——-|——–|
| flattenObject('data', { author: { selector: '.a' } }, {}) | { 'data.author.selector': '.a' } |
| flattenObject('data', { tags: ['a', 'b'] }, {}) | { 'data.tags': '["a","b"]' } |
| flattenObject('', { key: 'val' }, {}) | { key: 'val' } |

This is essential for the Microlink API, which accepts nested parameters as flat dot-notation query string keys.

parseLooseValue

parseLooseValue(value) → boolean | number | object | array | string

Coerces string values from Additional Query Parameters into their natural JavaScript types:

| Input | Output | Type |
|——-|——–|——|
| "true" | true | boolean |
| "false" | false | boolean |
| "42" | 42 | number |
| "-3.14" | -3.14 | number |
| '{"a":1}' | { a: 1 } | object |
| '[1,2]' | [1, 2] | array |
| "hello" | "hello" | string |
| "1e5" | "1e5" | string (scientific notation is not parsed) |

Non-string inputs are returned unchanged. Invalid JSON-like strings (e.g., "{ invalid }") are kept as strings.

OBJECT_PARAMS

OBJECT_PARAMS = new Set(['data', 'meta', 'headers', 'viewport', 'insights'])

The set of parameter keys that, when their value is a plain object, should be flattened into dot-notation query parameters rather than passed directly. All other keys are passed as scalar values.

—

Testing

Transpiling TypeScript

This project is authored in TypeScript and compiled to dist/ for n8n runtime usage.

Compile source into dist/
npm run build

Generated artifacts:

dist/
  credentials/MicrolinkApi.credentials.js
  nodes/Microlink/Microlink.node.js
  nodes/Microlink/microlink.svg

Running Tests

Run all tests
npm test
Run tests in watch mode
npm test -- --watch
Run with coverage report
npm run test:coverage
Run a specific test file
npx jest nodes/Microlink/Microlink.node.test.js
npx jest credentials/MicrolinkApi.credentials.test.js

Test Architecture

Tests are colocated next to the source files they cover, following n8n’s own convention:

credentials/
  MicrolinkApi.credentials.ts          # source
  MicrolinkApi.credentials.test.js     # 12 tests
nodes/Microlink/
  Microlink.node.ts                    # source
  Microlink.node.test.js               # 240 tests

The n8n-workflow peer dependency is fully mocked — tests run without installing n8n itself. The mock provides NodeConnectionTypes.Main and a lightweight NodeOperationError class. The node’s execute() method is tested by constructing a mock execution context that replicates n8n’s runtime interface (getInputData, getNodeParameter, getCredentials, helpers.httpRequest, etc.) and calling execute.call(mockContext).

Why These Tests

The test suite is organized into focused layers, each with a distinct purpose:

| Layer | Tests | Why |
|——-|——-|—–|
| Utility functions (isPlainObject, flattenObject, parseLooseValue, OBJECT_PARAMS) | 27 | These pure functions are the foundation of query string construction. Testing them in isolation catches type-coercion bugs and edge cases (null, arrays, scientific notation, invalid JSON) before they propagate into API requests. |
| Credential structure | 12 | Credentials are loaded by n8n based on their declared structure. Incorrect names, missing defaults, or wrong types cause silent failures at runtime. These tests lock down the contract. |
| Node description | 17 | The description object is n8n’s UI contract — operations, property types, defaults, and display conditions. A missing operation or wrong default can break the entire node in the n8n editor. Structural tests prevent regressions. |
| Operations (9 operations) | 15 | Each operation maps to different query parameters. The markdown and text operations have special behavior (force, meta, embed, data extraction). Operation tests verify the correct flags reach the HTTP request. |
| Response modes (auto, json, text, binary) | 11 | Response handling has four distinct code paths including buffer conversion, binary property naming, and automatic text detection via embed. These tests verify each path produces the correct output shape. |
| Credentials & base URL | 7 | The node auto-selects between free (api.microlink.io) and pro (pro.microlink.io) endpoints, handles custom URLs, whitespace trimming, and null/undefined credentials. These tests cover every routing combination. |
| Simple options (boolean, string, number) | 58 | Every option type has different inclusion/exclusion rules: booleans pass through even when false, strings are excluded when empty, numbers are excluded when zero. Parametric it.each tests cover all options in both included and excluded states. |
| JSON options (data, meta, headers, viewport, insights) | 9 | JSON options are merged with existing values and flattened into dot-notation. The merge logic is subtle — markdown/text operations pre-set data, and insights can be a boolean that needs overwriting. These tests verify correct merging and flattening. |
| Additional parameters | 7 | Additional params are the escape hatch for any API parameter. They support type coercion, JSON flattening, and override previously set values. Tests cover parsing, empty-key skipping, and override behavior. |
| Query string building | 4 | Validates the final assembly: URL is always present, nulls are filtered, objects are flattened, scalars pass through. |
| Error handling | 5 | Tests the three error paths: NodeOperationError wrapping, context preservation with itemIndex, and continueOnFail graceful degradation. |
| Multiple items | 2 | n8n processes items in batches. Tests verify independent per-item processing and that errors in one item don’t block others when continueOnFail is enabled. |
| Option overrides & combinations | 6 | Real-world usage combines operations with options, credentials with additional params, and overrides at multiple levels. Integration-style tests verify these combinations work together correctly. |
| Request shape | 6 | HTTP method, json flag, and encoding must be set correctly for every response mode. These tests are the final gate before the request leaves the node. |

Coverage

------------------------------|---------|----------|---------|---------|
File                          | % Stmts | % Branch | % Funcs | % Lines |
------------------------------|---------|----------|---------|---------|
All files                     |   99.24 |    96.09 |     100 |     100 |
 MicrolinkApi.credentials.ts  |     100 |      100 |     100 |     100 |
 Microlink.node.ts            |   99.21 |    96.09 |     100 |     100 |
------------------------------|---------|----------|---------|---------|

254 tests across 2 test suites. 100% line and function coverage.

—

Publishing to n8n

This package is published to npm by GitHub Actions with a provenance statement. Since 2026-05-01, n8n verified community nodes must be published from CI with provenance — nodes published from a local machine are rejected for verification. (A plain local npm publish still works for an unverified npm/community install, but it will not pass verification.)

The release pipeline lives in .github/workflows/publish.yml: on every published GitHub Release it runs lint, tests, and build, then npm publish --provenance --access public.

1. Prerequisites

A npm account with publish rights to the package.
The package.json name field must start with n8n-nodes- (already set to n8n-nodes-microlink).
The n8n field in package.json must list all credential and node files (already configured).
The keywords array must include "n8n-community-node-package" (already present).

2. One-time setup: `NPM_TOKEN` secret

1. Create an npm Automation (or Granular) access token with publish rights.
2. In the GitHub repo, open Settings → Secrets and variables → Actions → New repository secret.
3. Name it NPM_TOKEN and paste the token.

3. Verify locally before releasing

CI re-runs these, but check them first to avoid a failed release:

npm run lint
npm test
npm run build

4. Cut a release

npm version patch   # 0.1.0 → 0.1.1 (bug fixes); use minor / major as appropriate
git push --follow-tags

Then create a GitHub Release for the new tag (Releases → Draft a new release → choose the tag → Publish release). Publishing the release triggers publish.yml, which publishes to npm with provenance.

5. Verify the publish

Watch the Actions tab for the “Publish to npm” run to finish green.
Visit https://www.npmjs.com/package/n8n-nodes-microlink and confirm the Provenance badge appears on the new version.

6. Install in n8n

Once published, any n8n user can install it:

1. Open Settings > Community Nodes in their n8n instance.
2. Search for n8n-nodes-microlink.
3. Click Install.

The node appears in the editor immediately — no restart required on n8n Cloud. Self-hosted instances may need a restart.

7. Subsequent releases

Repeat steps 3–5: bump the version, push the tag, and publish a GitHub Release. n8n Cloud picks up new versions automatically; self-hosted users update via Settings > Community Nodes > Update.

—

Included Nodes

Description

n8n-nodes-microlink

Installation

In n8n (recommended)

Local development

From this project's root

From your n8n installation directory

Start n8n