{"id":48791,"library":"nostr-fetch","title":"nostr-fetch","description":"A utility library for JavaScript/TypeScript applications to fetch past events from Nostr relays with built-in concurrency control, timeout handling, and connection management. Version 0.17.0 is current, with a stable API and frequent releases. Unlike raw WebSocket handling or libraries like nostr-tools, nostr-fetch provides a high-level fetch interface that abstracts relay subscription lifecycle, retries, and pagination. It supports both Node.js and browser environments, ships TypeScript types, and is ESM-only. Key differentiators include automatic relay connection pooling, custom fetch strategies, and event validation against filters.","status":"active","version":"0.17.0","language":"javascript","source_language":"en","source_url":"https://github.com/jiftechnify/nostr-fetch","tags":["javascript","nostr","typescript"],"install":[{"cmd":"npm install nostr-fetch","lang":"bash","label":"npm"},{"cmd":"yarn add nostr-fetch","lang":"bash","label":"yarn"},{"cmd":"pnpm add nostr-fetch","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Uses nostr-tools types (Filter, Event) and relay abstraction","package":"nostr-tools","optional":false},{"reason":"Polyfill fetch for Node.js <18; browser users can skip if native fetch works","package":"cross-fetch","optional":true}],"imports":[{"note":"Named export; default export is a function that returns a promise for relay list","wrong":"import fetchEvents from 'nostr-fetch'","symbol":"fetchEvents","correct":"import { fetchEvents } from 'nostr-fetch'"},{"note":"Class export; use for custom fetcher instances","wrong":"import { nostrFetcher } from 'nostr-fetch'","symbol":"NostrFetcher","correct":"import { NostrFetcher } from 'nostr-fetch'"},{"note":"TypeScript type, use 'import type' to avoid bundling issues","wrong":"import { FetchResult } from 'nostr-fetch'","symbol":"FetchResult","correct":"import type { FetchResult } from 'nostr-fetch'"}],"quickstart":{"code":"import { fetchEvents } from 'nostr-fetch';\n\nconst relays = ['wss://relay.damus.io', 'wss://relay.nostr.band'];\nconst filter = {\n  kinds: [1],\n  limit: 10,\n};\n\nasync function main(): Promise<void> {\n  const events = await fetchEvents(relays, filter, {\n    skipVerification: false,\n    abortSignal: undefined,\n  });\n  console.log('Events:', events);\n}\nmain().catch(console.error);","lang":"typescript","description":"Shows basic usage of fetchEvents to retrieve 10 text notes from two public relays with default options."},"warnings":[{"fix":"Use async/await instead of callback; callback support removed in v0.17.0","message":"fetchEvents with callback signature is deprecated in v0.15.0","severity":"deprecated","affected_versions":">=0.15.0"},{"fix":"Update imports to use named exports; default export is now { getDefaultRelays, setDefaultRelays }","message":"In v0.16.0, default export signature changed from function to object with methods","severity":"breaking","affected_versions":">=0.16.0 <0.17.0"},{"fix":"Always include trailing slash in relay URLs: 'wss://relay.com/'","message":"Relay URL validation now rejects URLs without explicit path (e.g., 'wss://relay.com') as of v0.14.0","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Replace 'timeout' with 'requestTimeout' in fetch options object","message":"The option 'timeout' has been renamed to 'requestTimeout' in v0.12.0","severity":"deprecated","affected_versions":">=0.12.0"},{"fix":"Create a NostrFetcher instance with custom maxConns or batch relays into groups","message":"fetchEvents will connect to all provided relays simultaneously; to avoid overwhelming connections, use a throttled fetcher","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Add skipVerification: false in fetch options; requires nostr-tools for verification","message":"The library does not handle event verification by default; set skipVerification: false to validate signatures","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use dynamic import() for CommonJS projects, or migrate to ESM","message":"In v0.10.0, the package switched to ESM-only, dropping CommonJS support","severity":"breaking","affected_versions":">=0.10.0"}],"env_vars":null,"search_vec":"'0.17.0':29 'abstract':60 'api':35 'applic':9 'automat':85 'browser':72 'built':19 'built-in':18 'concurr':21 'connect':26,87 'control':22 'current':31 'custom':89 'differenti':83 'environ':73 'esm':80 'esm-on':79 'event':13,93 'fetch':3,11,51,57,90 'filter':96 'frequent':37 'handl':24,42 'high':55 'high-level':54 'includ':84 'interfac':58 'javascript':97 'javascript/typescript':8 'key':82 'level':56 'librari':6,44 'lifecycl':63 'like':45 'manag':27 'node.js':70 'nostr':2,15,47,50,98 'nostr-fetch':1,49 'nostr-tool':46 'pagin':66 'past':12 'pool':88 'provid':52 'raw':40 'relay':16,61,86 'releas':38 'retri':64 'ship':74 'stabl':34 'strategi':91 'subscript':62 'support':68 'timeout':23 'tool':48 'type':76 'typescript':75,99 'unlik':39 'util':5 'valid':94 'version':28 'websocket':41","created_at":"2026-06-07T16:58:28.575919+00:00","updated_at":"2026-06-07T16:58:28.575919+00:00","problems":[{"fix":"Use import() or upgrade Node.js >=12; or set type: 'module' in package.json","cause":"Node.js version <12 or using require() in CommonJS with ESM-only package","error":"SyntaxError: Unexpected token 'export'"},{"fix":"Use named import: import { fetchEvents } from 'nostr-fetch'","cause":"Importing default export as a function, but it's now an object (v0.16+)","error":"TypeError: fetchEvents is not a function"},{"fix":"Provide at least one relay URL string in the array","cause":"Passed empty array or undefined relays to fetchEvents","error":"Error: no relay urls provided"},{"fix":"Add trailing slash: 'wss://relay.damus.io/'","cause":"Missing trailing slash or invalid format (pre-v0.14 allowed, v0.14+ rejects)","error":"Error: Invalid relay URL: wss://relay.damus.io"}],"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":"https://github.com/jiftechnify/nostr-fetch#readme","github":"https://github.com/jiftechnify/nostr-fetch","docs":null,"changelog":null,"pypi":null,"npm":"nostr-fetch","openapi_spec":null,"status_page":null,"smithery":null,"categories":["messaging","storage"],"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}}