{"id":48122,"library":"gun-fetch","title":"gun-fetch","description":"A fetch-like API for GunDB that provides HTTP-method-based access to Gun decentralized database operations. Version 3.7.7, actively maintained with irregular release cadence. Supports GET, PUT, HEAD methods and special query characters (_ for user/relay queries, - for hex-encoded keys). Enables register/login, pagination, peer management, and relay connections through custom headers. Differentiates from raw Gun by providing a familiar fetch interface for CRUD operations.","status":"active","version":"3.7.7","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install gun-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add gun-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add gun-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; gun-fetch wraps GunDB operations","package":"gun","optional":false}],"imports":[{"note":"gun-fetch uses CommonJS by default; no ESM exports as of v3.7.7","wrong":"import gunFetch from 'gun-fetch'","symbol":"gunFetch","correct":"const gunFetch = require('gun-fetch')"},{"note":"gunFetch(options) returns a fetch function; not a named export","wrong":"import { fetch } from 'gun-fetch'","symbol":"fetch","correct":"const fetch = gunFetch(options)"},{"note":"Options object with `file` (path for data storage) and `relay` (boolean to connect to relays). Can also pass Gun instance or relay URLs.","wrong":"","symbol":"options","correct":"const options = {file: path.resolve('./storage'), relay: true}"}],"quickstart":{"code":"const path = require('path');\nconst gunFetch = require('gun-fetch');\n\n// Configure storage and relay behavior\nconst options = {\n  file: path.resolve('./storage'),\n  relay: false // Set true to connect to default relays\n};\n\nconst fetch = gunFetch(options);\n\nasync function main() {\n  // Write data\n  await fetch('gun://hello/test/testing', {\n    method: 'PUT',\n    body: JSON.stringify({ message: 'Hello GunDB!' })\n  });\n\n  // Read data\n  const response = await fetch('gun://hello/test/testing', {\n    method: 'GET'\n  });\n  const text = await response.text();\n  console.log('Fetched data:', text);\n\n  // Check existence via HEAD\n  const headResponse = await fetch('gun://hello/test/testing', {\n    method: 'HEAD'\n  });\n  console.log('Status:', headResponse.status); // 200 if exists\n}\n\nmain().catch(console.error);","lang":"javascript","description":"Demonstrates basic CRUD operations using gun-fetch: PUT to store data, GET to retrieve, HEAD to check existence. Uses local file storage without relay."},"warnings":[{"fix":"Use the returned fetch function directly: const fetch = gunFetch(options);","message":"In v3, the `gunFetch()` function returns a fetch function instead of a client object.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Pass Gun instance via options: gunFetch({ gun: myGunInstance })","message":"Passing a Gun instance directly to gunFetch() is deprecated; use the `gun` option instead.","severity":"deprecated","affected_versions":">=3.5.0"},{"fix":"Set relay: true or provide a Gun instance with relay connection.","message":"The `relay` option defaults to false; if not set, gun-fetch will not connect to any relays, causing network operations to fail.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always stringify body: body: JSON.stringify(yourData)","message":"PUT requests require body to be a JSON string; using a plain object will not be stored correctly.","severity":"gotcha","affected_versions":"all"},{"fix":"Avoid starting data keys with underscore or hex-encode keys starting with `_` using `-` prefix.","message":"The `_` prefix in hostname triggers user/relay queries; using `_` in data keys will cause unintended behavior.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'3.7.7':24 'access':17 'activ':25 'api':8 'base':16 'cadenc':30 'charact':39 'connect':55 'crud':70 'custom':57 'databas':21 'decentr':20 'differenti':59 'enabl':48 'encod':46 'familiar':66 'fetch':3,6,67 'fetch-lik':5 'get':32 'gun':2,19,62 'gun-fetch':1 'gundb':10 'head':34 'header':58 'hex':45 'hex-encod':44 'http':14 'http-method-bas':13 'interfac':68 'irregular':28 'javascript':72 'key':47 'like':7 'maintain':26 'manag':52 'method':15,35 'oper':22,71 'pagin':50 'peer':51 'provid':12,64 'put':33 'queri':38,42 'raw':61 'register/login':49 'relay':54 'releas':29 'special':37 'support':31 'user/relay':41 'version':23","created_at":"2026-06-07T16:55:01.339080+00:00","updated_at":"2026-06-07T16:55:01.339080+00:00","problems":[{"fix":"Use require('gun-fetch') or check that the package is installed correctly.","cause":"Using ESM import instead of CommonJS require, or incorrect module path.","error":"TypeError: gunFetch is not a function"},{"fix":"Pass an options object with at least `file` and `relay` or a `gun` instance.","cause":"Calling gunFetch() without options or with invalid options object.","error":"Error: No Gun instance provided"},{"fix":"Run npm install gun to install GunDB as a dependency.","cause":"GunDB peer dependency not installed.","error":"Error: Cannot find module 'gun'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"gun-fetch","openapi_spec":null,"status_page":null,"smithery":null,"categories":["database"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}