{"id":11612,"library":"qss","title":"qss: Tiny Query String Serializer","description":"qss (query string stringify) is a minimalist, 305-byte browser utility designed for efficiently serializing JavaScript objects into URL query strings and parsing query strings back into objects. The current stable version is 3.0.0. It distinguishes itself by its extreme lightness and strong performance for decoding compared to other libraries like `qs`, `query-string`, and even Node.js's native `querystring.decode` in browser contexts. While suitable for browsers, its `encode` function is significantly slower than Node.js's native `querystring.stringify`, making it less ideal for server-side encoding. qss ships with TypeScript type definitions, providing a robust development experience. Releases are feature-driven rather than on a strict cadence, with major versions introducing breaking changes as needed for improvements or modernizations.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/lukeed/qss","tags":["javascript","qs","query","string","browser","stringify","querystring","query-string","parameter","typescript"],"install":[{"cmd":"npm install qss","lang":"bash","label":"npm"},{"cmd":"yarn add qss","lang":"bash","label":"yarn"},{"cmd":"pnpm add qss","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v2.0.0, `encode` is a named export. The default export was removed.","wrong":"import qss from 'qss'","symbol":"encode","correct":"import { encode } from 'qss'"},{"note":"Primarily designed for ESM usage in browsers, though CJS is supported. Type definitions are included for TypeScript.","wrong":"const { decode } = require('qss')","symbol":"decode","correct":"import { decode } from 'qss'"},{"note":"For CommonJS environments, destructure `encode` and `decode` directly. Older Node.js versions (13.0-13.7) may have issues due to `exports` map.","symbol":"qss (CommonJS)","correct":"const { encode, decode } = require('qss')"}],"quickstart":{"code":"import { encode, decode } from 'qss';\n\n// Example 1: Basic object encoding\nconst params1 = { foo: 'hello world', bar: [1, 2, 3], baz: true };\nconst queryString1 = encode(params1);\nconsole.log('Encoded 1:', queryString1);\n// Expected: 'foo=hello%20world&bar=1&bar=2&bar=3&baz=true'\n\n// Example 2: Encoding with a custom prefix\nconst params2 = { limit: 10, offset: 0 };\nconst queryString2 = encode(params2, '?');\nconsole.log('Encoded 2 with prefix:', queryString2);\n// Expected: '?limit=10&offset=0'\n\n// Example 3: Decoding a query string\nconst decodedParams1 = decode('foo=hello%20world&bar=1&bar=2&bar=3&baz=true');\nconsole.log('Decoded 1:', decodedParams1);\n// Expected: { foo: 'hello world', bar: [1, 2, 3], baz: true }\n\n// Example 4: Decoding from location.search (browser context)\n// In a browser, you might do:\n// const browserQueryString = location.search.substring(1);\n// const decodedBrowserParams = decode(browserQueryString);\n// console.log('Decoded from browser search:', decodedBrowserParams);\n","lang":"typescript","description":"Demonstrates how to encode JavaScript objects into query strings and decode query strings back into objects, including usage with prefixes and array values."},"warnings":[{"fix":"Upgrade Node.js to a stable LTS version (e.g., Node.js 14+).","message":"Version 3.0.0 introduced 'exports' map support, which may cause module loading issues in Node.js versions 13.0 through 13.7. These were development releases and are officially End-of-Life.","severity":"breaking","affected_versions":"3.x"},{"fix":"Change your import statements from `import qss from 'qss'` to `import { encode } from 'qss'`.","message":"Version 2.0.0 removed the default export. The primary `stringify` functionality is now available as the named `encode` export.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Consider using Node.js's built-in `querystring` module for server-side encoding (e.g., `require('querystring').stringify`).","message":"qss is optimized for browser environments. While it works in Node.js, the native `querystring.stringify` is significantly faster for encoding operations in Node.js, making qss less performant for server-side encoding tasks.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always provide the full prefix string, including any desired separators, e.g., `encode({foo: 'bar'}, '?')` or `encode({baz: 'qux'}, 'existing=param&')`.","message":"The `prefix` argument for `qss.encode` is appended directly. No checks or automatic glue characters (like `?` or `&`) are added. If you want a prefix, it must include your desired joiner.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Update your import statement to use named exports: `import { encode, decode } from 'qss'`.","cause":"Attempting to use `qss` as a default export after upgrading to v2.0.0 or later.","error":"TypeError: qss is not a function or TypeError: qss_1.default is not a function"},{"fix":"Upgrade your Node.js runtime to a stable, actively maintained LTS version (e.g., Node.js 14 or newer).","cause":"Using `qss` in Node.js versions 13.0-13.7 due to the `exports` map in `package.json` introduced in v3.0.0.","error":"ERR_PACKAGE_PATH_NOT_EXPORTED"},{"fix":"Ensure the `prefix` argument includes the full desired prefix with its own separator, e.g., `encode(obj, '?')` or `encode(obj, 'foo=bar&')`.","cause":"Incorrect usage of the `prefix` argument in `qss.encode`, expecting it to automatically add `?` or `&`.","error":"Query string is missing separator or malformed after encoding."}],"ecosystem":"npm"}