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/', {normalizeHttps: 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/', {normalizeHttp: true});
|
89 | //=> 'https://sindresorhus.com'
|
90 | ```
|
91 |
|
92 | This option can't be used with the `forceHttp` option at the same time.
|
93 |
|
94 | ##### stripHash
|
95 |
|
96 | Type: `boolean`<br>
|
97 | Default: `true`
|
98 |
|
99 | Removes hash from the URL.
|
100 |
|
101 | ```js
|
102 | normalizeUrl('sindresorhus.com/about.html#contact');
|
103 | //=> 'http://sindresorhus.com/about.html'
|
104 |
|
105 | normalizeUrl('sindresorhus.com/about.html#contact', {stripHash: false});
|
106 | //=> 'http://sindresorhus.com/about.html#contact'
|
107 | ```
|
108 |
|
109 | ##### stripWWW
|
110 |
|
111 | Type: `boolean`<br>
|
112 | Default: `true`
|
113 |
|
114 | Removes `www.` from the URL.
|
115 |
|
116 | ```js
|
117 | normalizeUrl('http://www.sindresorhus.com/about.html#contact');
|
118 | //=> 'http://sindresorhus.com/about.html#contact'
|
119 |
|
120 | normalizeUrl('http://www.sindresorhus.com/about.html#contact', {stripWWW: false});
|
121 | //=> 'http://www.sindresorhus.com/about.html#contact'
|
122 | ```
|
123 |
|
124 | ##### removeQueryParameters
|
125 |
|
126 | Type: `Array<RegExp|string>`<br>
|
127 | Default: `[/^utm_\w+/i]`
|
128 |
|
129 | Removes query parameters that matches any of the provided strings or regexes.
|
130 |
|
131 | ```js
|
132 | normalizeUrl('www.sindresorhus.com?foo=bar&ref=test_ref', {
|
133 | removeQueryParameters: ['ref']
|
134 | });
|
135 | //=> 'http://sindresorhus.com/?foo=bar'
|
136 | ```
|
137 |
|
138 | ##### removeTrailingSlash
|
139 |
|
140 | Type: `boolean`<br>
|
141 | Default: `true`
|
142 |
|
143 | Removes trailing slash.
|
144 |
|
145 | **Note:** Trailing slash is always removed if the URL doesn't have a pathname.
|
146 |
|
147 | ```js
|
148 | normalizeUrl('http://sindresorhus.com/redirect/');
|
149 | //=> 'http://sindresorhus.com/redirect'
|
150 |
|
151 | normalizeUrl('http://sindresorhus.com/redirect/', {removeTrailingSlash: false});
|
152 | //=> 'http://sindresorhus.com/redirect/'
|
153 |
|
154 | normalizeUrl('http://sindresorhus.com/', {removeTrailingSlash: false});
|
155 | //=> 'http://sindresorhus.com'
|
156 | ```
|
157 |
|
158 | ##### removeDirectoryIndex
|
159 |
|
160 | Type: `boolean` `Array<RegExp|string>`<br>
|
161 | Default: `false`
|
162 |
|
163 | 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.
|
164 |
|
165 | ```js
|
166 | normalizeUrl('www.sindresorhus.com/foo/default.php', {
|
167 | removeDirectoryIndex: [/^default\.[a-z]+$/]
|
168 | });
|
169 | //=> 'http://sindresorhus.com/foo'
|
170 | ```
|
171 |
|
172 | ##### sortQueryParameters
|
173 |
|
174 | Type: `boolean`<br>
|
175 | Default: `true`
|
176 |
|
177 | Sorts the query parameters alphabetically by key.
|
178 |
|
179 | ```js
|
180 | normalizeUrl('www.sindresorhus.com?b=two&a=one&c=three', {
|
181 | sortQueryParameters: false
|
182 | });
|
183 | //=> 'http://sindresorhus.com/?b=two&a=one&c=three'
|
184 | ```
|
185 |
|
186 |
|
187 | ## Related
|
188 |
|
189 | - [compare-urls](https://github.com/sindresorhus/compare-urls) - Compare URLs by first normalizing them
|
190 |
|
191 |
|
192 | ## License
|
193 |
|
194 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|