v5.0.1 Dynamically import puppeteer

Author: brahma-dev

README.md

@@ -1,13 +1,27 @@
 # Node metafetch
 
 [![Build Status](https://github.com/brahma-dev/metafetch/actions/workflows/build.yml/badge.svg)](https://github.com/brahma-dev/metafetch/actions/workflows/build.yml)
-[![codecov](https://codecov.io/gh/brahma-dev/metafetch/branch/master/graph/badge.svg)](https://codecov.io/gh/brahma-dev/metafetch)
+[![codecov](https://codecov.io/gh/brahma-dev/metafetch/branch/main/graph/badge.svg)](https://codecov.io/gh/brahma-dev/metafetch)
 [![coveralls](https://coveralls.io/repos/github/brahma-dev/metafetch/badge.svg?branch=main)](https://coveralls.io/github/brahma-dev/metafetch?branch=main)
 [![Known Vulnerabilities](https://snyk.io/test/npm/metafetch/badge.svg?style=flat)](https://snyk.io/test/npm/metafetch)
 [![NPM version](https://img.shields.io/npm/v/metafetch.svg?style=flat)](https://www.npmjs.org/package/metafetch)
 
 **Metafetch** is a library to fetch and parse metadata from a web page. It can extract standard meta tags, Open Graph data, JSON-LD, favicons, and feeds, and even render client-side JavaScript to get data from Single-Page Applications (SPAs).
 
+## Table of Contents
+
+-   [Key Features](#key-features)
+-   [Installation](#installation)
+-   [Usage](#usage)
+    -   [Basic Example](#basic-example)
+    -   [Advanced Example (Rendering SPAs & Retries)](#advanced-example-rendering-spas--retries)
+-   [API](#api)
+    -   [`metafetch.fetch(url, [options])`](#metafetchfetchurl-options)
+    -   [Available Flags](#available-flags)
+-   [Instance Management](#instance-management)
+-   [Response Data](#response-data)
+-   [License](#license)
+
 ## Key Features
 
 *   **Comprehensive Metadata:** Extracts title, description, URL, site name, images, links, and more.
@@ -25,9 +39,10 @@
 Use NPM to install:
 
 ```bash
-npm install metafetch puppeteer
+npm install metafetch
 ```
-*Note: `puppeteer` is a peer dependency and must be installed separately if you want to use the client-side rendering feature.*
+
+*Note: **`puppeteer`** is a peer dependency and must be installed separately (`npm install puppeteer`) if you want to use the SPA / client-side rendering feature.*
 
 ## Usage
 
@@ -59,6 +74,7 @@ This will output a representative object like this:
   type: 'article',
   url: 'https://example.com/article-path',
   originalURL: 'https://example.com',
+  ampURL: 'https://example.com/article-path/amp',
   siteName: 'Example News',
   charset: 'utf-8',
   image: 'https://example.com/images/featured-image.png',

package-lock.json

@@ -1,7 +1,7 @@
 {
   "name": "metafetch",
   "description": "Metafetch fetches a given URL's title, description, images, links etc.",
-  "version": "5.0.0",
+  "version": "5.0.1",
   "homepage": "https://github.com/brahma-dev/metafetch",
   "repository": {
     "type": "git",
@@ -25,7 +25,12 @@
     "linkedom": "^0.18.11"
   },
   "peerDependencies": {
-    "puppeteer": "^24.16.1"
+    "puppeteer": ">=22.0.0 <25.0.0"
+  },
+  "peerDependenciesMeta": {
+    "puppeteer": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@istanbuljs/nyc-config-typescript": "^1.0.2",

package.json

@@ -1,6 +1,5 @@
 import { parseHTML } from 'linkedom';
 import type { Document } from 'linkedom';
-import puppeteer from 'puppeteer';
 
 /**
  * The shape of the response object returned by Metafetch.
@@ -80,6 +79,14 @@ export class Metafetch {
 		return this.#userAgent;
 	}
 
+	/**
+	 * Wrapper for dynamic import of puppeteer to improve testability.
+	 * @private
+	 */
+	private async _getPuppeteer() {
+		return import('puppeteer');
+	}
+
 	/**
 	 * Fetches and parses metadata from a given URL.
 	 * @param url The URL to fetch.
@@ -112,6 +119,15 @@ export class Metafetch {
 				let encoding: string;
 
 				if (options.render) {
+					let puppeteer;
+					try {
+						const puppeteerModule = await this._getPuppeteer();
+						puppeteer = puppeteerModule.default;
+					} catch (err) {
+						throw new Error(
+							'The "render" option requires the "puppeteer" package. Please install it (`npm install puppeteer`) and try again.'
+						);
+					}
 					const browser = await puppeteer.launch({
 						headless: true, args: [
 							'--no-sandbox',

src/index.ts

@@ -37,7 +37,7 @@ describe('Metafetch: Optimized Tests', () => {
 					res.setHeader('Content-Type', 'text/html; charset=iso-8859-1').end('<body></body>');
 					return;
 				case '/charset-meta':
-					res.setHeader('Content-Type', 'text/html'); 
+					res.setHeader('Content-Type', 'text/html');
 					body = '<head><meta charset="windows-1252"></head>';
 					break;
 				case '/base-tag':
@@ -470,6 +470,21 @@ describe('Metafetch: Optimized Tests', () => {
 				expect(err.message).to.equal("Received an empty response body.");
 			}
 		});
+
+		it('should throw a helpful error when puppeteer fails to import', async () => {
+			const newInstance = new Metafetch();
+			// Stub the private method to simulate an import failure
+			const importStub = sinon.stub(newInstance as any, '_getPuppeteer').rejects(new Error('Simulated import failure'));
+
+			try {
+				await newInstance.fetch(`${BASE_URL}/page`, { render: true });
+				throw new Error("Test failed: Metafetch should have thrown an error.");
+			} catch (err: any) {
+				expect(err.message).to.equal('The "render" option requires the "puppeteer" package. Please install it (`npm install puppeteer`) and try again.');
+			} finally {
+				importStub.restore();
+			}
+		});
 	});
 
 	describe('Request Retries', () => {