sindresorhus/normalize-urlPublic

NotificationsYou must be signed in to change notification settings
Fork124
Star861

Normalize a URL

License

MIT license

861 stars 124 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 173 Commits
.github		.github
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.npmrc		.npmrc
index.d.ts		index.d.ts
index.js		index.js
index.test-d.ts		index.test-d.ts
license		license
package.json		package.json
readme.md		readme.md
test.js		test.js

Repository files navigation

normalize-url

Normalize a URL

Useful when you need to display, store, deduplicate, sort, compare, etc, URLs.

Note: This package doesnot do URL sanitization.Garbage in, garbage out. If you use this in a server context and accept URLs as user input, it's up to you to protect against invalid URLs,path traversal attacks, etc.

Install

npm install normalize-url

Usage

importnormalizeUrlfrom'normalize-url';normalizeUrl('sindresorhus.com');//=> 'http://sindresorhus.com'normalizeUrl('//www.sindresorhus.com:80/../baz?b=bar&a=foo');//=> 'http://sindresorhus.com/baz?a=foo&b=bar'

API

normalizeUrl(url, options?)

URLs with custom protocols are not normalized and just passed through by default. Supported protocols are:https,http,file, anddata.

Human-friendly URLs with basic auth (for example,user:password@sindresorhus.com) are not handled because basic auth conflicts with custom protocols.Basic auth URLs are also deprecated.

url

Type:string

URL to normalize, includingdata URL.

options

Type:object

defaultProtocol

Type:string
Default:'http'
Values:'https' | 'http'

normalizeProtocol

Type:boolean
Default:true

PrependdefaultProtocol to the URL if it's protocol-relative.

normalizeUrl('//sindresorhus.com');//=> 'http://sindresorhus.com'normalizeUrl('//sindresorhus.com',{normalizeProtocol:false});//=> '//sindresorhus.com'

forceHttp

Type:boolean
Default:false

Normalize HTTPS to HTTP.

normalizeUrl('https://sindresorhus.com');//=> 'https://sindresorhus.com'normalizeUrl('https://sindresorhus.com',{forceHttp:true});//=> 'http://sindresorhus.com'

forceHttps

Type:boolean
Default:false

Normalize HTTP to HTTPS.

normalizeUrl('http://sindresorhus.com');//=> 'http://sindresorhus.com'normalizeUrl('http://sindresorhus.com',{forceHttps:true});//=> 'https://sindresorhus.com'

This option cannot be used with theforceHttp option at the same time.

stripAuthentication

Type:boolean
Default:true

Strip theauthentication part of the URL.

normalizeUrl('https://user:password@sindresorhus.com');//=> 'https://sindresorhus.com'normalizeUrl('https://user:password@sindresorhus.com',{stripAuthentication:false});//=> 'https://user:password@sindresorhus.com'

stripHash

Type:boolean
Default:false

Strip the hash part of the URL.

normalizeUrl('sindresorhus.com/about.html#contact');//=> 'http://sindresorhus.com/about.html#contact'normalizeUrl('sindresorhus.com/about.html#contact',{stripHash:true});//=> 'http://sindresorhus.com/about.html'

stripProtocol

Type:boolean
Default:false

Remove the protocol from the URL:http://sindresorhus.com →sindresorhus.com.

It will only removehttps:// andhttp:// protocols.

normalizeUrl('https://sindresorhus.com');//=> 'https://sindresorhus.com'normalizeUrl('https://sindresorhus.com',{stripProtocol:true});//=> 'sindresorhus.com'

stripTextFragment

Type:boolean
Default:true

Strip thetext fragment part of the URL.

Note: The text fragment will always be removed if thestripHash option is set totrue, as the hash contains the text fragment.

normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello');//=> 'http://sindresorhus.com/about.html#'normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello');//=> 'http://sindresorhus.com/about.html#section'normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello',{stripTextFragment:false});//=> 'http://sindresorhus.com/about.html#:~:text=hello'normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello',{stripTextFragment:false});//=> 'http://sindresorhus.com/about.html#section:~:text=hello'

stripWWW

Type:boolean
Default:true

Removewww. from the URL.

normalizeUrl('http://www.sindresorhus.com');//=> 'http://sindresorhus.com'normalizeUrl('http://www.sindresorhus.com',{stripWWW:false});//=> 'http://www.sindresorhus.com'

removeQueryParameters

Type:Array<RegExp | string> | boolean
Default:[/^utm_\w+/i]

Remove query parameters that matches any of the provided strings or regexes.

normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref',{removeQueryParameters:['ref']});//=> 'http://sindresorhus.com/?foo=bar'

If a boolean is provided,true will remove all the query parameters.

normalizeUrl('www.sindresorhus.com?foo=bar',{removeQueryParameters:true});//=> 'http://sindresorhus.com'

false will not remove any query parameter.

normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref',{removeQueryParameters:false});//=> 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test'

keepQueryParameters

Type:Array<RegExp | string>
Default:undefined

Keeps only query parameters that matches any of the provided strings or regexes.

Note: It overrides theremoveQueryParameters option.

normalizeUrl('https://sindresorhus.com?foo=bar&ref=unicorn',{keepQueryParameters:['ref']});//=> 'https://sindresorhus.com/?ref=unicorn'

removeTrailingSlash

Type:boolean
Default:true

Remove trailing slash.

Note: Trailing slash is always removed if the URL doesn't have a pathname unless theremoveSingleSlash option is set tofalse.

normalizeUrl('http://sindresorhus.com/redirect/');//=> 'http://sindresorhus.com/redirect'normalizeUrl('http://sindresorhus.com/redirect/',{removeTrailingSlash:false});//=> 'http://sindresorhus.com/redirect/'normalizeUrl('http://sindresorhus.com/',{removeTrailingSlash:false});//=> 'http://sindresorhus.com'

removeSingleSlash

Type:boolean
Default:true

Remove a sole/ pathname in the output. This option is independent ofremoveTrailingSlash.

normalizeUrl('https://sindresorhus.com/');//=> 'https://sindresorhus.com'normalizeUrl('https://sindresorhus.com/',{removeSingleSlash:false});//=> 'https://sindresorhus.com/'

removeDirectoryIndex

Type:boolean | Array<RegExp | string>
Default:false

Removes the default directory index file from path that matches any of the provided strings or regexes. Whentrue, the regex/^index\.[a-z]+$/ is used.

normalizeUrl('www.sindresorhus.com/foo/default.php',{removeDirectoryIndex:[/^default\.[a-z]+$/]});//=> 'http://sindresorhus.com/foo'

removeExplicitPort

Type:boolean
Default:false

Removes an explicit port number from the URL.

Port 443 is always removed from HTTPS URLs and 80 is always removed from HTTP URLs regardless of this option.

normalizeUrl('sindresorhus.com:123',{removeExplicitPort:true});//=> 'http://sindresorhus.com'

sortQueryParameters

Type:boolean
Default:true

Sorts the query parameters alphabetically by key.

normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three',{sortQueryParameters:false});//=> 'http://sindresorhus.com/?b=two&a=one&c=three'

removePath

Type:boolean
Default:false

Removes the entire URL path, leaving only the domain.

normalizeUrl('https://example.com/path/to/page',{removePath:true});//=> 'https://example.com'

transformPath

Type:Function
Default:false

Custom function to transform the URL path components. The function receives an array of non-empty path components and should return a modified array.

// Keep only the first path componentnormalizeUrl('https://example.com/api/v1/users',{transformPath:(pathComponents)=>pathComponents.slice(0,1)});//=> 'https://example.com/api'// Remove specific componentsnormalizeUrl('https://example.com/admin/users',{transformPath:(pathComponents)=>pathComponents.filter(c=>c!=='admin')});//=> 'https://example.com/users'