json-fetch

library9.0.10jsnpmunverified

json-fetch is a lightweight wrapper around the ES6 fetch API that simplifies interacting with JSON APIs. It automatically serializes request bodies to JSON and sets appropriate Content-Type headers, parses responses as JSON when Content-Type is application/json, includes credentials by default, and supports configurable retry logic via the promise-retry library. Current stable version: 9.0.10. Release cadence is irregular. Key differentiators: built-in retry strategies for 5xx errors and network errors, request/response lifecycle callbacks, TypeScript type declarations (requires DOM lib), and a simple API that reduces boilerplate for JSON API calls. Supports Node.js >=12.

devops

npm install json-fetch

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-FETCH

json-fetch

devopsjavascriptv9.0.10

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.

default

✓ import jsonFetch from 'json-fetch'

✗ const jsonFetch = require('json-fetch')

Package is ESM-only since v7. CommonJS require() will not work with default export.

retriers

✓ import { retriers } from 'json-fetch'

✗ const retriers = require('json-fetch').retriers

retriers is a named export. CommonJS require('json-fetch').retriers is also valid but not tree-shakable.

FetchUnexpectedStatusError

✓ import { FetchUnexpectedStatusError } from 'json-fetch'

✗ import FetchUnexpectedStatusError from 'json-fetch'

This is a named export, not default. Available since v6.

FetchResponse

✓ import type { FetchResponse } from 'json-fetch'

TypeScript users should import the type for response shape. Not a runtime export.

Shows basic POST request with JSON body, expected status validation, retry on network errors, and request lifecycle callbacks.

import jsonFetch, { retriers } from 'json-fetch'; async function main() { try { const response = await jsonFetch('https://api.example.com/data', { method: 'POST', body: { key: 'value' }, expectedStatuses: [200], shouldRetry: retriers.isNetworkError, retry: { retries: 3 }, onRequestStart: (url, options) => console.log('Request started', url), onRequestEnd: (url, options, response) => console.log('Request ended', url, response.status), }); console.log('Response body:', response.body); } catch (err) { if (err.name === 'FetchUnexpectedStatusError') { console.error('Unexpected status:', err.response.status, err.response.body); } else { console.error('Network or other error:', err); } } } main();

Debug

Known issues

breakingDefault export changed from an object to a function in v7. Previously required `jsonFetch.default()` call.

fix

Import as default function directly: `import jsonFetch from 'json-fetch'`.

affects: >=7.0.0

breakingNode.js >=12 required. Older versions will cause import/syntax errors.

fix

Upgrade Node.js to v12 or later.

affects: >=9.0.0

gotchaTypeScript type declarations only work if DOM lib is included in tsconfig. Otherwise type errors for RequestInit etc.

fix

Add `"lib": ["DOM", "ES2020"]` to tsconfig.json.

affects: >=8.0.0

deprecatedOptions `retry` and `shouldRetry` are deprecated in favor of `retry` and `shouldRetry` passed directly (no change in name, but the shape may change in future). Current usage is still supported.

fix

Keep using as-is; no immediate action needed.

affects: >=9.0.0

gotchaThe library does not handle non-JSON responses gracefully. If Content-Type is not application/json, response.body will be undefined.

fix

Ensure your API returns Content-Type: application/json or handle manually.

affects: *

Errors

Common errors & fixes

Cannot find module 'json-fetch'

Package not installed or mismatched import path.

fix

Run `npm install json-fetch` or `yarn add json-fetch`. Ensure no path typo.

TypeError: jsonFetch is not a function

Using CommonJS require() on ESM-only module.

fix

Use `import jsonFetch from 'json-fetch'` or switch to dynamic import.

Property 'default' does not exist on type '...'

Importing the old default export as an object (jsonFetch.default).

fix

Use `import jsonFetch from 'json-fetch'` directly.

error TS2339: Property 'retriers' does not exist on type '...'

Trying to access retriers as a property of the default import instead of named import.

fix

Use `import { retriers } from 'json-fetch'`.

Upgrade

Version history

9.0.10latest on npm

Audit

Dependencies

promise-retryoptionalused for configurable retry behavior when shouldRetry option is provided

Agent activity

7 hits · last 30 days

node

Resources

githubgit://github.com/goodeggs/json-fetch ↗

packagejson-fetch ↗

homepagehttps://github.com/goodeggs/json-fetch ↗