{"_id":"url-extras","_rev":"4171595","name":"url-extras","description":"Browser-compatible implementations of some of Node.js' URL utilities","dist-tags":{"latest":"0.1.0"},"maintainers":[{"name":"sindresorhus","email":""}],"time":{"modified":"2026-03-01T21:18:54.000Z","created":"2025-11-03T20:22:07.263Z","0.1.0":"2025-11-03T20:22:07.263Z"},"users":{},"author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"repository":{"type":"git","url":"git+https://github.com/sindresorhus/url-extras.git"},"versions":{"0.1.0":{"name":"url-extras","version":"0.1.0","description":"Browser-compatible implementations of some of Node.js' URL utilities","license":"MIT","repository":{"type":"git","url":"git+https://github.com/sindresorhus/url-extras.git"},"funding":"https://github.com/sponsors/sindresorhus","author":{"name":"Sindre Sorhus","email":"sindresorhus@gmail.com","url":"https://sindresorhus.com"},"type":"module","exports":{"types":"./index.d.ts","default":"./index.js"},"sideEffects":false,"engines":{"node":">=20"},"scripts":{"test":"xo && node --test tests/*.js && tsc index.d.ts"},"keywords":["url","file","path","file-url","path-url","fileurltopath","pathtofileurl","browser","compatible","polyfill","cross-platform","windows","unc"],"devDependencies":{"typescript":"^5.3.3","xo":"^0.56.0"},"xo":{"rules":{"@typescript-eslint/naming-convention":"off","n/prefer-global/process":"off"}},"gitHead":"e60b6c9e403d458b22b9259a9567fd69cc38ffc8","types":"./index.d.ts","_id":"url-extras@0.1.0","bugs":{"url":"https://github.com/sindresorhus/url-extras/issues"},"homepage":"https://github.com/sindresorhus/url-extras#readme","_nodeVersion":"20.19.5","_npmVersion":"11.6.1","dist":{"shasum":"905c5f3d1d2d6284d9731c87625bbfa702fdadad","size":3861,"noattachment":false,"key":"/url-extras/-/url-extras-0.1.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/url-extras/download/url-extras-0.1.0.tgz"},"_npmUser":{"name":"sindresorhus","email":"sindresorhus@gmail.com"},"directories":{},"maintainers":[{"name":"sindresorhus","email":""}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/url-extras_0.1.0_1762201327069_0.7463632144798671"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2025-11-03T20:22:07.263Z","publish_time":1762201327263,"_source_registry_name":"default","_cnpm_publish_time":1762201327263}},"readme":"# url-extras\n\n> Browser-compatible implementations of some of Node.js' URL utilities\n\nBrowser-compatible versions of Node.js' [`url.fileURLToPath()`](https://nodejs.org/api/url.html#urlfileurltopathurl-options) and [`url.pathToFileURL()`](https://nodejs.org/api/url.html#urlpathtofileurlpath-options).\n\n## Why?\n\nModern bundlers like Vite and Webpack 5+ don't polyfill Node.js core modules. This package provides zero-dependency implementations using only standard JavaScript APIs that work everywhere.\n\n## Features\n\n- Browser-compatible (uses only standard JavaScript APIs)\n- Zero dependencies\n- Cross-platform (Windows drive letters, UNC paths, Unix paths)\n- TypeScript support\n- Tree-shakeable ESM\n\n## Install\n\n```sh\nnpm install url-extras\n```\n\n## Usage\n\n```js\nimport {fileURLToPath} from 'url-extras';\n\n// Convert file URL to path\nfileURLToPath('file:///Users/user/file.txt');\n//=> '/Users/user/file.txt'\n```\n\n## API\n\n### fileURLToPath(url, options?)\n\nConvert a file URL to a file path.\n\nPlatform-aware: On Windows (or when `options.windows` is `true`), drive letters (e.g., `file:///C:/`) are converted to Windows paths (e.g., `C:\\`), and UNC paths (e.g., `file://server/share`) are converted to Windows UNC format (e.g., `\\\\server\\share`). On Unix-like systems (or when `options.windows` is `false`), file URLs with hostnames (except `localhost`) will throw an error, matching Node.js behavior.\n\n```js\nimport {fileURLToPath} from 'url-extras';\n\nfileURLToPath('file:///Users/user/file.txt');\n//=> '/Users/user/file.txt'\n\nfileURLToPath('file:///C:/Users/user/file.txt');\n//=> 'C:\\\\Users\\\\user\\\\file.txt' (on Windows)\n\nfileURLToPath(new URL('file:///Users/user/file.txt'));\n//=> '/Users/user/file.txt'\n\n// UNC paths work on Windows but throw on Unix\nfileURLToPath('file://server/share/file.txt');\n//=> '\\\\\\\\server\\\\share\\\\file.txt' (on Windows)\n//=> Throws TypeError (on Unix - hostnames not allowed)\n\n// Explicit platform control\nfileURLToPath('file:///C:/test', {windows: true});\n//=> 'C:\\\\test'\n\nfileURLToPath('file:///C:/test', {windows: false});\n//=> '/C:/test'\n```\n\n#### url\n\nType: `string | URL`\n\nThe file URL to convert.\n\n#### options\n\nType: `object`\n\n##### windows\n\nType: `boolean`\\\nDefault: Auto-detected in Node.js, `false` in browsers\n\nExplicitly specify whether to use Windows path rules.\n\n- When `undefined` (default), automatically detects based on the runtime platform (`process.platform`).\n- When `true`, Windows-style paths are used (backslashes, drive letters, UNC paths).\n- When `false`, Unix-style paths are used (forward slashes only).\n\nIn browsers where `process.platform` is not available, this defaults to `false` (Unix rules).\n\n### pathToFileURL(path, options?)\n\nConvert a file path to a file URL.\n\nThe path must be absolute. Throws a `TypeError` if the path is not absolute.\n\nReturns a `URL` object.\n\nOn Windows (or when `options.windows` is `true`), handles drive letters (e.g., `C:\\` → `file:///C://`, `C:\\path` → `file:///C:/path`) and UNC paths (e.g., `\\\\server\\share` → `file://server/share`). Drive letter case is preserved. On Unix-like systems (or when `options.windows` is `false`), converts absolute paths to `file:///` URLs.\n\n**Note:** Unlike Node.js, this implementation requires absolute paths and will throw for relative paths, maintaining browser compatibility.\n\n```js\nimport {pathToFileURL} from 'url-extras';\n\npathToFileURL('/Users/user/file.txt');\n//=> URL { href: 'file:///Users/user/file.txt', ... }\n\npathToFileURL('/Users/user/file.txt').href;\n//=> 'file:///Users/user/file.txt'\n\npathToFileURL('C:\\\\Users\\\\user\\\\file.txt').href;\n//=> 'file:///C:/Users/user/file.txt'\n\npathToFileURL('C:\\\\').href;\n//=> 'file:///C://'\n\npathToFileURL('\\\\\\\\server\\\\share\\\\file.txt').href;\n//=> 'file://server/share/file.txt'\n\n// Explicit platform control\npathToFileURL('C:\\\\test', {windows: true}).href;\n//=> 'file:///C:/test'\n\npathToFileURL('/C:/test', {windows: false}).href;\n//=> 'file:///C:/test' (colon is valid in Unix paths)\n```\n\n#### path\n\nType: `string`\n\nThe absolute file path to convert.\n\n#### options\n\nType: `object`\n\nPlatform behavior options.\n\n##### windows\n\nType: `boolean`\\\nDefault: Auto-detected in Node.js, `false` in browsers\n\nExplicitly specify whether to use Windows path rules.\n\n- When `undefined` (default), automatically detects based on the runtime platform (`process.platform`).\n- When `true`, Windows-style paths are used (backslashes, drive letters, UNC paths).\n- When `false`, Unix-style paths are used (forward slashes only).\n\nIn browsers where `process.platform` is not available, this defaults to `false` (Unix rules).\n\n## Related\n\n- [normalize-url](https://github.com/sindresorhus/normalize-url) - Normalize a URL\n","_attachments":{},"homepage":"https://github.com/sindresorhus/url-extras#readme","bugs":{"url":"https://github.com/sindresorhus/url-extras/issues"},"license":"MIT"}