1 | # normalize-url [![Coverage Status](https://codecov.io/gh/sindresorhus/normalize-url/branch/main/graph/badge.svg)](https://codecov.io/gh/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 | **Note:** This package does **not** do URL sanitization. [Garbage in, garbage out.](https://en.wikipedia.org/wiki/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](https://owasp.org/www-community/attacks/Path_Traversal), etc.
|
8 |
|
9 | ## Install
|
10 |
|
11 | ```
|
12 | $ npm install normalize-url
|
13 | ```
|
14 |
|
15 | *If you need to use this in the browser, use version 4: `npm i normalize-url@4`*
|
16 |
|
17 | ## Usage
|
18 |
|
19 | ```js
|
20 | import normalizeUrl from 'normalize-url';
|
21 |
|
22 | normalizeUrl('sindresorhus.com');
|
23 | //=> 'http://sindresorhus.com'
|
24 |
|
25 | normalizeUrl('//www.sindresorhus.com:80/../baz?b=bar&a=foo');
|
26 | //=> 'http://sindresorhus.com/baz?a=foo&b=bar'
|
27 | ```
|
28 |
|
29 | ## API
|
30 |
|
31 | ### normalizeUrl(url, options?)
|
32 |
|
33 | #### url
|
34 |
|
35 | Type: `string`
|
36 |
|
37 | URL to normalize, including [data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs).
|
38 |
|
39 | #### options
|
40 |
|
41 | Type: `object`
|
42 |
|
43 | ##### defaultProtocol
|
44 |
|
45 | Type: `string`\
|
46 | Default: `http:`
|
47 |
|
48 | ##### normalizeProtocol
|
49 |
|
50 | Type: `boolean`\
|
51 | Default: `true`
|
52 |
|
53 | Prepend `defaultProtocol` to the URL if it's protocol-relative.
|
54 |
|
55 | ```js
|
56 | normalizeUrl('//sindresorhus.com:80/');
|
57 | //=> 'http://sindresorhus.com'
|
58 |
|
59 | normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false});
|
60 | //=> '//sindresorhus.com'
|
61 | ```
|
62 |
|
63 | ##### forceHttp
|
64 |
|
65 | Type: `boolean`\
|
66 | Default: `false`
|
67 |
|
68 | Normalize `https:` to `http:`.
|
69 |
|
70 | ```js
|
71 | normalizeUrl('https://sindresorhus.com:80/');
|
72 | //=> 'https://sindresorhus.com'
|
73 |
|
74 | normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true});
|
75 | //=> 'http://sindresorhus.com'
|
76 | ```
|
77 |
|
78 | ##### forceHttps
|
79 |
|
80 | Type: `boolean`\
|
81 | Default: `false`
|
82 |
|
83 | Normalize `http:` to `https:`.
|
84 |
|
85 | ```js
|
86 | normalizeUrl('https://sindresorhus.com:80/');
|
87 | //=> 'https://sindresorhus.com'
|
88 |
|
89 | normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true});
|
90 | //=> 'https://sindresorhus.com'
|
91 | ```
|
92 |
|
93 | This option can't be used with the `forceHttp` option at the same time.
|
94 |
|
95 | ##### stripAuthentication
|
96 |
|
97 | Type: `boolean`\
|
98 | Default: `true`
|
99 |
|
100 | Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of the URL.
|
101 |
|
102 | ```js
|
103 | normalizeUrl('user:password@sindresorhus.com');
|
104 | //=> 'https://sindresorhus.com'
|
105 |
|
106 | normalizeUrl('user:password@sindresorhus.com', {stripAuthentication: false});
|
107 | //=> 'https://user:password@sindresorhus.com'
|
108 | ```
|
109 |
|
110 | ##### stripHash
|
111 |
|
112 | Type: `boolean`\
|
113 | Default: `false`
|
114 |
|
115 | Strip the hash part of the URL.
|
116 |
|
117 | ```js
|
118 | normalizeUrl('sindresorhus.com/about.html#contact');
|
119 | //=> 'http://sindresorhus.com/about.html#contact'
|
120 |
|
121 | normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true});
|
122 | //=> 'http://sindresorhus.com/about.html'
|
123 | ```
|
124 |
|
125 | ##### stripProtocol
|
126 |
|
127 | Type: `boolean`\
|
128 | Default: `false`
|
129 |
|
130 | Remove HTTP(S) protocol from the URL: `http://sindresorhus.com` → `sindresorhus.com`.
|
131 |
|
132 | ```js
|
133 | normalizeUrl('https://sindresorhus.com');
|
134 | //=> 'https://sindresorhus.com'
|
135 |
|
136 | normalizeUrl('https://sindresorhus.com', {stripProtocol: true});
|
137 | //=> 'sindresorhus.com'
|
138 | ```
|
139 |
|
140 | ##### stripTextFragment
|
141 |
|
142 | Type: `boolean`\
|
143 | Default: `true`
|
144 |
|
145 | Strip the [text fragment](https://web.dev/text-fragments/) part of the URL.
|
146 |
|
147 | **Note:** The text fragment will always be removed if the `stripHash` option is set to `true`, as the hash contains the text fragment.
|
148 |
|
149 | ```js
|
150 | normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello');
|
151 | //=> 'http://sindresorhus.com/about.html#'
|
152 |
|
153 | normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello');
|
154 | //=> 'http://sindresorhus.com/about.html#section'
|
155 |
|
156 | normalizeUrl('http://sindresorhus.com/about.html#:~:text=hello', {stripTextFragment: false});
|
157 | //=> 'http://sindresorhus.com/about.html#:~:text=hello'
|
158 |
|
159 | normalizeUrl('http://sindresorhus.com/about.html#section:~:text=hello', {stripTextFragment: false});
|
160 | //=> 'http://sindresorhus.com/about.html#section:~:text=hello'
|
161 | ```
|
162 |
|
163 | ##### stripWWW
|
164 |
|
165 | Type: `boolean`\
|
166 | Default: `true`
|
167 |
|
168 | Remove `www.` from the URL.
|
169 |
|
170 | ```js
|
171 | normalizeUrl('http://www.sindresorhus.com');
|
172 | //=> 'http://sindresorhus.com'
|
173 |
|
174 | normalizeUrl('http://www.sindresorhus.com', {stripWWW: false});
|
175 | //=> 'http://www.sindresorhus.com'
|
176 | ```
|
177 |
|
178 | ##### removeQueryParameters
|
179 |
|
180 | Type: `Array<RegExp | string> | boolean`\
|
181 | Default: `[/^utm_\w+/i]`
|
182 |
|
183 | Remove query parameters that matches any of the provided strings or regexes.
|
184 |
|
185 | ```js
|
186 | normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
|
187 | removeQueryParameters: ['ref']
|
188 | });
|
189 | //=> 'http://sindresorhus.com/?foo=bar'
|
190 | ```
|
191 |
|
192 | If a boolean is provided, `true` will remove all the query parameters.
|
193 |
|
194 | ```js
|
195 | normalizeUrl('www.sindresorhus.com?foo=bar', {
|
196 | removeQueryParameters: true
|
197 | });
|
198 | //=> 'http://sindresorhus.com'
|
199 | ```
|
200 |
|
201 | `false` will not remove any query parameter.
|
202 |
|
203 | ```js
|
204 | normalizeUrl('www.sindresorhus.com?foo=bar&utm_medium=test&ref=test_ref', {
|
205 | removeQueryParameters: false
|
206 | });
|
207 | //=> 'http://www.sindresorhus.com/?foo=bar&ref=test_ref&utm_medium=test'
|
208 | ```
|
209 |
|
210 | ##### removeTrailingSlash
|
211 |
|
212 | Type: `boolean`\
|
213 | Default: `true`
|
214 |
|
215 | Remove trailing slash.
|
216 |
|
217 | **Note:** Trailing slash is always removed if the URL doesn't have a pathname unless the `removeSingleSlash` option is set to `false`.
|
218 |
|
219 | ```js
|
220 | normalizeUrl('http://sindresorhus.com/redirect/');
|
221 | //=> 'http://sindresorhus.com/redirect'
|
222 |
|
223 | normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
|
224 | //=> 'http://sindresorhus.com/redirect/'
|
225 |
|
226 | normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
|
227 | //=> 'http://sindresorhus.com'
|
228 | ```
|
229 |
|
230 | ##### removeSingleSlash
|
231 |
|
232 | Type: `boolean`\
|
233 | Default: `true`
|
234 |
|
235 | Remove a sole `/` pathname in the output. This option is independant of `removeTrailingSlash`.
|
236 |
|
237 | ```js
|
238 | normalizeUrl('https://sindresorhus.com/');
|
239 | //=> 'https://sindresorhus.com'
|
240 |
|
241 | normalizeUrl('https://sindresorhus.com/', {removeSingleSlash: false});
|
242 | //=> 'https://sindresorhus.com/'
|
243 | ```
|
244 |
|
245 | ##### removeDirectoryIndex
|
246 |
|
247 | Type: `boolean | Array<RegExp | string>`\
|
248 | Default: `false`
|
249 |
|
250 | Removes 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.
|
251 |
|
252 | ```js
|
253 | normalizeUrl('www.sindresorhus.com/foo/default.php', {
|
254 | removeDirectoryIndex: [/^default\.[a-z]+$/]
|
255 | });
|
256 | //=> 'http://sindresorhus.com/foo'
|
257 | ```
|
258 |
|
259 | ##### sortQueryParameters
|
260 |
|
261 | Type: `boolean`\
|
262 | Default: `true`
|
263 |
|
264 | Sorts the query parameters alphabetically by key.
|
265 |
|
266 | ```js
|
267 | normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
|
268 | sortQueryParameters: false
|
269 | });
|
270 | //=> 'http://sindresorhus.com/?b=two&a=one&c=three'
|
271 | ```
|
272 |
|
273 | ## Related
|
274 |
|
275 | - [compare-urls](https://github.com/sindresorhus/compare-urls) - Compare URLs by first normalizing them
|
276 |
|
277 | ---
|
278 |
|
279 | <div align="center">
|
280 | <b>
|
281 | <a href="https://tidelift.com/subscription/pkg/npm-normalize-url?utm_source=npm-normalize-url&utm_medium=referral&utm_campaign=readme">Get professional support for this package with a Tidelift subscription</a>
|
282 | </b>
|
283 | <br>
|
284 | <sub>
|
285 | Tidelift helps make open source sustainable for maintainers while giving companies<br>assurances about security, maintenance, and licensing for their dependencies.
|
286 | </sub>
|
287 | </div>
|