posthtml-fetch

library4.0.3jsnpmunverified

PostHTML plugin that fetches remote or local content and interpolates it into HTML using posthtml-expressions. Current stable version: 4.0.3. Release cadence is irregular; the plugin is mature and stable. Key differentiators: simple declarative <fetch> tag, supports JSON and text responses, integrates with PostHTML ecosystem, uses ofetch under the hood for HTTP, and allows configuration of tag names, URL attribute, and expression options. It is designed for server-side rendering and build-time content injection, not for dynamic client-side fetching.

devops

npm install posthtml-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · POSTHTML-FETCH

posthtml-fetch

devopsjavascriptv4.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

posthtmlFetch

✓ import posthtmlFetch from 'posthtml-fetch'

✗ const posthtmlFetch = require('posthtml-fetch')

CommonJS require works but the package ships ESM types; use named import only if using ESM. Default import is the correct pattern.

Plugin

✓ import type { PostHtmlFetch } from 'posthtml-fetch'

✗ import { Options } from 'posthtml-fetch'

The package exports a default function and a type named PostHtmlFetch; Options is not explicitly exported from v4. Check types for exact names.

default import

✓ import posthtmlFetch from 'posthtml-fetch'

✗ import { posthtmlFetch } from 'posthtml-fetch'

Named import is incorrect; the plugin is exported as default. Use default import (no curly braces).

require-style import

✓ const posthtmlFetch = require('posthtml-fetch')

Works in CommonJS environments; TypeScript types still available.

Shows basic usage: posthtml-fetch fetches a remote JSON API and interpolates response fields into HTML using mustache-like expressions.

import posthtml from 'posthtml'; import posthtmlFetch from 'posthtml-fetch'; const html = ` <fetch url="https://jsonplaceholder.typicode.com/users/1"> {{ response.name }}'s username is {{ response.username }} </fetch> `; posthtml() .use(posthtmlFetch()) .process(html) .then(result => { console.log(result.html); // Output: Leanne Graham's username is Bret });

Debug

Known issues

breakingIn v3, the plugin used 'node-fetch' as a dependency. v4 replaced it with 'ofetch', which may behave differently (e.g., default timeout, retries).

fix

Upgrade without code changes but test for subtle differences in HTTP handling (e.g., error messages, redirect behavior).

affects: >=4.0.0

deprecatedThe 'attr' option used in v2/v3 was renamed to 'attribute' in v4. Using 'attr' will not work.

fix

Use 'attribute' instead of 'attr' when passing options.

affects: >=4.0.0

gotchaThe plugin only supports JSON and text responses. If the remote server returns XML or binary data, the response will be empty or cause an error.

fix

Ensure the URL returns JSON or text; or use posthtml-expressions to transform the response manually.

affects: >=2.0.0

gotchaThe 'tags' option default is ['fetch', 'remote']; custom tags must be passed explicitly. If you omit 'tags', only those two tag names are processed.

fix

Pass tags: ['myTag'] if you want to use a different tag name.

affects: >=2.0.0

gotchaUsing 'preserveTag: true' keeps the original <fetch> tag in output, which may not be valid HTML or may interfere with styling.

fix

Set preserveTag: false (default) to remove the tag after interpolation.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'ofetch'

Missing peer dependency 'ofetch' when using v4. The package requires 'ofetch' but it is not listed as a peer dependency, so it may not be auto-installed.

fix

Run 'npm install ofetch' alongside posthtml-fetch.

TypeError: posthtmlFetch is not a function

Using named import instead of default import (e.g., import { posthtmlFetch } from 'posthtml-fetch')

fix

Use default import: import posthtmlFetch from 'posthtml-fetch'

SyntaxError: Unexpected token 'export'

The package uses ESM modules and your Node project is using CommonJS require() without transpilation.

fix

Use import() dynamic import or switch to ESM ("type": "module" in package.json). For CommonJS, use const posthtmlFetch = require('posthtml-fetch').default or enable esModuleInterop.

The 'attr' option was removed in v4. Use 'attribute' instead.

Passing 'attr' in options object, which was renamed in v4.

fix

Rename 'attr' to 'attribute' in the options passed to posthtmlFetch().

Upgrade

Version history

4.0.3latest on npm

Audit

Dependencies

posthtmlrequiredPeer dependency; posthtml-fetch is a PostHTML plugin and requires posthtml to process HTML

Agent activity

10 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/posthtml/posthtml-fetch ↗

packageposthtml-fetch ↗

homepagehttps://github.com/posthtml/posthtml-fetch ↗