uri-tag

A template literal tag to encode URI components. Allows you to to build a URI string, where any expressions will be safely encoded.

import uri from 'uri-tag';

const name = getName(); // Arbitrary user input
const status = getStatus(); // Arbitrary user input

const myUri = uri`https://example.com/api/users?name=${name}&status=${status}`;

Uses RFC 3986 compliant URI encoding to encode any unsafe character sequences to their escaped representations:

const query = 'query with special chars ! ? foo=bar %';
const endpoint = uri`/api/search?q=${query}`;

// endpoint === '/api/search?q=query%20with%20special%20chars%20%21%20%3F%20foo%3Dbar%20%25'

To bypass encoding for a specific component, you can use uri.raw:

const apiBase = 'https://example.com/api/v1';
const query = 'foo/bar';
const endpoint = uri`${uri.raw(apiBase)}/users?name=${query}`;

// endpoint === 'https://example.com/api/v1/users?name=foo%2Fbar'

uri.raw uses a unique symbol under the hood, so that only code with access to the uri-tag module can pass in a raw template variable. Any user input from an external source (so, strings, JSON objects, etc.) will not be able to access this symbol.

Types

This package includes definitions for TypeScript.

Similar packages

• encody
• encodeuricomponent-tag
• url-escape-tag (Relies on NodeJS querystring module, requires a polyfill for browser usage.)
• url-tagged-template (Different goals, parses URLs to their components rather than returning a URL string.)

Changelog

• v2.0

  • Upgrade uri-tag to use modern Node.js 14+ features.
  • Convert package to ES modules by default using module: "type".
  • Use exports in package.json rather than main. This is technically a breaking change due to the change in which subpaths can be imported.
  • Drop support for Node 12.
  • Upgrade to package-lock v2 format.

• v1.4

  • Drop support for Node v10.

• v1.3

  • Update URI encoding to be RFC 3986 compliant

• v1.2

  • Remove support for Node v8, add tests for Node v14.

• v1.1

  • Remove core-js polyfills to improve file size.
  • Add tsd to test TypeScript declaration.

• v1.0

  • First stable release.
  • Adds support for TypeScript.

• v0

  • Initial version.