url-normalize

Features

• HTTPS by default
• Flexible configuration
• Custom protocols (e.g. tg://)
• Domain extraction
• Support both CJS & ESM modules

Install

yarn add url-normalize

Usage

import { urlNormalize } from "url-normalize"

urlNormalize("example.com")
// -> "https://example.com"

urlNormalize("//www.example.com:443/../foo/bar?b=2&a=1#tag")
// -> "https://example.com/foo/bar?a=1&b=2#tag"

// all invalid urls is null
urlNormalize("example")
// -> null

Configuration

defaultProtocol (default: https)

Default supported protocols are: http, https

urlNormalize("example.com", { defaultProtocol: "http" })
// -> "http://example.com"

urlNormalize("example.com", { defaultProtocol: "ftps" })
// -> ftps://example.com

// BUT keeps original protocol if it in url
urlNormalize("https://example.com", { defaultProtocol: "http" })
// -> "https://example.com"

keepProtocol (default: true)

urlNormalize("https://example.com")
// -> "https://example.com"

urlNormalize("https://example.com", { keepProtocol: false })
// -> "example.com"

urlNormalize("https://example.com/foo?bar=baz", { keepProtocol: false })
// -> "example.com/foo?bar=baz"

keepWWW (default: false)

urlNormalize("www.example.com")
// -> "https://example.com"

urlNormalize("www.example.com", { keepWWW: true })
// -> "https://www.example.com"

keepAuth (default: false)

urlNormalize("https://user:[email protected]")
// -> "https://example.com"

urlNormalize("https://user:[email protected]", { keepAuth: true })
// -> "https://user:[email protected]"

keepPort (default: false)

urlNormalize("https://example.com:8080")
// -> "https://example.com"

urlNormalize("https://example.com:8080", { keepPort: true })
// -> "https://example.com:8080"

// BUT for HTTP - 80 & HTTPS - 443 always without port
urlNormalize("https://example.com:443", { keepPort: true })
// -> "https://example.com"

keepDirectoryIndex (default: true)

urlNormalize("example.com/index.html")
// -> "https://example.com/index.html"

urlNormalize("example.com/index.html", { keepDirectoryIndex: false })
// -> "https://example.com"

keepQueryParams (default: true)

urlNormalize("example.com/?a=1&b=2")
// -> "https://example.com/?a=1&b=2"

urlNormalize("example.com/?a=1&b=2", { keepQueryParams: false })
// -> "https://example.com"

sortQueryParams (default: true)

urlNormalize("example.com/?b=2&b=1")
// -> "https://example.com/?a=1&b=2"

urlNormalize("example.com/?b=2&b=1", { sortQueryParams: false })
// -> "https://example.com/?b=2&b=1"

keepHash (default: true)

urlNormalize("example.com/#foo")
// -> "https://example.com/#foo"

urlNormalize("example.com/?b=2&b=1", { keepHash: false })
// -> "https://example.com"

keepTextFragment (default: false)

urlNormalize("example.com/#:~:text=hello")
// -> "https://example.com"

urlNormalize("example.com/?b=2&b=1", { keepTextFragment: true })
// -> "https://example.com/#:~:text=hello"

allowCustomProtocol (default: false)

urlNormalize("ftps://example.com")
// -> null

urlNormalize("tg://example.com")
// -> null

urlNormalize("ftps://example.com", { allowCustomProtocol: true })
// -> "ftps://example.com"

urlNormalize("tg://example.com", { allowCustomProtocol: true })
// -> "tg://example.com"

forceProtocol

urlNormalize("https://example.com", { forceProtocol: "sftp" })
// -> "sftp://example.com"

urlNormalize("tg://example.com", { forceProtocol: "we" })
// -> "we://example.com"

Advanced

urlNormalizeOrFail

import { urlNormalize, urlNormalizeOrFail } from "url-normalize"

urlNormalize("invalid")
// -> null

urlNormalizeOrFail("invalid")
// throws Error

extractDomain

import { extractDomain, extractDomainOrFail } from "url-normalize"

extractDomain("https://example.com:8080/?a=1&b=2#tag")
// -> "example.com"

extractDomain("invalid")
// -> null

extractDomainOrFail("invalid")
// throws Error

createUrlNormalize

import { createUrlNormalize } from "url-normalize"

const urlNormalize = createUrlNormalize({
  defaultProtocol: "http",
  keepHash: false,
})

urlNormalize("example.com/foo#tag")
// -> "http://example.com/foo"

Similar projects

• sindresorhus/normalize-url