{"id":11943,"library":"resolve-pathname","title":"URL Pathname Resolver","description":"The `resolve-pathname` package, currently at stable version 3.0.0, offers a pure JavaScript implementation for resolving URL pathnames. Its core purpose is to replicate the exact pathname resolution behavior found in web browsers when processing the `href` attribute of an `<a>` tag. This utility is distinct from Node.js's `url.resolve`, which handles full URLs, and from other browser-specific solutions like `resolve-url` that may have DOM dependencies. It prides itself on 100% compatibility with browser pathname resolution rules without relying on a DOM environment. The package is typically very stable with an infrequent release cadence for major versions, indicating a mature and well-tested codebase. It is suitable for both Node.js and browser environments, with ESM, CommonJS, and UMD builds available.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mjackson/resolve-pathname","tags":["javascript"],"install":[{"cmd":"npm install resolve-pathname","lang":"bash","label":"npm"},{"cmd":"yarn add resolve-pathname","lang":"bash","label":"yarn"},{"cmd":"pnpm add resolve-pathname","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary function is exported as a default export in ESM contexts.","wrong":"import { resolvePathname } from 'resolve-pathname';","symbol":"resolvePathname","correct":"import resolvePathname from 'resolve-pathname';"},{"note":"Standard CommonJS import for Node.js environments or older bundlers. Using ES module syntax will fail.","wrong":"import resolvePathname from 'resolve-pathname';","symbol":"resolvePathname","correct":"const resolvePathname = require('resolve-pathname');"},{"note":"When included via a `<script>` tag (UMD build), the function is available globally on the `window` object.","wrong":"resolvePathname();","symbol":"resolvePathname","correct":"window.resolvePathname;"}],"quickstart":{"code":"import resolvePathname from 'resolve-pathname';\n\n// Example 1: Resolving a relative path from a specific base path.\nconst resolved1 = resolvePathname('about', '/company/jobs');\nconsole.log(`'/company/jobs' + 'about' -> ${resolved1}`); // Expected: /company/about\n\n// Example 2: Resolving a parent path from a nested base path.\nconst resolved2 = resolvePathname('../jobs', '/company/team/ceo');\nconsole.log(`'/company/team/ceo' + '../jobs' -> ${resolved2}`); // Expected: /company/jobs\n\n// Example 3: Resolving a path when no base path is provided (defaults to '/').\nconst resolved3 = resolvePathname('about');\nconsole.log(`'/' + 'about' -> ${resolved3}`); // Expected: /about\n\n// Example 4: Resolving an absolute path (base path is ignored).\nconst resolved4 = resolvePathname('/about');\nconsole.log(`'/company/info/some-path' + '/about' -> ${resolved4}`); // Expected: /about\n\n// Example 5: Index paths (trailing slash on base) are supported, similar to browsers.\nconst resolved5 = resolvePathname('new-page', '/company/info/');\nconsole.log(`'/company/info/' + 'new-page' -> ${resolved5}`); // Expected: /company/info/new-page\n\n// Simulating browser environment with window.location.pathname\n// Assume window.location.pathname is '/company/team/ceo'\nconst mockLocationPathname = '/company/team/ceo';\nconst resolvedBrowser1 = resolvePathname('cto', mockLocationPathname);\nconsole.log(`'${mockLocationPathname}' + 'cto' -> ${resolvedBrowser1}`); // Expected: /company/team/cto\n\nconst resolvedBrowser2 = resolvePathname('../jobs', mockLocationPathname);\nconsole.log(`'${mockLocationPathname}' + '../jobs' -> ${resolvedBrowser2}`); // Expected: /company/jobs","lang":"javascript","description":"Demonstrates various pathname resolution scenarios, including relative and absolute paths, handling of base paths, and browser-like behavior with trailing slashes."},"warnings":[{"fix":"If you need to resolve full URLs, consider `url.resolve` in Node.js or `new URL(relative, base).href` in modern browser/Node.js environments.","message":"This package is designed exclusively for resolving *pathnames*, not full URLs (e.g., it ignores scheme, host, port, query, hash). Do not confuse it with Node.js's built-in `url.resolve` which operates on full URLs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always explicitly provide the `from` argument if the resolution should be relative to a specific path other than the root `/`.","message":"When the `from` (base) pathname argument is omitted or falsy, `resolve-pathname` defaults it to `/`. This can lead to unexpected absolute paths if you intended a different base.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Be mindful of trailing slashes in your base path; ensure consistency based on whether the base represents a directory or a file path.","message":"The behavior of `resolve-pathname` with trailing slashes on the `from` path is identical to browsers. For instance, `resolvePathname('bar', '/foo/')` results in `/foo/bar`, whereas `resolvePathname('bar', '/foo')` results in `/bar` (effectively navigating up from '/foo' as a file).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure you are using `import` statements for ES Modules and `require()` for CommonJS modules. If transpiling, configure your build system correctly to handle module interoperability.","message":"Using `require()` for this package in an ESM-only environment (or vice-versa) can lead to module resolution errors, especially in modern Node.js or bundlers that enforce ES modules.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For ES Modules, use `import resolvePathname from 'resolve-pathname';`. For CommonJS, use `const resolvePathname = require('resolve-pathname');`.","cause":"Attempting to import `resolvePathname` as a named export when it is a default export, or incorrect module syntax (e.g., `import` in a CommonJS context).","error":"TypeError: resolvePathname is not a function"},{"fix":"Always provide the `from` argument, e.g., `resolvePathname('my-path', '/base');` or `resolvePathname('my-path', window.location.pathname);`.","cause":"The `from` (base) pathname argument was omitted or was `null`/`undefined`, causing `resolve-pathname` to default the base to `/`.","error":"Path resolved to unexpected absolute path (e.g., `/my-path` instead of `/base/my-path`)"}],"ecosystem":"npm"}