URL Encoding in Node.js: Components and Query Parameters

Encode the part you are actually changing

A URL contains components with different jobs: a scheme, host, path, query and optional fragment. When a user supplies one query value, encode that value rather than escaping the entire URL. For example, an ampersand inside the value A&B must not become a separator between parameters. The correct representation of that value is A%26B. Constructing a URL by simply joining untrusted strings can change which parameters the receiving application sees. Decide where the string belongs before choosing an encoding function.

Use encodeURIComponent for a component

In Node.js, encodeURIComponent('A&B / café') returns A%26B%20%2F%20caf%C3%A9. The ampersand, space and slash are escaped because this operation treats the input as one component. The accented letter is encoded as UTF-8 bytes and then percent escapes. This function is a JavaScript global; it does not require importing a Node package. A useful local check is decodeURIComponent(encodeURIComponent(value)) === value for ordinary valid Unicode strings. A literal percent sign becomes %25, so encoding an already encoded value changes it again.

Build query strings with URLSearchParams

For query parameters, create new URLSearchParams({q: 'A&B / café'}).toString(). Its output is q=A%26B+%2F+caf%C3%A9. Here spaces appear as plus signs under form-style query serialization. That is different from the %20 generated by encodeURIComponent, while both may represent a space in the appropriate context. URLSearchParams also escapes a literal plus sign: a+b becomes a%2Bb. This distinction matters for search queries and identifiers. Treating every plus sign as an ordinary character when parsing a form-style query gives the wrong value.

Preserve a URL's structure

Create const u = new URL('https://example.com/search'); then call u.searchParams.set('q', 'A&B / café'). The resulting URL retains its scheme, host and path while serializing the new query correctly. set replaces existing values for the same key; append adds another value. For repeated keys such as tag=red&tag=blue, use getAll('tag') to retrieve both. An object constructed from a sequence of duplicate keys may lose multiplicity if later code keeps only one value. Choose that behavior deliberately when designing an API.

Do not substitute encodeURI blindly

encodeURI preserves URL syntax characters that encodeURIComponent escapes. Consequently, using encodeURI on the query value A&B leaves the ampersand meaningful and can split a value into two parameters. Conversely, applying encodeURIComponent to a complete https:// URL escapes the colon and slashes, turning the address into a component string. Neither result is a universal encoder failure: the chosen function was given the wrong type of input. When changing a full URL, prefer the URL API and assign only the component you intend to modify.

Decode once at the matching boundary

decodeURIComponent('caf%C3%A9') returns café, while decodeURIComponent('%') throws a URIError because the escape is incomplete. Handle malformed input explicitly instead of silently accepting partial values. decodeURIComponent does not turn plus signs into spaces; parsing the query with URLSearchParams handles that query convention. If an HTTP framework has already decoded a parameter, avoid decoding it again. Double decoding can transform a literal encoded sequence into syntax that an earlier validation step never examined. Test the whole input path, including the framework, rather than only the helper function.

Check the browser tool against Node

The linked tool can demonstrate component encoding and decoding with a small string before you put it into server code. Try A&B, a+b, a space, a slash and café as separate cases. Record the mode and expected result for each. A round trip proves preservation of the tested characters, but it does not prove that the string is a safe host, file path or redirect destination. Encoding controls representation; validation decides whether the application's meaning is allowed. Keep those two operations visible in code review.

Related guides

Base64 decode nodejs

Base64 decode nodejs: calculation method, required inputs, worked check, limitations and a link to Base64 Encoder and Decoder.

Node js decode base64

Node js decode base64: calculation method, required inputs, worked check, limitations and a link to Base64 Encoder and Decoder.

Javascript online regex tester

Javascript online regex tester: calculation method, required inputs, worked check, limitations and a link to Regex Tester.