Publishing Events

Publishing events means sending them to one or multiple relays as described in NIP-01. NDK provides easy ways to publish events and manage the status of that event.

NOTE

Please note that the behavior of .publish() requires a valid signer and will only publish the events to the configured relays. More about relay interaction in the connecting documentation.

Publishing Events

The easiest way to publish an event is to use the publish() method on the event object.

import NDK, { NDKEvent, NDKNip07Signer } from "@nostr-dev-kit/ndk";

const nip07signer = new NDKNip07Signer();
const ndk = new NDK({ signer: nip07signer });

const event = new NDKEvent(ndk);
event.kind = 1;
event.content = "Hello world";
await event.publish(); 

This will sign the event and send it to the network.

Publishing Replaceable Events

Some events in Nostr allow for replacement.

Kinds 0, 3, range 10000-19999. Range 30000-39999 is dedicated for parameterized replaceable events, which means that multiple events of the same kind under the same pubkey can exist and are differentiated via their d tag.

Since replaceable events depend on having a newer created_at, NDK provides a convenience method to reset id, sig, and created_at to allow for easy replacement: event.publishReplaceable()

import NDK from "@nostr-dev-kit/ndk";

const ndk = new NDK();
const existingEvent = await ndk.fetchEvent("574033c986bea1d7493738b46fec1bb98dd6a826391d6aa893137e89790027ec"); // fetch the event to replace

if (existingEvent) {
    existingEvent.tags.push(
        ["p", "fa984bd7dbb282f07e16e7ae87b26a2a7b9b90b7246a44771f0cf5ae58018f52"], // follow a new user
    );
    existingEvent.publish(); // this will NOT work
    existingEvent.publishReplaceable(); // this WILL work
}

Specifying Relays

NDK will publish your event to the already connected relaySets. If you want to specify where to publish that specific event to you can pass a NDKRelaySet to the publish method:

import NDK, { NDKEvent, NDKRelaySet } from "@nostr-dev-kit/ndk";

const ndk = new NDK();

const event = new NDKEvent(ndk);
event.kind = 1;
event.content = "Hello world";

const customRelaySet = NDKRelaySet.fromRelayUrls(["wss://relay.snort.social", "wss://relay.primal.net"], ndk);
await event.publish(customRelaySet);

Tracking Publication Status

You can use the event.on published handler to keep track of where events are published and the status of each publish attempt:

import NDK, { NDKEvent, type NDKRelay, type NDKRelaySet } from "@nostr-dev-kit/ndk";

const ndk = new NDK({
    explicitRelayUrls: ["wss://relay.damus.io", "wss://relay.nostr.band", "wss://nos.lol"],
});

await ndk.connect();

const event = new NDKEvent(ndk, {
    kind: 1,
    content: "Hello Nostr!",
});

event.on("published", (data: { relaySet: NDKRelaySet; publishedToRelays: Set<NDKRelay> }) => {
    // Get all relays where the event was successfully published
    console.log("Published to:", data.publishedToRelays);
});

Publication Failures

When publishing to multiple relays, some may succeed while others fail. This can be handled through the event:publish-failed handler

import NDK, { NDKEvent, type NDKPublishError } from "@nostr-dev-kit/ndk";

const ndk = new NDK({
    explicitRelayUrls: ["wss://relay.damus.io", "wss://relay.nostr.band", "wss://nos.lol"],
});

await ndk.connect();

const event = new NDKEvent(ndk, {
    kind: 1,
    content: "Hello Nostr!",
});

ndk.on(`event:publish-failed`, (event: NDKEvent, error: NDKPublishError, relays: WebSocket["url"][]) => {
    console.log("Event failed to publish on", relays, error);
});

Event Status Properties

• event.publishedToRelays - Array of relay URLs where the event was successfully published
• event.failedPublishesToRelays - Map of relay URLs to their errors
• event.publishRelayStatus - Map of all relay URLs to their detailed status
• event.wasPublishedTo(url) - Check if successfully published to a specific relay
• event.publishStatus - Overall status: "pending", "success", or "error"
• event.publishError - Error if the overall publish failed

Code Snippets

More snippets and examples can be found in the snippets directory