WHATWG URL Utilities

2.4.1 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: require is not a function
```
cause 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
```
cause 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: ...
```
cause 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.

Warnings

gotcha When 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';`.
gotcha While `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';`.
breaking Although 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.

Install

npm install bare-url npm
yarn add bare-url yarn
pnpm add bare-url pnpm

Imports

fileURLToPath
wrong:
```
const { fileURLToPath } = require('bare-url');
```
correct:
```
import { fileURLToPath } from '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
wrong:
```
import pathToFileURL from 'bare-url/pathToFileURL';
```
correct:
```
import { pathToFileURL } from 'bare-url';
```
Utility functions are typically exported as named exports from the main module entry point.
URL
wrong:
```
const URL = require('bare-url').URL;
```
correct:
```
import { URL } from 'bare-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.

Quickstart

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

view raw JSON →