snapreq

library0.0.5jsnpmunverified

snapreq is a cross-platform HTTP and WebSocket client with a single API across Node.js, web browsers, Expo, and React Native. Current stable version 0.0.5. It picks the right transport (Node http/https, fetch, or XMLHttpRequest) at runtime and zero runtime dependencies. Unlike alternatives (ky, got, node-fetch), snapreq enforces API consistency by raising SnapReqUnsupportedFeatureError for platform-specific gaps (e.g., Unix sockets in browsers) instead of silently changing behavior. ESM-only with JSDoc types checked by tsc. No barrel entry point; imports from subpaths to enable tree-shaking. Supports retry, timeouts, Unix sockets, TLS configuration, request cancellation, streaming, and automatic JSON parsing.

devops testing

npm install snapreq

package ↗

INSTALL

IMPORT

SIG · SNAPREQ

snapreq

devopsjavascriptv0.0.5

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SnapReq

✓ import SnapReq from 'snapreq'

✗ import { SnapReq } from 'snapreq'

SnapReq is the default export; named import will not work. No barrel entry, only import from 'snapreq'.

SnapReqWebSocketClient

✓ import SnapReqWebSocketClient from 'snapreq/websocket'

✗ import SnapReqWebSocketClient from 'snapreq'

WebSocket client is a separate subpath import to avoid bloating bundles when not using WebSockets.

SnapReqHttpError

✓ import { SnapReqHttpError } from 'snapreq/errors'

✗ import SnapReqHttpError from 'snapreq/errors'

Both SnapReqHttpError and SnapReqUnsupportedFeatureError are named exports from 'snapreq/errors'.

defaultRetryableError

✓ import { defaultRetryableError } from 'snapreq/retry'

✗ import defaultRetryableError from 'snapreq/retry'

defaultRetryableError is a named export, not default.

SnapReqResponse

✓ import SnapReqResponse from 'snapreq/response'

✗ import { SnapReqResponse } from 'snapreq/response'

SnapReqResponse is the default export from 'snapreq/response'.

SnapReqHeaders

✓ import SnapReqHeaders from 'snapreq/headers'

✗ import { SnapReqHeaders } from 'snapreq/headers'

SnapReqHeaders is the default export from 'snapreq/headers'.

Shows creating a SnapReq client with a base URL from environment, making a GET request with a timeout, parsing JSON, and handling errors.

import SnapReq from 'snapreq'; const client = new SnapReq({ baseUrl: process.env.API_BASE ?? 'https://jsonplaceholder.typicode.com' }); async function main() { try { const res = await client.get('/posts/1', { timeoutMs: 5000 }); console.log('Status:', res.status); const data = await res.json(); console.log('Title:', data.title); } catch (err) { console.error('Request failed:', err); } } main();

Debug

Known issues

gotchaCommonJs require() is not supported; snapreq is ESM-only. Using require('snapreq') will throw an error.

fix

Use import syntax or dynamic import(). If you must use require, consider using snapreq with a bundler that can transpile ESM.

affects: >=0.0.5

gotchaImporting SnapReq as a named export (import { SnapReq } from 'snapreq') will fail; it is a default export.

fix

Use import SnapReq from 'snapreq' without curly braces.

affects: >=0.0.5

gotchaPlatform-specific features like Unix sockets (socketPath) or Node Buffer (response.buffer()) throw SnapReqUnsupportedFeatureError on non-Node transports. Not checking for this error can lead to unexpected crashes.

fix

Wrap platform-specific calls in try-catch and handle SnapReqUnsupportedFeatureError gracefully, or check transport mode before using Node-only features.

affects: >=0.0.5

gotchaRetry only applies to buffered requests (where response body is consumed via json(), text(), bytes(), etc.). It does not work with streamed bodies (response.stream()).

fix

Avoid using retry with streamed responses. If retry is needed, consume the response fully before accessing the body.

affects: >=0.0.5

gotchaUnsetting implicit timeout by setting timeoutMs: 0 on a request only disables the client-level timeout for that specific call. It does not set an infinite timeout if the client has a default; the request may still timeout if the server is slow.

fix

Explicitly set timeoutMs: 0 on the client if you want no timeout globally, or use a large value like Number.MAX_SAFE_INTEGER.

affects: >=0.0.5

gotchaThe request() method (get, post, etc.) does not throw on non-2xx status by default, unlike many HTTP clients (axios, got). This can lead to unhandled error statuses if the developer assumes throwOnError is true.

fix

Either check response.ok or set throwOnError: true on the client or per request.

affects: >=0.0.5

Errors

Common errors & fixes

Error: Cannot find module 'snapreq'

Package not installed or bundler cannot resolve ESM exports for snapreq subpath imports.

fix

Run 'npm install snapreq' and ensure your project uses a module bundler that supports ESM subpath exports (e.g., webpack 5+, Node 12+).

TypeError: SnapReq is not a constructor

Named import used instead of default import: import { SnapReq } from 'snapreq'

fix

Change to: import SnapReq from 'snapreq'

SnapReqUnsupportedFeatureError: buffer() is not available on this transport

Tried to use response.buffer() on a browser or react-native transport.

fix

Use response.bytes() instead for cross-platform binary data, or check transport before calling buffer().

Error: No transport available for this environment

snapreq could not find a suitable HTTP transport (e.g., in a very old Node.js version lacking fetch, and XHR not available).

fix

Ensure you are running Node 18+ (which has native fetch) or in a browser context with XMLHttpRequest. Polyfills may be needed for older environments.

TypeError: snapreq/websocket does not export 'SnapReqWebSocketClient'

Import path or named export incorrect.

fix

Use default import: import SnapReqWebSocketClient from 'snapreq/websocket'

Upgrade

Version history

0.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

10 hits · last 30 days

node

Resources

packagesnapreq ↗