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