Relative URLs in JavaScript: Why a Missing Trailing Slash Changes the Path

The same filename resolves differently when the base changes from /docs/ to /docs. Relative URL resolution follows URL structure rather than string concatenation. A trailing slash determines which path components remain.

example.com and example.org are illustrative domains. All examples construct URLs in memory without network requests.

1. A trailing slash changes the base directory

const directory = new URL('intro.html', 'https://example.com/docs/');
const document = new URL('intro.html', 'https://example.com/docs');

console.log(directory.href); // https://example.com/docs/intro.html
console.log(document.href);  // https://example.com/intro.html

/docs/ supplies the current directory. In /docs, the final component is replaced when intro.html is resolved. The parser does not ask a server whether docs is a file or directory.

Specify whether configuration contains a directory base or a document URL. Appending a slash indiscriminately can conflict with existing queries, fragments and intended semantics.

2. A leading slash resets the path to the origin root

const base = 'https://example.com/app/docs/';
console.log(new URL('guide.html', base).pathname);  // /app/docs/guide.html
console.log(new URL('/guide.html', base).pathname); // /guide.html
console.log(new URL('../guide.html', base).pathname); // /app/guide.html

A root-relative path does not retain /app/docs/. This matters for applications deployed under a directory prefix. Parent-relative ../ follows the base directory instead. Choose references according to resource location.

3. Queries and fragments resolve separately

const base = 'https://example.com/docs/page.html?lang=vi#old';
console.log(new URL('?page=2', base).href);
// https://example.com/docs/page.html?page=2
console.log(new URL('#new', base).href);
// https://example.com/docs/page.html?lang=vi#new
console.log(new URL('', base).href);
// https://example.com/docs/page.html?lang=vi

A new query replaces the old query and drops the old fragment. A new fragment retains the base path and query. The empty reference shown here retains the document and query but drops the fragment.

To add a parameter while retaining others, construct a URL and use searchParams. URL resolution and parameter-value encoding are separate operations.

4. A base does not confine input to one website

const base = 'https://example.com/app/';
console.log(new URL('https://example.org/news', base).href);
// https://example.org/news
console.log(new URL('//example.org/news', base).href);
// https://example.org/news

An absolute URL selects its own destination. A // reference inherits the scheme but chooses another host. Supplying a base does not establish an internal-link policy.

Restricted destinations need checks on the resolved URL according to product requirements, including protocol, origin and credentials where appropriate. Matching origin does not replace resource authorization. This is not a complete redirect or SSRF validator.

5. Parsing does not establish resource existence

try {
  new URL('/guide.html');
} catch (error) {
  console.log(error.name); // TypeError
}

const url = new URL('missing.html', 'https://example.com/docs/');
console.log(url.href); // https://example.com/docs/missing.html

A relative path requires a valid base. Successfully constructing missing.html does not establish an HTTP 200 response. Resource checks require a separate step suitable for the resource and permissions.

The constructor can stringify inputs. Validate types explicitly at boundaries that require strings so missing values do not turn into unintended paths.

6. Useful resolution cases

• Directory bases with trailing slashes and document bases without them.
• Current-directory, root-relative and parent-relative paths.
• Bases with existing queries and fragments.
• Query-only, fragment-only and empty references.
• Absolute URLs and // references selecting another host.
• Missing or invalid bases and boundary type errors.
• Root and subdirectory-prefix deployments.

The snippets ran locally with Node.js without networking. Application routers, HTML base elements and reverse-proxy behavior were not tested. References: the URL constructor and relative-reference resolution.

Inspect the resolved URL rather than guessing from input text. A small slash can distinguish the current directory from the website root.