1 | # normalize-url [![Build Status](https://travis-ci.org/sindresorhus/normalize-url.svg?branch=master)](https://travis-ci.org/sindresorhus/normalize-url)
|
2 |
|
3 | > [Normalize](https://en.wikipedia.org/wiki/URL_normalization) a URL
|
4 |
|
5 | Useful when you need to display, store, deduplicate, sort, compare, etc, URLs.
|
6 |
|
7 |
|
8 | ## Install
|
9 |
|
10 | ```
|
11 | $ npm install normalize-url
|
12 | ```
|
13 |
|
14 |
|
15 | ## Usage
|
16 |
|
17 | ```js
|
18 | const normalizeUrl = require('normalize-url');
|
19 |
|
20 | normalizeUrl('sindresorhus.com');
|
21 | //=> 'http://sindresorhus.com'
|
22 |
|
23 | normalizeUrl('HTTP://xn--xample-hva.com:80/?b=bar&a=foo');
|
24 | //=> 'http://êxample.com/?a=foo&b=bar'
|
25 | ```
|
26 |
|
27 |
|
28 | ## API
|
29 |
|
30 | ### normalizeUrl(url, [options])
|
31 |
|
32 | #### url
|
33 |
|
34 | Type: `string`
|
35 |
|
36 | URL to normalize.
|
37 |
|
38 | #### options
|
39 |
|
40 | Type: `Object`
|
41 |
|
42 | ##### normalizeProtocol
|
43 |
|
44 | Type: `boolean`<br>
|
45 | Default: `true`
|
46 |
|
47 | Prepend `http:` to the URL if it's protocol-relative.
|
48 |
|
49 | ```js
|
50 | normalizeUrl('//sindresorhus.com:80/');
|
51 | //=> 'http://sindresorhus.com'
|
52 |
|
53 | normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false});
|
54 | //=> '//sindresorhus.com'
|
55 | ```
|
56 |
|
57 | ##### normalizeHttps
|
58 |
|
59 | Type: `boolean`<br>
|
60 | Default: `false`
|
61 |
|
62 | Normalize `https:` URLs to `http:`.
|
63 |
|
64 | ```js
|
65 | normalizeUrl('https://sindresorhus.com:80/');
|
66 | //=> 'https://sindresorhus.com'
|
67 |
|
68 | normalizeUrl('https://sindresorhus.com:80/', {normalizeHttps: true});
|
69 | //=> 'http://sindresorhus.com'
|
70 | ```
|
71 |
|
72 | ##### stripFragment
|
73 |
|
74 | Type: `boolean`<br>
|
75 | Default: `true`
|
76 |
|
77 | Remove the fragment at the end of the URL.
|
78 |
|
79 | ```js
|
80 | normalizeUrl('sindresorhus.com/about.html#contact');
|
81 | //=> 'http://sindresorhus.com/about.html'
|
82 |
|
83 | normalizeUrl('sindresorhus.com/about.html#contact', {stripFragment: false});
|
84 | //=> 'http://sindresorhus.com/about.html#contact'
|
85 | ```
|
86 |
|
87 | ##### stripWWW
|
88 |
|
89 | Type: `boolean`<br>
|
90 | Default: `true`
|
91 |
|
92 | Remove `www.` from the URL.
|
93 |
|
94 | ```js
|
95 | normalizeUrl('http://www.sindresorhus.com/about.html#contact');
|
96 | //=> 'http://sindresorhus.com/about.html#contact'
|
97 |
|
98 | normalizeUrl('http://www.sindresorhus.com/about.html#contact', {stripWWW: false});
|
99 | //=> 'http://www.sindresorhus.com/about.html#contact'
|
100 | ```
|
101 |
|
102 | ##### removeQueryParameters
|
103 |
|
104 | Type: `Array<RegExp|string>`<br>
|
105 | Default: `[/^utm_\w+/i]`
|
106 |
|
107 | Remove query parameters that matches any of the provided strings or regexes.
|
108 |
|
109 | ```js
|
110 | normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
|
111 | removeQueryParameters: ['ref']
|
112 | });
|
113 | //=> 'http://sindresorhus.com/?foo=bar'
|
114 | ```
|
115 |
|
116 | ##### removeTrailingSlash
|
117 |
|
118 | Type: `boolean`<br>
|
119 | Default: `true`
|
120 |
|
121 | Remove trailing slash.
|
122 |
|
123 | **Note:** Trailing slash is always removed if the URL doesn't have a pathname.
|
124 |
|
125 | ```js
|
126 | normalizeUrl('http://sindresorhus.com/redirect/');
|
127 | //=> 'http://sindresorhus.com/redirect'
|
128 |
|
129 | normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
|
130 | //=> 'http://sindresorhus.com/redirect/'
|
131 |
|
132 | normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
|
133 | //=> 'http://sindresorhus.com'
|
134 | ```
|
135 |
|
136 | ##### removeDirectoryIndex
|
137 |
|
138 | Type: `boolean` `Array<RegExp|string>`<br>
|
139 | Default: `false`
|
140 |
|
141 | Remove the default directory index file from path that matches any of the provided strings or regexes. When `true`, the regex `/^index\.[a-z]+$/` is used.
|
142 |
|
143 | ```js
|
144 | normalizeUrl('www.sindresorhus.com/foo/default.php', {
|
145 | removeDirectoryIndex: [/^default\.[a-z]+$/]
|
146 | });
|
147 | //=> 'http://sindresorhus.com/foo'
|
148 | ```
|
149 |
|
150 | ##### sortQueryParameters
|
151 |
|
152 | Type: `boolean`<br>
|
153 | Default: `true`
|
154 |
|
155 | Sort the query parameters alphabetically by key.
|
156 |
|
157 | ```js
|
158 | normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
|
159 | sortQueryParameters: false
|
160 | });
|
161 | //=> 'http://sindresorhus.com/?b=two&a=one&c=three'
|
162 | ```
|
163 |
|
164 |
|
165 | ## Related
|
166 |
|
167 | - [compare-urls](https://github.com/sindresorhus/compare-urls) - Compare URLs by first normalizing them
|
168 |
|
169 |
|
170 | ## License
|
171 |
|
172 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|