BTCforPlebs/nostr-chat-widget
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

readme

Browse Source
This commit is contained in:
Logen
2025-10-06 13:08:35 -04:00
parent 53c222be97
commit 8dcf377be6
1 changed files with 110 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

227
readme.md
View File

@@ -1,88 +1,85 @@
# Nostr Chat Widget
A lightweight, privacy-focused chat widget powered by the Nostr protocol. Features end-to-end encryption, decentralized relay connections, and zero server dependencies.
A lightweight, client‑only Nostr chat widget that can be dropped into any website. The widget is built using **nostr-tools** and **Tailwind CSS** for styling.
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Nostr](https://img.shields.io/badge/protocol-Nostr-purple.svg)
## ✨ Features
- 🔐 **End-to-End Encrypted** - Messages encrypted using NIP-04
- 🌐 **Decentralized** - Connects to multiple Nostr relays
- 🚫 **No Backend Required** - Entirely client-side
- 📱 **Mobile Responsive** - Works seamlessly on all devices
- ⚡ **Lightweight** - Minimal dependencies
- 🔑 **Ephemeral Keys** - Auto-generated session keys (24hr expiry)
- 💾 **Session Persistence** - Messages saved locally per session
---
## 🚀 Quick Start
### 1. Add Required Files
```bash
# clone and open the demo page
git clone https://github.com/yourusername/nostr-web-chat-plugin.git
cd nostr-web-chat-plugin
open demo/index.html # use your preferred browser
```
Include the chat widget files in your HTML:
Once the demo page is open you can immediately play with the widget:
1. **Add the public key** – see *Configuring the Public Key* section below.
2. Hit the orange button in the bottom‑right corner and start chatting!
---
## 🔑 Configuring the Public Key (npub) on the Demo Page
We added an easy‑to‑use input bar at the top‑center of the demo page that lets you quickly test the widget with any Nostr npub. The JS code reads the key from **localStorage** under the key `cs_pubkey`. When you set a new npub it temporarily overwrites the hard‑coded `csPubkey` value in `src/chat.js`. This makes testing live chats a breeze without touching the source.
### How It Works
1. **Add the input bar** – The demo page already contains a small form (see `demo/index.html`).
2. **Enter an npub** – Click *Set Npub* to store the value in localStorage.
3. **Reload the page** – The widget automatically loads the new key from localStorage and uses it for all DM interactions.
4. **Clear** – Delete `cs_pubkey` from localStorage or set it back to the original value to revert.
Below is a quick snippet of the relevant part of `demo/index.html` for reference:
```html
<!-- Add Tailwind CSS for styling -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- Add import map for nostr-tools -->
<script type="importmap">
{
"imports": {
"nostr-tools": "https://esm.sh/nostr-tools@1.17.0"
}
}
<div id="npub-config" class="fixed top-4 left-1/2 transform -translate-x-1/2 z-50"
style="background: rgba(255,255,255,0.9); padding:.5rem 1rem; border-radius:.5rem;"
>
<input type="text" id="npub-input" placeholder="Enter your npub..." class="p-1 border rounded" style="width:220px;"/>
<button id="set-npub" class="p-1 bg-blue-500 text-white rounded ml-2">Set Npub</button>
</div>
<script type="module">
const setBtn = document.getElementById('set-npub');
setBtn.addEventListener('click', () => {
const npub = document.getElementById('npub-input').value.trim();
if (!npub) return;
localStorage.setItem('cs_pubkey', npub);
alert('NPUB set! Refresh the page to use it.');
});
</script>
<!-- Add the chat widget -->
<script type="module" src="path/to/chat.js"></script>
<!-- Add chat widget container -->
<div id="chat-widget-root"></div>
```
### 2. Configure Your Public Key
The source file `src/chat.js` then checks localStorage on initialization:
Edit the `CONFIG` object in `chat.js`:
```javascript
const CONFIG = {
relays: [
'wss://relay.damus.io',
'wss://relay.primal.net',
'wss://nos.lol'
],
csPubkey: 'YOUR_PUBLIC_KEY_HERE' // Your team's Nostr public key (hex format)
};
```js
// At runtime, override the hard‑coded key if present in localStorage
const stored = localStorage.getItem('cs_pubkey');
if (stored) {
CONFIG.csPubkey = stored;
}
```
### 3. Done!
You can keep the original placeholder in `src/chat.js` for production releases. For development or demo purposes, this pattern is the recommended way.
The chat widget will appear as a floating button in the bottom-right corner of your page.
---
## 📋 Configuration Options
## 📖 Getting Your Public Key
| Option | Type | Description |
|--------|------|-------------|
| `relays` | Array | List of Nostr relay URLs to connect to |
| `csPubkey` | String | Your customer support team's public key (hex format) |
1. Create a Nostr identity using any Nostr client.
2. Export your public key in hex format (not npub).
3. Add it to the `csPubkey` field in `src/chat.js`.
### Getting Your Public Key
**Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools).
1. Create a Nostr identity using any Nostr client
2. Export your public key in hex format (not npub)
3. Add it to the `csPubkey` field
**Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools)
---
## 🎨 Customization
### Styling
The widget uses Tailwind CSS utility classes. To customize colors, search for these classes in `chat.js`:
- Primary color: `from-[#fdad01] to-[#ff8c00]` (orange gradient)
- Change to your brand colors
- Change it to your brand colors.
### Mobile Behavior
@@ -94,76 +91,72 @@ On mobile devices, the chat expands to fullscreen automatically. Customize this
}
```
---
## 🔒 How It Works
1. **Session Creation**: When a user opens the chat, an ephemeral keypair is generated and stored locally
2. **Message Encryption**: All messages are encrypted using NIP-04 (end-to-end encryption)
3. **Relay Publishing**: Encrypted messages are published to multiple Nostr relays
4. **Real-time Updates**: The widget subscribes to replies from your team's public key
5. **Local Storage**: Messages persist locally for 24 hours per session
1. **Session Creation**: Generates an in‑memory keypair stored locally for the session.
2. **Message Encryption**: All messages are encrypted using NIP‑04 (end‑to‑end encryption).
3. **Relay Publishing**: Encrypted messages are published to multiple Nostr relays.
4. **Real‑time Updates**: Subscribes to replies from your team's public key.
5. **Local Storage**: Messages persist locally for 24 hours per session.
---
## 📦 Dependencies
- **[nostr-tools](https://github.com/nbd-wtf/nostr-tools)** – Nostr protocol implementation
- **[Tailwind CSS](https://tailwindcss.com/)** – Styling framework
- [nostr-tools](https://github.com/nbd-wtf/nostr-tools) - Nostr protocol implementation
- [Tailwind CSS](https://tailwindcss.com/) - Styling framework
---
## 🛠️ Development
### Local Testing
1. Clone the repository
2. Open `demo/index.html` in a browser
3. Configure your public key in `chat.js`
```bash
# Clone and test the demo
git clone https://github.com/yourusername/nostr-web-chat-plugin.git
cd nostr-web-chat-plugin
open demo/index.html # or serve with a static server
```
### Browser Compatibility
- Chrome/Edge: ✅
- Firefox: ✅
- Safari: ✅
- Mobile browsers: ✅
**Note:** Requires ES6 module support
## 📱 Receiving Messages
To receive and respond to chat messages, you'll need a Nostr client:
### Recommended Clients
- **Desktop**: [Nostr.band](https://nostr.band), [Nostrudel](https://nostrudel.ninja)
- **Mobile**: [Damus (iOS)](https://damus.io), [Amethyst (Android)](https://github.com/vitorpamplona/amethyst)
- **Web**: [Snort.social](https://snort.social), [Iris.to](https://iris.to)
### Setup Instructions
1. Import your private key into a Nostr client
2. Watch for DM notifications from new chat sessions
3. Reply directly from the client - messages appear instantly in the widget
## 🔐 Security Considerations
- **Ephemeral Keys**: Each session generates a new keypair (24hr expiry)
- **No User Data**: No tracking, cookies, or personal data collection
- **E2E Encryption**: All messages encrypted before transmission
- **Relay Privacy**: Messages distributed across multiple relays
## 📄 License
MIT License - See LICENSE file for details
## 🤝 Contributing
Contributions welcome! Please feel free to submit a Pull Request.
## 💬 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-chat-widget/issues)
- **Nostr**: Contact via Nostr DM
## 🙏 Credits
Built with [Nostr](https://nostr.com) protocol and [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
1. Open `demo/index.html` in a browser.
2. Use the npub input bar to test with any key.
---
**Made with ⚡ by Loge Media**
## 📱 Receiving Messages
To receive and respond to chat messages, use any Nostr client:
- **Desktop**: [Nostr.band](https://nostr.band), [Snort](https://snort.social)
- **Mobile**: [Damus](https://damus.io), [Amethyst](https://github.com/vitorpamplona/amethyst)
---
## 🔐 Security Considerations
- **Ephemeral Keys**: New keypair per session (24‑hr expiration).
- **No User Data**: No cookies or tracking.
- **E2E Encryption**: Messages are encrypted before being sent.
- **Relay Privacy**: Distributed across multiple relays.
---
## 📄 License
MIT License – see [LICENSE](LICENSE).
---
## 🤝 Contributing
Pull requests welcome! Please open an issue first if you plan a large change.
---
## 💬 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-web-chat-plugin/issues)
- **Nostr DM**: Use any DM to contact the maintainer.
---
**Made with ⚡ by Loge Media**