Prepend HTTP/S Protocol to URLs

4.0.0 · active · verified Wed Apr 22

prepend-http is a focused utility package designed to ensure URLs have a proper `http://` or `https://` protocol prefix. It intelligently adds `https://` (by default) to "humanized" URLs such as domain names (`sindresorhus.com`) or `localhost` entries, while leaving already-prefixed URLs untouched. The package is currently stable at version `4.0.0`, released recently in response to ecosystem changes. Historically, releases are infrequent but significant, often tied to Node.js LTS updates or module system shifts. A key differentiator is its simplicity and reliability, provided by a well-regarded maintainer in the JavaScript ecosystem. Since version 4, prepend-http is a pure ESM package, aligning with modern JavaScript module practices, and requires Node.js 12.20 or newer.

Common errors

```
ERR_REQUIRE_ESM
```
cause Attempting to use CommonJS `require()` to import `prepend-http`, which is a pure ESM package since v4.0.0.

fix Change `const prependHttp = require('prepend-http');` to `import prependHttp from 'prepend-http';`. Ensure your environment supports ESM (e.g., `"type": "module"` in `package.json`).
```
TypeError: prependHttp is not a function
```
cause This error can occur if an ES Module (ESM) is incorrectly imported into a CommonJS (CJS) context, or if the default export is not correctly accessed when dynamically importing ESM into CJS.

fix Ensure you are using `import prependHttp from 'prepend-http';` in an ESM context. If you must `require` from a CJS file, consider using dynamic `import()`: `const { default: prependHttp } = await import('prepend-http');` (requires `async/await`).
```
ReferenceError: require is not defined
```
cause Attempting to use `require()` in an ES Module context (e.g., in a file where `"type": "module"` is set in `package.json` or the file has a `.mjs` extension).

fix Replace `const prependHttp = require('prepend-http');` with `import prependHttp from 'prepend-http';` and ensure all other dependencies are imported using `import` statements.

Warnings

breaking Starting with v4.0.0, `prepend-http` is a pure ES Module (ESM). CommonJS `require()` statements will no longer work and will throw an `ERR_REQUIRE_ESM` error.
Fix: Update all imports to use ESM `import` syntax (e.g., `import prependHttp from 'prepend-http';`). Ensure your Node.js project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions).
breaking Version 4.0.0 requires Node.js 12.20.0 or higher (or 14.13.1 or >=16.0.0). Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js runtime to version 12.20.0, 14.13.1, or any version 16.0.0 or newer.
breaking The `https` option now defaults to `true` since v3.0.0. Previously, it defaulted to `false` in versions prior to 3.0.0, meaning `prependHttp('example.com')` would have resulted in `http://example.com`.
Fix: If you require `http://` by default, explicitly pass `{ https: false }` as the second argument: `prependHttp(url, { https: false })`.
breaking Version 3.0.0 required Node.js 8 or higher. Older Node.js versions were no longer supported from this version onwards.
Fix: Upgrade your Node.js runtime to version 8 or higher. (Note: v4.0.0 requires an even newer Node.js version, see other warnings).

Install

npm install prepend-http npm
yarn add prepend-http yarn
pnpm add prepend-http pnpm

Imports

prependHttp
wrong:
```
const prependHttp = require('prepend-http');
```
correct:
```
import prependHttp from 'prepend-http';
```
Since v4.0.0, this package is pure ESM. CommonJS `require()` is no longer supported and will result in an `ERR_REQUIRE_ESM` error.
Options
wrong:
```
import { Options } from 'prepend-http';
```
correct:
```
import type { Options } from 'prepend-http';
```
The type definition for the `options` object is typically exported as `Options`. Use `import type` for type-only imports to prevent potential bundling issues or unnecessary code inclusion.

Quickstart

Demonstrates how to use `prependHttp` with various URL inputs, including defaulting to `https`, explicitly using `http`, and handling already-prefixed URLs.

import prependHttp from 'prepend-http';

// Example 1: Basic usage - prepends https:// by default
const url1 = 'sindresorhus.com';
const prefixedUrl1 = prependHttp(url1);
console.log(`'${url1}' -> '${prefixedUrl1}'`);
// Expected: 'sindresorhus.com' -> 'https://sindresorhus.com'

// Example 2: Explicitly prepend http://
const url2 = 'localhost:3000';
const prefixedUrl2 = prependHttp(url2, { https: false });
console.log(`'${url2}' -> '${prefixedUrl2}'`);
// Expected: 'localhost:3000' -> 'http://localhost:3000'

// Example 3: URL already has a protocol - should be untouched
const url3 = 'ftp://example.com/file.txt';
const prefixedUrl3 = prependHttp(url3);
console.log(`'${url3}' -> '${prefixedUrl3}'`);
// Expected: 'ftp://example.com/file.txt' -> 'ftp://example.com/file.txt'

// Example 4: Mixed case - ensure consistency
const url4 = 'http://github.com';
const prefixedUrl4 = prependHttp(url4);
console.log(`'${url4}' -> '${prefixedUrl4}'`);
// Expected: 'http://github.com' -> 'http://github.com'

view raw JSON →