Package Exports

nostr-components
nostr-components/components/nostr-comment
nostr-components/components/nostr-dm
nostr-components/components/nostr-follow-button
nostr-components/components/nostr-like
nostr-components/components/nostr-live-chat
nostr-components/components/nostr-post
nostr-components/components/nostr-profile
nostr-components/components/nostr-profile-badge
nostr-components/components/nostr-zap
nostr-components/themes
nostr-components/themes/dark
nostr-components/themes/light

Readme

Nostr Components

Embed Nostr anywhere on the internet, a Zap Button for every webpage.

🚀 About the Project

Nostr Components makes it easy to embed Zap button, Nostr profiles, posts, and follow buttons in any website. Inspired by fiatjaf's Nostr Web Components, this project adds a beautiful UI, a Storybook component generator (for webmasters), and allows embedding Nostr content anywhere on the Internet.

Zap button
Follow button
Like button
Profile Badge
Profile
Post
WordPress Integration

🛠️ Usage

Quick Start

Option 1: CDN (Recommended for Quick Integration)

Add the component script to your HTML's <head>. Each component can be loaded individually or use the full bundle.

<head>
  <!-- Load individual component (recommended for smaller bundles) -->
  <script type="module" src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-follow-button.es.js"></script>
  
  <!-- Or load the full bundle -->
  <script src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/nostr-components.umd.js"></script>
  <!-- Components auto-register when the script loads, no init() needed -->
  <!-- Optional: Call init() for explicit initialization (for backward compatibility) -->
  <script>
    // Components are already registered automatically
    // You can optionally call init() for explicit initialization
    if (window.NostrComponents && window.NostrComponents.default) {
      window.NostrComponents.default.init();
    } else if (window.NostrComponents && window.NostrComponents.init) {
      // Fallback: use named export
      window.NostrComponents.init();
    }
  </script>
</head>

Option 2: NPM Package

Install the package via npm:

npm install nostr-components

Then import components in your JavaScript/TypeScript:

// Import individual components
import 'nostr-components/dist/components/nostr-follow-button.es.js';
import 'nostr-components/dist/components/nostr-zap.es.js';
import 'nostr-components/dist/components/nostr-like.es.js';

// Or import the full bundle
import 'nostr-components/dist/nostr-components.es.js';

For bundlers (Vite, Webpack, etc.), you can also import the source:

// Import from source (requires bundler)
import { NostrFollowButton } from 'nostr-components';
import { NostrZap } from 'nostr-components';
import { NostrLike } from 'nostr-components';

Note: When using npm packages, make sure your bundler is configured to handle Web Components properly.

Use the Components: Place the component tags anywhere in your <body>.

Authentication

All interactive components (Follow, Like, Zap) require user authentication. Components use NostrLogin which supports:

NIP-07 Browser Extensions (Alby, nos2x, etc.)
NIP-46 Remote Signers (Bunkers)

The authentication flow is handled automatically when users interact with components.

1. Nostr Zap

A Lightning Network zap button that allows users to send sats to any Nostr user with a lightning address or LNURL.

Usage:

<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-zap.es.js"></script>
</head>
<body>
  <nostr-zap 
    npub="npub1qsvv5ttv6mrlh38q8ydmw3gzwq360mdu8re2vr7rk68sqmhmsh4svhsft3"
    theme="dark"
    text="⚡ Zap Me"
  ></nostr-zap>
</body>

Preview:

Preview of zap button

2. Nostr Follow

A simple button that allows users to follow a Nostr profile.

Usage:

<head>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-follow-button.es.js"
  ></script>
</head>
<body>
  <nostr-follow-button
    npub="npub1qsvv5ttv6mrlh38q8ydmw3gzwq360mdu8re2vr7rk68sqmhmsh4svhsft3"
  ></nostr-follow-button>
</body>

Preview:

3. Nostr Like

A like button that uses NIP-25 (External Content Reactions) to like any URL on the web. When URL is not specified, current URL is taken.

Usage:

<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-like.es.js"></script>
</head>
<body>
  <!-- Like the current page URL -->
  <nostr-like></nostr-like>

  <!-- Like a specific URL with custom text -->
  <nostr-like url="https://github.com/saiy2k/nostr-components" text="❤️"></nostr-like>
</body>

Preview:

4. Nostr Profile Badge

A small badge displaying a Nostr profile with a username and avatar.

Usage:

<head>
  <script
    type="module"
    src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-profile-badge.es.js"
  ></script>
</head>
<body>
  <nostr-profile-badge
    pubkey="npub180cvv07tjdrrgpa0j7j7tmnyl2yr6yr7l8j4s3evf6u64th6gkwsyjh6w6"
  ></nostr-profile-badge>
</body>

Preview:

5. Nostr Profile

A detailed profile card showing avatar, name, bio, notes count, followers, etc.

Usage:

<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-profile.es.js"></script>
</head>
<body>
  <nostr-profile
    pubkey="npub1a2cww4kn9wqte4ry70vyfwqyqvpswksna27rtxd8vty6c74era8sdcw83a"
  ></nostr-profile>
</body>

Preview:

6. Nostr Post

Embed any Nostr post by providing the event ID.

Usage:

<head>
  <script type="module" src="https://cdn.jsdelivr.net/npm/nostr-components@latest/dist/components/nostr-post.es.js"></script>
</head>
<body>
  <nostr-post
    eventId="note1t2jvt5vpusrwrxkfu8x8r7q65zzvm32xuur6y7am4zn475r8ucjqmwwhd2"
  ></nostr-post>
</body>

Preview:

Preview of post

7. WordPress Integration

The Nostr Components WordPress plugin provides Gutenberg blocks and shortcodes for all components, making it easy to embed Nostr functionality in your WordPress site.

For more details, see the WordPress Plugin.

📖 Documentation, Examples and Demo

Check out our full documentation here.

🛠️ Development

npm Installation Notes (Windows / newer npm versions)

If you encounter dependency resolution errors (ERESOLVE) when running npm install with newer versions of npm, use:

npm install --legacy-peer-deps


### Storybook Setup

This project uses Storybook for component development and testing. The setup includes both public showcase stories and private testing stories.

**Development Commands:**

```bash
# Start Storybook in development mode (includes testing stories)
npm run storybook

# Build Storybook for production (excludes testing stories)
STORYBOOK_ENV=production npm run build-storybook

Story Organization:

Public Stories: Showcase stories for component demos and documentation
Testing Stories: Private stories for development testing (excluded from production builds)

The production build automatically excludes all testing stories to keep the public Storybook clean and focused on showcasing components.

🤝 Contributing

We welcome contributions!
Feel free to submit issues, feature requests, or PRs on GitHub.

📝 License

This project is licensed under the MIT License.

💙 Spread Nostr Everywhere! 🚀