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:47 -04:00
parent 8dcf377be6
commit c63cc684ac
1 changed files with 21 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
readme.md
View File

@@ -6,12 +6,7 @@ A lightweight, client‑only Nostr chat widget that can be dropped into any webs
## 🚀 Quick Start ## 🚀 Quick Start
```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
```
Once the demo page is open you can immediately play with the widget: 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. 1. **Add the public key** – see *Configuring the Public Key* section below.
@@ -21,45 +16,23 @@ Once the demo page is open you can immediately play with the widget:
## 🔑 Configuring the Public Key (npub) on the Demo Page ## 🔑 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. 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 . When you set a new npub it temporarily overwrites the hard‑coded value in . This makes testing live chats a breeze without touching the source.
### How It Works ### How It Works
1. **Add the input bar** – The demo page already contains a small form (see `demo/index.html`). 1. **Add the input bar** – The demo page already contains a small form (see ).
2. **Enter an npub** – Click *Set Npub* to store the value in localStorage. 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. 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. 4. **Clear** – Delete 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: Below is a quick snippet of the relevant part of for reference:
```html
<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>
```
The source file `src/chat.js` then checks localStorage on initialization:
```js The source file then checks localStorage on initialization:
// At runtime, override the hard‑coded key if present in localStorage
const stored = localStorage.getItem('cs_pubkey');
if (stored) {
CONFIG.csPubkey = stored;
}
```
You can keep the original placeholder in `src/chat.js` for production releases. For development or demo purposes, this pattern is the recommended way.
You can keep the original placeholder in for production releases. For development or demo purposes, this pattern is the recommended way.
--- ---
@@ -67,7 +40,7 @@ You can keep the original placeholder in `src/chat.js` for production releases.
1. Create a Nostr identity using any Nostr client. 1. Create a Nostr identity using any Nostr client.
2. Export your public key in hex format (not npub). 2. Export your public key in hex format (not npub).
3. Add it to the `csPubkey` field in `src/chat.js`. 3. Add it to the field in .
**Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools). **Tip:** You can convert npub to hex at [nostr.band/tools](https://nostr.band/tools).
@@ -77,29 +50,24 @@ You can keep the original placeholder in `src/chat.js` for production releases.
### Styling ### Styling
The widget uses Tailwind CSS utility classes. To customize colors, search for these classes in `chat.js`: The widget uses Tailwind CSS utility classes. To customize colors, search for these classes in :
- Primary color: `from-[#fdad01] to-[#ff8c00]` (orange gradient) - Primary color: (orange gradient)
- Change it to your brand colors. - Change it to your brand colors.
### Mobile Behavior ### Mobile Behavior
On mobile devices, the chat expands to fullscreen automatically. Customize this in the CSS: On mobile devices, the chat expands to fullscreen automatically. Customize this in the CSS:
```css
@media (max-width: 600px) {
/* Adjust mobile styles here */
}
```
--- ---
## 🔒 How It Works ## 🔒 How It Works
1. **Session Creation**: Generates an in‑memory keypair stored locally for the 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). 2. **Message Encryption**: All messages encrypted using NIP‑04.
3. **Relay Publishing**: Encrypted messages are published to multiple Nostr relays. 3. **Relay Publishing**: Sent to multiple Nostr relays.
4. **Real‑time Updates**: Subscribes to replies from your team's public key. 4. **Real‑time Updates**: Subscribes to replies from your public key.
5. **Local Storage**: Messages persist locally for 24 hours per session. 5. **Local Storage**: Messages persist for 24 hours.
--- ---
@@ -113,15 +81,10 @@ On mobile devices, the chat expands to fullscreen automatically. Customize this
### Local Testing ### Local Testing
```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
```
1. Open `demo/index.html` in a browser.
2. Use the npub input bar to test with any key. 1. Open in a browser.
2. Use the npub input bar for testing.
--- ---
@@ -134,10 +97,9 @@ To receive and respond to chat messages, use any Nostr client:
--- ---
## 🔐 Security Considerations ## 🔐 Security Considerations
- **Ephemeral Keys**: New keypair per session (24‑hr expiration). - **Ephemeral Keys**: New keypair per session (24‑hr expiration).
- **No User Data**: No cookies or tracking. - **No User Data**: No cookies or tracking.
- **E2E Encryption**: Messages are encrypted before being sent. - **E2E Encryption**: Messages encrypted before sending.
- **Relay Privacy**: Distributed across multiple relays. - **Relay Privacy**: Distributed across multiple relays.
--- ---
@@ -148,14 +110,13 @@ MIT License – see [LICENSE](LICENSE).
--- ---
## 🤝 Contributing ## 🤝 Contributing
Pull requests welcome! Please open an issue first if you plan a large change. Pull requests welcome! Please open an issue first if you plan a large change.
--- ---
## 💬 Support ## 💬 Support
- **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-web-chat-plugin/issues) - **Issues**: [GitHub Issues](https://github.com/yourusername/nostr-web-chat-plugin/issues)
- **Nostr DM**: Use any DM to contact the maintainer. - **Nostr DM**: Any DM to contact the maintainer.
--- ---