{"id":10563,"library":"bare-url","title":"WHATWG URL Utilities","description":"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.","status":"active","version":"2.4.1","language":"javascript","source_language":"en","source_url":"https://github.com/holepunchto/bare-url","tags":["javascript","typescript"],"install":[{"cmd":"npm install bare-url","lang":"bash","label":"npm"},{"cmd":"yarn add bare-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add bare-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { fileURLToPath } = require('bare-url');","symbol":"fileURLToPath","correct":"import { fileURLToPath } from 'bare-url';"},{"note":"Utility functions are typically exported as named exports from the main module entry point.","wrong":"import pathToFileURL from 'bare-url/pathToFileURL';","symbol":"pathToFileURL","correct":"import { pathToFileURL } from 'bare-url';"},{"note":"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.","wrong":"const URL = require('bare-url').URL;","symbol":"URL","correct":"import { URL } from 'bare-url';"}],"quickstart":{"code":"import { fileURLToPath, pathToFileURL, URL } from 'bare-url';\n\n// Convert a file URL to a path string\nconst filePath = fileURLToPath('file:///home/user/document.txt');\nconsole.log(`File URL to path: ${filePath}`);\n// Expected: /home/user/document.txt\n\n// Convert a path string to a file URL\nconst fileUrl = pathToFileURL('/usr/local/data/report.pdf');\nconsole.log(`Path to file URL: ${fileUrl.toString()}`);\n// Expected: file:///usr/local/data/report.pdf\n\n// Create and parse a new URL object\nconst myUrl = new URL('https://example.com:8080/path/to/resource?query=param#hash');\nconsole.log(`\nParsed URL details:`\n  + `\\n  Origin: ${myUrl.origin}`\n  + `\\n  Hostname: ${myUrl.hostname}`\n  + `\\n  Port: ${myUrl.port}`\n  + `\\n  Pathname: ${myUrl.pathname}`\n  + `\\n  Search Params: ${myUrl.searchParams.get('query')}`);\n// Expected: example.com, 8080, /path/to/resource, param","lang":"typescript","description":"Demonstrates converting between file paths and URLs, and parsing a complex URL string into its components using the `bare-url` utilities."},"warnings":[{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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';`.","message":"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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const url = require('bare-url');` to `import * as url from 'bare-url';` or `import { fileURLToPath } from 'bare-url';`.","cause":"Attempting to use CommonJS `require()` syntax in an ES Module (ESM) file.","error":"TypeError: require is not a function"},{"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`.","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.","error":"TypeError: url.fileURLToPath is not a function"},{"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.","cause":"The input string provided to `new URL()` or `fileURLToPath()` is not a valid URL or file path according to WHATWG URL parsing rules.","error":"TypeError [ERR_INVALID_URL]: Invalid URL: ..."}],"ecosystem":"npm"}