bare-url

library2.4.1jsnpmunverified

bare-url is a JavaScript library providing a WHATWG URL Standard-compliant implementation for parsing, formatting, and manipulating URLs. As of version 2.4.1, it offers a robust set of utilities, including conversions between file paths and URL objects. It ships with comprehensive TypeScript type definitions, enabling strong type-checking in modern development environments. The package is actively maintained, indicated by its numerous versions and frequent recent updates, ensuring adherence to the evolving WHATWG standard. While Node.js provides a global `URL` class that aligns with the WHATWG specification, `bare-url` can serve as a consistent, lightweight alternative or a reliable polyfill in environments where the native `URL` might be absent, outdated, or exhibit inconsistent behavior. Its focus is on providing a dependable, spec-compliant URL API.

http-networking serialization

npm install bare-url

github ↗package ↗

INSTALL

IMPORT

SIG · BARE-URL

bare-url

http-networkingjavascriptv2.4.1

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.

fileURLToPath

✓ import { fileURLToPath } from 'bare-url';

✗ const { fileURLToPath } = require('bare-url');

For ES Modules, prefer named imports. CommonJS `require()` is still supported but discouraged in modern Node.js applications and not supported in browsers for module loading.

pathToFileURL

✓ import { pathToFileURL } from 'bare-url';

✗ import pathToFileURL from 'bare-url/pathToFileURL';

Utility functions are typically exported as named exports from the main module entry point.

URL

✓ import { URL } from 'bare-url';

✗ const URL = require('bare-url').URL;

The library exports its own `URL` constructor, which may extend or wrap the native `URL` global. In most modern environments, the global `URL` is also available and WHATWG compliant; use `bare-url`'s `URL` for consistency if you're already using its other utilities or need specific polyfill behavior.

Demonstrates converting between file paths and URLs, and parsing a complex URL string into its components using the `bare-url` utilities.

import { fileURLToPath, pathToFileURL, URL } from 'bare-url'; // Convert a file URL to a path string const filePath = fileURLToPath('file:///home/user/document.txt'); console.log(`File URL to path: ${filePath}`); // Expected: /home/user/document.txt // Convert a path string to a file URL const fileUrl = pathToFileURL('/usr/local/data/report.pdf'); console.log(`Path to file URL: ${fileUrl.toString()}`); // Expected: file:///usr/local/data/report.pdf // Create and parse a new URL object const myUrl = new URL('https://example.com:8080/path/to/resource?query=param#hash'); console.log(` Parsed URL details:` + `\n Origin: ${myUrl.origin}` + `\n Hostname: ${myUrl.hostname}` + `\n Port: ${myUrl.port}` + `\n Pathname: ${myUrl.pathname}` + `\n Search Params: ${myUrl.searchParams.get('query')}`); // Expected: example.com, 8080, /path/to/resource, param

Debug

Known issues

gotchaWhen migrating from CommonJS `require()` to ES Modules `import`, ensure you use named imports as `bare-url` exports its utilities and `URL` class as named exports. Directly destructuring from `require('bare-url')` might yield different results or fail in an ESM context.

fix

Replace `const url = require('bare-url');` with `import * as url from 'bare-url';` or `const { fileURLToPath } = require('bare-url');` with `import { fileURLToPath } from 'bare-url';`.

affects: >=2.0.0

gotchaWhile `bare-url` provides a WHATWG-compliant `URL` constructor, modern Node.js environments (v10.0.0+ onwards) have a global `URL` object that also adheres to the WHATWG Standard. Evaluate if `bare-url`'s specific implementation is necessary for your environment or if the global `URL` is sufficient to avoid potential bundle size increases.

fix

For Node.js projects, consider testing with the global `URL` first. If cross-environment consistency or specific polyfill requirements dictate, then use `import { URL } from 'bare-url';`.

affects: >=2.0.0

breakingAlthough no explicit major breaking changes between v1 and v2 were immediately apparent in release notes, major version bumps often imply breaking changes in API surface or behavior. Developers upgrading across major versions should consult the package's changelog on GitHub to identify specific breaking changes that might affect their application, particularly regarding strict WHATWG compliance updates.

fix

Always review the official GitHub releases and changelog when upgrading `bare-url` across major versions. Update your code to align with any new API specifications or behavioral changes.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: require is not a function

Attempting to use CommonJS `require()` syntax in an ES Module (ESM) file.

fix

Change `const url = require('bare-url');` to `import * as url from 'bare-url';` or `import { fileURLToPath } from 'bare-url';`.

TypeError: url.fileURLToPath is not a function

Incorrectly importing `bare-url` in an ES Module context, or trying to access a named export as a property of a default import when the package doesn't provide a default export object with those properties.

fix

Ensure you are using named imports for specific functions: `import { fileURLToPath } from 'bare-url';` or importing the entire module object: `import * as url from 'bare-url';` and then `url.fileURLToPath`.

TypeError [ERR_INVALID_URL]: Invalid URL: ...

The input string provided to `new URL()` or `fileURLToPath()` is not a valid URL or file path according to WHATWG URL parsing rules.

fix

Validate your input strings to ensure they adhere to valid URL formats, including proper protocol prefixes (e.g., 'https://', 'file:///') and legal characters. Use `try...catch` blocks to handle URL parsing errors gracefully.

Upgrade

Version history

2.4.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/holepunchto/bare-url ↗

packagehttps://www.npmjs.com/package/bare-url ↗