{"id":15134,"library":"jsc-safe-url","title":"JSC Safe URL Utilities","description":"jsc-safe-url is a specialized utility package designed to address a specific behavior in JavaScriptCore (JSC) where query strings and URL fragments are stripped from source URLs when they appear in error stacks. This sanitization can obscure vital debugging information, particularly in environments like React Native that rely on JSC. The package provides three core functions: `toJscSafeUrl` to encode query string data into the URL's path component using a unique `//&` delimiter, `toNormalUrl` to reverse this process and restore the original URL, and `isJscSafeUrl` to check if a URL is currently in the JSC-safe format. This functionality is crucial for implementing proposals like React Native Community RFC0646. The current stable version is 0.2.4. Due to its niche focus on a specific browser engine quirk, its release cadence is typically slow and driven by upstream changes in JSC or React Native's needs, rather than frequent feature additions. Its key differentiator is its precise, targeted solution for this particular JSC URL handling problem.","status":"active","version":"0.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/robhogan/jsc-safe-url","tags":["javascript","javascriptcore","metro","react-native","typescript"],"install":[{"cmd":"npm install jsc-safe-url","lang":"bash","label":"npm"},{"cmd":"yarn add jsc-safe-url","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsc-safe-url","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package primarily uses named exports. Supports TypeScript.","wrong":"const toJscSafeUrl = require('jsc-safe-url').toJscSafeUrl;","symbol":"toJscSafeUrl","correct":"import { toJscSafeUrl } from 'jsc-safe-url';"},{"note":"All utility functions are named exports from the root package.","wrong":"import toNormalUrl from 'jsc-safe-url/toNormalUrl';","symbol":"toNormalUrl","correct":"import { toNormalUrl } from 'jsc-safe-url';"},{"note":"While star imports work, direct named imports are preferred for clarity and tree-shaking.","wrong":"import * as jscSafeUrl from 'jsc-safe-url'; jscSafeUrl.isJscSafeUrl(...);","symbol":"isJscSafeUrl","correct":"import { isJscSafeUrl } from 'jsc-safe-url';"}],"quickstart":{"code":"import { toJscSafeUrl, toNormalUrl, isJscSafeUrl } from 'jsc-safe-url';\n\n// An example URL that would have its query string stripped by JavaScriptCore\nconst originalUrl = 'https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id';\n\nconsole.log(`Original URL: ${originalUrl}`);\n\n// Check if the URL is currently \"JSC-safe\" (it shouldn't be)\nconsole.log(`Is original URL JSC-safe? ${isJscSafeUrl(originalUrl)}`);\n// Expected output: Is original URL JSC-safe? false\n\n// Convert the URL to a JSC-safe format, embedding query params into the path\nconst jscSafeUrl = toJscSafeUrl(originalUrl);\nconsole.log(`JSC-safe URL: ${jscSafeUrl}`);\n// Expected output: JSC-safe URL: https://my-app.com/bundle.js//&platform=ios&dev=true#source-map-id\n\n// Verify the new URL is considered JSC-safe\nconsole.log(`Is JSC-safe URL truly JSC-safe? ${isJscSafeUrl(jscSafeUrl)}`);\n// Expected output: Is JSC-safe URL truly JSC-safe? true\n\n// Convert the JSC-safe URL back to its original, normal form\nconst normalUrl = toNormalUrl(jscSafeUrl);\nconsole.log(`Normal URL after conversion: ${normalUrl}`);\n// Expected output: Normal URL after conversion: https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id\n\n// Verify that the restored URL is identical to the original\nconsole.log(`URLs match after round-trip: ${originalUrl === normalUrl}`);\n// Expected output: URLs match after round-trip: true\n\n// Example with a URL that has no query string initially\nconst urlWithoutQuery = 'https://my-app.com/no-query.js';\nconsole.log(`\\nIs URL without query JSC-safe? ${isJscSafeUrl(urlWithoutQuery)}`);\n// Expected output: Is URL without query JSC-safe? true\nconsole.log(`toJscSafeUrl on no query: ${toJscSafeUrl(urlWithoutQuery)}`);\n// Expected output: toJscSafeUrl on no query: https://my-app.com/no-query.js\n","lang":"typescript","description":"Demonstrates how to convert a standard URL into a JSC-safe format, verify its safety, and then convert it back to its original form, showcasing the package's primary utilities."},"warnings":[{"fix":"Use `toJscSafeUrl(url)` to encode URLs before they are processed by JSC-based environments, typically when generating source maps or error reports. Use `toNormalUrl(jscSafeUrl)` to revert them if the original query string is needed elsewhere.","message":"JavaScriptCore (JSC) environments, such as those used in React Native, sanitize source URLs in error stacks by stripping query strings and URL fragments. This behavior means that valuable debugging context (e.g., `?platform=ios`) will be lost unless URLs are explicitly encoded.","severity":"gotcha","affected_versions":"All versions of `jsc-safe-url` address this, but the underlying issue is an upstream behavior in JSC itself."},{"fix":"Always call `toNormalUrl()` before passing a URL that was previously converted with `toJscSafeUrl()` to any external system or component that expects a standard, RFC-compliant URL format. Only use the JSC-safe format where specifically required by the JSC environment.","message":"The custom `//&` delimiter used to embed query strings into the path is specific to `jsc-safe-url`. Using URLs containing this delimiter directly in systems that expect standard URL formats (e.g., HTTP clients, web servers, other URL parsers) may lead to incorrect routing, file not found errors, or unexpected behavior.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using named imports for ESM: `import { isJscSafeUrl, toJscSafeUrl } from 'jsc-safe-url';` or for CommonJS: `const { isJscSafeUrl } = require('jsc-safe-url');`","cause":"The utility functions are named exports, but an incorrect import statement (e.g., default import or CommonJS `require` without `.functionName`) was used.","error":"TypeError: isJscSafeUrl is not a function"},{"fix":"Before using a `jsc-safe-url` in contexts outside of the specific JSC error stack reporting, always convert it back to a standard URL using `toNormalUrl(jscSafeUrl)`.","cause":"A URL encoded using `toJscSafeUrl()` was consumed by a part of the application or an external system that does not understand this custom encoding and expects a standard URL format.","error":"URL unexpectedly contains '//&' in path component"}],"ecosystem":"npm"}