Registry / http-networking / html-metadata-parser

html-metadata-parser

library2.0.4jsnpmunverified

html-metadata-parser is a JavaScript library for Node.js environments, specializing in the extraction and parsing of metadata from HTML documents. It efficiently scrapes Open Graph (OG) tags, standard HTML meta tags, and image URLs from a given web page. The library provides a single, promise-based `parser` function that takes a URL as input and returns a structured object containing the discovered `og`, `meta`, and `images` data. The current stable version is 2.0.4, with development appearing to be active, although without a strictly defined public release cadence. Its key differentiator lies in its straightforward API for server-side metadata extraction, making it highly suitable for applications requiring functionalities like link previews, social media card generation, or general web content analysis. The package also ships with comprehensive TypeScript type definitions, providing an enhanced development experience for TypeScript users.

http-networking data serialization

npm install html-metadata-parser

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · HTML-METADATA-PARS

html-metadata-parser

http-networkingjavascriptv2.0.4

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

parser

✓ import { parser } from 'html-metadata-parser';

✗ import parser from 'html-metadata-parser';

The `parser` function is a named export. Default import will result in `undefined`.

parser (CommonJS)

✓ const { parser } = require('html-metadata-parser');

✗ const parser = require('html-metadata-parser');

When using CommonJS, `parser` must be destructured as it's a named export, not the default module export.

MetadataResult (TypeScript Type)

✓ import type { MetadataResult } from 'html-metadata-parser';

For TypeScript projects, it is recommended to import the `MetadataResult` type for type-checking the parser's output.

This quickstart demonstrates how to use `html-metadata-parser` to asynchronously fetch and parse metadata from a given URL, including error handling.

import { parser, type MetadataResult } from 'html-metadata-parser'; const targetUrl = 'https://www.youtube.com/watch?v=eSzNNYk7nVU'; (async () => { try { console.log(`Attempting to parse metadata from: ${targetUrl}`); const result: MetadataResult = await parser(targetUrl); if (result) { console.log('Successfully parsed metadata:\n'); console.log(JSON.stringify(result, null, 2)); } else { console.log('No metadata found or parsed successfully.'); } // Example of accessing specific metadata console.log(`\nOpen Graph Title: ${result.og?.title || 'N/A'}`); console.log(`Meta Description: ${result.meta?.description || 'N/A'}`); } catch (error) { console.error('An error occurred during metadata parsing:'); if (error instanceof Error) { console.error(error.message); } else { console.error(String(error)); } } })();

Debug

Known issues

gotchaThe library relies on network requests. Unreliable network connectivity, DNS issues, or target server downtime can lead to `FetchError` or `ENOTFOUND` errors. Implement robust error handling for network-related failures.

fix

Wrap calls to `parser` in a `try...catch` block and handle specific network error codes or messages. Consider retries with a backoff strategy for transient issues.

affects: >=1.0.0

gotchaParsing large or poorly structured HTML documents can be resource-intensive, potentially leading to increased memory usage or slow response times. Performance may vary significantly depending on the target URL's content.

fix

For very large documents, consider alternative parsing strategies or optimize resource handling. Monitor memory and CPU usage in production environments and apply timeouts to prevent hanging operations.

affects: >=1.0.0

gotchaRepeated scraping of the same website can lead to IP blocking or rate limiting by the target server, resulting in HTTP 429 (Too Many Requests) or other access denied errors.

fix

Implement delays between requests, cache results, or consider using a proxy rotation service if frequent requests to the same domain are necessary. Always respect `robots.txt`.

affects: >=1.0.0

gotchaThe `parser` function may return `null` or an object with `undefined` properties if specific metadata (e.g., Open Graph tags, meta description) is not present on the target page. Direct access without null-checking can lead to `TypeError`.

fix

Always perform nullish coalescing or optional chaining (e.g., `result.og?.title`) when accessing properties of the parsed metadata object to prevent runtime errors.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'title')

Attempting to access a property on an `og` or `meta` object that does not exist or is `undefined` because the target page lacked that specific metadata.

fix

Use optional chaining (`?.`) or nullish coalescing (`??`) when accessing metadata properties, e.g., `result.og?.title` or `result.meta?.description ?? 'No description'`. Always check if `result` itself is truthy.

FetchError: request to https://example.com failed, reason: getaddrinfo ENOTFOUND example.com

The hostname could not be resolved (DNS error), or the URL is malformed/unreachable. This is a network-related issue.

fix

Verify the URL is correct and accessible from your network. Check your DNS configuration or ensure there's no firewall blocking outbound requests. The error indicates the requested domain does not exist or cannot be reached.

TypeError: parser is not a function

Incorrect import or require statement, often attempting to use `import parser from 'html-metadata-parser';` or `const parser = require('html-metadata-parser');` instead of named destructuring.

fix

Use named import for ESM: `import { parser } from 'html-metadata-parser';` or named require for CommonJS: `const { parser } = require('html-metadata-parser');`

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/nasa8x/html-metadata-parser ↗

packagehttps://www.npmjs.com/package/html-metadata-parser ↗

homepagehttps://morioh.com/topic/node-js ↗