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.
fetchEvents
✓ import { fetchEvents } from 'nostr-fetch'
✗ import fetchEvents from 'nostr-fetch'
Named export; default export is a function that returns a promise for relay list
NostrFetcher
✓ import { NostrFetcher } from 'nostr-fetch'
✗ import { nostrFetcher } from 'nostr-fetch'
Class export; use for custom fetcher instances
FetchResult
✓ import type { FetchResult } from 'nostr-fetch'
✗ import { FetchResult } from 'nostr-fetch'
TypeScript type, use 'import type' to avoid bundling issues
Shows basic usage of fetchEvents to retrieve 10 text notes from two public relays with default options.
import { fetchEvents } from 'nostr-fetch';
const relays = ['wss://relay.damus.io', 'wss://relay.nostr.band'];
const filter = {
kinds: [1],
limit: 10,
};
async function main(): Promise<void> {
const events = await fetchEvents(relays, filter, {
skipVerification: false,
abortSignal: undefined,
});
console.log('Events:', events);
}
main().catch(console.error);
Debug
Known issues
deprecatedfetchEvents with callback signature is deprecated in v0.15.0fixUse async/await instead of callback; callback support removed in v0.17.0
affects: >=0.15.0
breakingIn v0.16.0, default export signature changed from function to object with methodsfixUpdate imports to use named exports; default export is now { getDefaultRelays, setDefaultRelays } affects: >=0.16.0 <0.17.0
breakingRelay URL validation now rejects URLs without explicit path (e.g., 'wss://relay.com') as of v0.14.0fixAlways include trailing slash in relay URLs: 'wss://relay.com/'
affects: >=0.14.0
deprecatedThe option 'timeout' has been renamed to 'requestTimeout' in v0.12.0fixReplace 'timeout' with 'requestTimeout' in fetch options object
affects: >=0.12.0
gotchafetchEvents will connect to all provided relays simultaneously; to avoid overwhelming connections, use a throttled fetcherfixCreate a NostrFetcher instance with custom maxConns or batch relays into groups
affects: >=0.0.0
gotchaThe library does not handle event verification by default; set skipVerification: false to validate signaturesfixAdd skipVerification: false in fetch options; requires nostr-tools for verification
affects: >=0.0.0
breakingIn v0.10.0, the package switched to ESM-only, dropping CommonJS supportfixUse dynamic import() for CommonJS projects, or migrate to ESM
affects: >=0.10.0
Errors
Common errors & fixes
SyntaxError: Unexpected token 'export'
Node.js version <12 or using require() in CommonJS with ESM-only package
fixUse import() or upgrade Node.js >=12; or set type: 'module' in package.json
TypeError: fetchEvents is not a function
Importing default export as a function, but it's now an object (v0.16+)
fixUse named import: import { fetchEvents } from 'nostr-fetch' Error: no relay urls provided
Passed empty array or undefined relays to fetchEvents
fixProvide at least one relay URL string in the array
Error: Invalid relay URL: wss://relay.damus.io
Missing trailing slash or invalid format (pre-v0.14 allowed, v0.14+ rejects)
fixAdd trailing slash: 'wss://relay.damus.io/'
Audit
Dependencies
nostr-toolsrequiredUses nostr-tools types (Filter, Event) and relay abstraction
cross-fetchoptionalPolyfill fetch for Node.js <18; browser users can skip if native fetch works