@xof/url

A lightweight URL parser, formatter, and resolver for Node.js with Internationalized Domain Name (IDN) support.

✨ Features

• ⚡ Lightweight and dependency-free
• 🌍 Internationalized Domain Name (IDN) support
• 🔗 URL parsing
• 📝 URL formatting
• 🧩 Relative URL resolution
• 🌐 IPv4 & IPv6 hostname support
• 📦 CommonJS compatible
• 🚀 Works on Node.js 16+

📦 Installation

npm

npm install @xof/url

pnpm

pnpm add @xof/url

Yarn

yarn add @xof/url

🚀 Usage

const url = require("@xof/url");

🔍 Parse URL

const url = require("@xof/url");

const parsed = url.parse(
  "https://user:[email protected]:8080/docs/index.html?name=xof&lang=en#about"
);

console.log(parsed);

Output

{
  protocol: "https:",
  slashes: true,
  auth: "user:pass",
  host: "example.com:8080",
  port: "8080",
  hostname: "example.com",
  hash: "#about",
  search: "?name=xof&lang=en",
  query: "name=xof&lang=en",
  pathname: "/docs/index.html",
  path: "/docs/index.html?name=xof&lang=en"
}

📋 Parse Query Object

Pass true as the second argument to automatically parse the query string.

const url = require("@xof/url");

const parsed = url.parse(
  "https://example.com/?page=1&limit=20",
  true
);

console.log(parsed.query);

Output

{
  page: "1",
  limit: "20"
}

📝 Format URL

const url = require("@xof/url");

const formatted = url.format({
  protocol: "https",
  slashes: true,
  hostname: "example.com",
  pathname: "/docs",
  query: {
    page: 1,
    sort: "latest"
  }
});

console.log(formatted);

Output

https://example.com/docs?page=1&sort=latest

🔗 Resolve Relative URL

const url = require("@xof/url");

const result = url.resolve(
  "https://example.com/docs/tutorial/",
  "../guide/getting-started"
);

console.log(result);

Output

https://example.com/docs/guide/getting-started

🧩 Resolve URL Object

const url = require("@xof/url");

const result = url.resolveObject(
  "https://example.com/docs/",
  "../api"
);

console.log(result);

🏗️ Create URL Instance

const { Url } = require("@xof/url");

const u = new Url();

u.protocol = "https:";
u.slashes = true;
u.hostname = "example.com";
u.pathname = "/hello";

console.log(u.format());

Output

https://example.com/hello

🌍 Internationalized Domain Name (IDN)

Unicode domain names are automatically converted to ASCII (Punycode).

const url = require("@xof/url");

const parsed = url.parse(
  "https://münich.com"
);

console.log(parsed.hostname);

Output

xn--mnich-kva.com

📚 API

| Method | Description | |--------|-------------| | parse(url, parseQueryString, slashesDenoteHost) | Parse a URL string. | | format(object) | Format a URL object into a URL string. | | resolve(from, to) | Resolve a relative URL. | | resolveObject(from, to) | Resolve and return a URL object. | | new Url() | Create a new URL instance. |

✅ Node.js Compatibility

| Version | Supported | |---------|:---------:| | 16.x | ✅ | | 18.x | ✅ | | 20.x | ✅ | | 22.x | ✅ |

📄 License

This project is licensed under the MIT License.

See the LICENSE file for details.

Made with ❤️ by XOF Copyright © 2026 XOF