Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
toJscSafeUrl
✓ import { toJscSafeUrl } from 'jsc-safe-url';
✗ const toJscSafeUrl = require('jsc-safe-url').toJscSafeUrl;
Package primarily uses named exports. Supports TypeScript.
toNormalUrl
✓ import { toNormalUrl } from 'jsc-safe-url';
✗ import toNormalUrl from 'jsc-safe-url/toNormalUrl';
All utility functions are named exports from the root package.
isJscSafeUrl
✓ import { isJscSafeUrl } from 'jsc-safe-url';
✗ import * as jscSafeUrl from 'jsc-safe-url'; jscSafeUrl.isJscSafeUrl(...);
While star imports work, direct named imports are preferred for clarity and tree-shaking.
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.
import { toJscSafeUrl, toNormalUrl, isJscSafeUrl } from 'jsc-safe-url';
// An example URL that would have its query string stripped by JavaScriptCore
const originalUrl = 'https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id';
console.log(`Original URL: ${originalUrl}`);
// Check if the URL is currently "JSC-safe" (it shouldn't be)
console.log(`Is original URL JSC-safe? ${isJscSafeUrl(originalUrl)}`);
// Expected output: Is original URL JSC-safe? false
// Convert the URL to a JSC-safe format, embedding query params into the path
const jscSafeUrl = toJscSafeUrl(originalUrl);
console.log(`JSC-safe URL: ${jscSafeUrl}`);
// Expected output: JSC-safe URL: https://my-app.com/bundle.js//&platform=ios&dev=true#source-map-id
// Verify the new URL is considered JSC-safe
console.log(`Is JSC-safe URL truly JSC-safe? ${isJscSafeUrl(jscSafeUrl)}`);
// Expected output: Is JSC-safe URL truly JSC-safe? true
// Convert the JSC-safe URL back to its original, normal form
const normalUrl = toNormalUrl(jscSafeUrl);
console.log(`Normal URL after conversion: ${normalUrl}`);
// Expected output: Normal URL after conversion: https://my-app.com/bundle.js?platform=ios&dev=true#source-map-id
// Verify that the restored URL is identical to the original
console.log(`URLs match after round-trip: ${originalUrl === normalUrl}`);
// Expected output: URLs match after round-trip: true
// Example with a URL that has no query string initially
const urlWithoutQuery = 'https://my-app.com/no-query.js';
console.log(`\nIs URL without query JSC-safe? ${isJscSafeUrl(urlWithoutQuery)}`);
// Expected output: Is URL without query JSC-safe? true
console.log(`toJscSafeUrl on no query: ${toJscSafeUrl(urlWithoutQuery)}`);
// Expected output: toJscSafeUrl on no query: https://my-app.com/no-query.js
Debug
Known issues
gotchaJavaScriptCore (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.fixUse `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.
affects: All versions of `jsc-safe-url` address this, but the underlying issue is an upstream behavior in JSC itself.
gotchaThe 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.fixAlways 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.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: isJscSafeUrl is not a function
The utility functions are named exports, but an incorrect import statement (e.g., default import or CommonJS `require` without `.functionName`) was used.
fixEnsure you are using named imports for ESM: `import { isJscSafeUrl, toJscSafeUrl } from 'jsc-safe-url';` or for CommonJS: `const { isJscSafeUrl } = require('jsc-safe-url');` URL unexpectedly contains '//&' in path component
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.
fixBefore 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)`.
Audit
Dependencies
No dependency data recorded yet.