1 | # normalize-url [![Build Status](https://travis-ci.org/sindresorhus/normalize-url.svg?branch=master)](https://travis-ci.org/sindresorhus/normalize-url) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/normalize-url/badge.svg?branch=master)](https://coveralls.io/github/sindresorhus/normalize-url?branch=master)
|
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 | ##### defaultProtocol
|
43 |
|
44 | Type: `string`<br>
|
45 | Default: `http:`
|
46 |
|
47 | ##### normalizeProtocol
|
48 |
|
49 | Type: `boolean`<br>
|
50 | Default: `true`
|
51 |
|
52 | Prepends `defaultProtocol` to the URL if it's protocol-relative.
|
53 |
|
54 | ```js
|
55 | normalizeUrl('//sindresorhus.com:80/');
|
56 | //=> 'http://sindresorhus.com'
|
57 |
|
58 | normalizeUrl('//sindresorhus.com:80/', {normalizeProtocol: false});
|
59 | //=> '//sindresorhus.com'
|
60 | ```
|
61 |
|
62 | ##### forceHttp
|
63 |
|
64 | Type: `boolean`<br>
|
65 | Default: `false`
|
66 |
|
67 | Normalizes `https:` URLs to `http:`.
|
68 |
|
69 | ```js
|
70 | normalizeUrl('https://sindresorhus.com:80/');
|
71 | //=> 'https://sindresorhus.com'
|
72 |
|
73 | normalizeUrl('https://sindresorhus.com:80/', {forceHttp: true});
|
74 | //=> 'http://sindresorhus.com'
|
75 | ```
|
76 |
|
77 | ##### forceHttps
|
78 |
|
79 | Type: `boolean`<br>
|
80 | Default: `false`
|
81 |
|
82 | Normalizes `http:` URLs to `https:`.
|
83 |
|
84 | ```js
|
85 | normalizeUrl('https://sindresorhus.com:80/');
|
86 | //=> 'https://sindresorhus.com'
|
87 |
|
88 | normalizeUrl('http://sindresorhus.com:80/', {forceHttps: true});
|
89 | //=> 'https://sindresorhus.com'
|
90 | ```
|
91 |
|
92 | This option can't be used with the `forceHttp` option at the same time.
|
93 |
|
94 | ##### stripAuthentication
|
95 |
|
96 | Type: `boolean`<br>
|
97 | Default: `true`
|
98 |
|
99 | Strip the [authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) part of a URL.
|
100 |
|
101 | ```js
|
102 | normalizeUrl('user:password@sindresorhus.com');
|
103 | //=> 'https://sindresorhus.com'
|
104 |
|
105 | normalizeUrl('user:password@sindresorhus.com', {stripAuthentication: false});
|
106 | //=> 'https://user:password@sindresorhus.com'
|
107 | ```
|
108 |
|
109 | ##### stripHash
|
110 |
|
111 | Type: `boolean`<br>
|
112 | Default: `false`
|
113 |
|
114 | Removes hash from the URL.
|
115 |
|
116 | ```js
|
117 | normalizeUrl('sindresorhus.com/about.html#contact');
|
118 | //=> 'http://sindresorhus.com/about.html#contact'
|
119 |
|
120 | normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: true});
|
121 | //=> 'http://sindresorhus.com/about.html'
|
122 | ```
|
123 |
|
124 | ##### stripProtocol
|
125 |
|
126 | Type: `boolean`<br>
|
127 | Default: `false`
|
128 |
|
129 | Removes HTTP(S) protocol from an URL `http://sindresorhus.com` → `sindresorhus.com`.
|
130 |
|
131 | ```js
|
132 | normalizeUrl('https://sindresorhus.com');
|
133 | //=> 'https://sindresorhus.com'
|
134 |
|
135 | normalizeUrl('sindresorhus.com', {stripProtocol: true});
|
136 | //=> 'sindresorhus.com'
|
137 | ```
|
138 |
|
139 | ##### stripWWW
|
140 |
|
141 | Type: `boolean`<br>
|
142 | Default: `true`
|
143 |
|
144 | Removes `www.` from the URL.
|
145 |
|
146 | ```js
|
147 | normalizeUrl('http://www.sindresorhus.com');
|
148 | //=> 'http://sindresorhus.com'
|
149 |
|
150 | normalizeUrl('http://www.sindresorhus.com', {stripWWW: false});
|
151 | //=> 'http://www.sindresorhus.com'
|
152 | ```
|
153 |
|
154 | ##### removeQueryParameters
|
155 |
|
156 | Type: `Array<RegExp|string>`<br>
|
157 | Default: `[/^utm_\w+/i]`
|
158 |
|
159 | Removes query parameters that matches any of the provided strings or regexes.
|
160 |
|
161 | ```js
|
162 | normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
|
163 | removeQueryParameters: ['ref']
|
164 | });
|
165 | //=> 'http://sindresorhus.com/?foo=bar'
|
166 | ```
|
167 |
|
168 | ##### removeTrailingSlash
|
169 |
|
170 | Type: `boolean`<br>
|
171 | Default: `true`
|
172 |
|
173 | Removes trailing slash.
|
174 |
|
175 | **Note:** Trailing slash is always removed if the URL doesn't have a pathname.
|
176 |
|
177 | ```js
|
178 | normalizeUrl('http://sindresorhus.com/redirect/');
|
179 | //=> 'http://sindresorhus.com/redirect'
|
180 |
|
181 | normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
|
182 | //=> 'http://sindresorhus.com/redirect/'
|
183 |
|
184 | normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
|
185 | //=> 'http://sindresorhus.com'
|
186 | ```
|
187 |
|
188 | ##### removeDirectoryIndex
|
189 |
|
190 | Type: `boolean` `Array<RegExp|string>`<br>
|
191 | Default: `false`
|
192 |
|
193 | 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.
|
194 |
|
195 | ```js
|
196 | normalizeUrl('www.sindresorhus.com/foo/default.php', {
|
197 | removeDirectoryIndex: [/^default\.[a-z]+$/]
|
198 | });
|
199 | //=> 'http://sindresorhus.com/foo'
|
200 | ```
|
201 |
|
202 | ##### sortQueryParameters
|
203 |
|
204 | Type: `boolean`<br>
|
205 | Default: `true`
|
206 |
|
207 | Sorts the query parameters alphabetically by key.
|
208 |
|
209 | ```js
|
210 | normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
|
211 | sortQueryParameters: false
|
212 | });
|
213 | //=> 'http://sindresorhus.com/?b=two&a=one&c=three'
|
214 | ```
|
215 |
|
216 |
|
217 | ## Related
|
218 |
|
219 | - [compare-urls](https://github.com/sindresorhus/compare-urls) - Compare URLs by first normalizing them
|
220 |
|
221 |
|
222 | ## License
|
223 |
|
224 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|