URL Pathname Resolver

3.0.0 · active · verified Sun Apr 19

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.

Common errors

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

fix For ES Modules, use `import resolvePathname from 'resolve-pathname';`. For CommonJS, use `const resolvePathname = require('resolve-pathname');`.
```
Path resolved to unexpected absolute path (e.g., `/my-path` instead of `/base/my-path`)
```
cause The `from` (base) pathname argument was omitted or was `null`/`undefined`, causing `resolve-pathname` to default the base to `/`.

fix Always provide the `from` argument, e.g., `resolvePathname('my-path', '/base');` or `resolvePathname('my-path', window.location.pathname);`.

Warnings

gotcha 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.
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.
gotcha 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.
Fix: Always explicitly provide the `from` argument if the resolution should be relative to a specific path other than the root `/`.
gotcha 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).
Fix: Be mindful of trailing slashes in your base path; ensure consistency based on whether the base represents a directory or a file path.
gotcha 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.
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.

Install

npm install resolve-pathname npm
yarn add resolve-pathname yarn
pnpm add resolve-pathname pnpm

Imports

resolvePathname

wrong:

import { resolvePathname } from 'resolve-pathname';

correct:

import resolvePathname from 'resolve-pathname';

The primary function is exported as a default export in ESM contexts.

resolvePathname
wrong:
```
import resolvePathname from 'resolve-pathname';
```
correct:
```
const resolvePathname = require('resolve-pathname');
```
Standard CommonJS import for Node.js environments or older bundlers. Using ES module syntax will fail.
resolvePathname
wrong:
```
resolvePathname();
```
correct:
```
window.resolvePathname;
```
When included via a `<script>` tag (UMD build), the function is available globally on the `window` object.

Quickstart

Demonstrates various pathname resolution scenarios, including relative and absolute paths, handling of base paths, and browser-like behavior with trailing slashes.

import resolvePathname from 'resolve-pathname';

// Example 1: Resolving a relative path from a specific base path.
const resolved1 = resolvePathname('about', '/company/jobs');
console.log(`'/company/jobs' + 'about' -> ${resolved1}`); // Expected: /company/about

// Example 2: Resolving a parent path from a nested base path.
const resolved2 = resolvePathname('../jobs', '/company/team/ceo');
console.log(`'/company/team/ceo' + '../jobs' -> ${resolved2}`); // Expected: /company/jobs

// Example 3: Resolving a path when no base path is provided (defaults to '/').
const resolved3 = resolvePathname('about');
console.log(`'/' + 'about' -> ${resolved3}`); // Expected: /about

// Example 4: Resolving an absolute path (base path is ignored).
const resolved4 = resolvePathname('/about');
console.log(`'/company/info/some-path' + '/about' -> ${resolved4}`); // Expected: /about

// Example 5: Index paths (trailing slash on base) are supported, similar to browsers.
const resolved5 = resolvePathname('new-page', '/company/info/');
console.log(`'/company/info/' + 'new-page' -> ${resolved5}`); // Expected: /company/info/new-page

// Simulating browser environment with window.location.pathname
// Assume window.location.pathname is '/company/team/ceo'
const mockLocationPathname = '/company/team/ceo';
const resolvedBrowser1 = resolvePathname('cto', mockLocationPathname);
console.log(`'${mockLocationPathname}' + 'cto' -> ${resolvedBrowser1}`); // Expected: /company/team/cto

const resolvedBrowser2 = resolvePathname('../jobs', mockLocationPathname);
console.log(`'${mockLocationPathname}' + '../jobs' -> ${resolvedBrowser2}`); // Expected: /company/jobs

view raw JSON →