highperfocused/grimoire
1
0
Fork 0
mirror of https://github.com/purrgrammer/grimoire.git synced 2026-04-08 22:47:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

ai: add CLAUDE.md and skills

Browse Source
This commit is contained in:
Alejandro Gómez
2025-12-11 12:40:29 +01:00
parent bdfb41c68f
commit 34f5885953
16 changed files with 8705 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
.claude/config.json Normal file
View File

@@ -0,0 +1,34 @@
{
"allowedCommands": [
"npm run dev",
"npm run build",
"npm run lint",
"npm run preview",
"npm install",
"npm install *",
"npm ci",
"npx *",
"node *",
"git status",
"git diff",
"git diff *",
"git log",
"git log *",
"git branch",
"git checkout -b *",
"git add *",
"git commit *",
"git push",
"git push *",
"git pull",
"git fetch",
"ls",
"ls *",
"cat *",
"grep *",
"find *",
"pwd",
"tree *"
],
"customInstructions": "This is a Nostr protocol explorer built with React 19, TypeScript, Vite, and TailwindCSS. When working with state management, always use the pure functions in src/core/logic.ts and the Jotai atom in src/core/state.ts. The app uses a mosaic tiling window system - be careful when modifying layout logic. Use the @ path alias for src/ imports."
}

634
.claude/skills/applesauce-core/SKILL.md Normal file
View File

@@ -0,0 +1,634 @@
---
name: applesauce-core
description: This skill should be used when working with applesauce-core library for Nostr client development, including event stores, queries, observables, and client utilities. Provides comprehensive knowledge of applesauce patterns for building reactive Nostr applications.
---
# applesauce-core Skill
This skill provides comprehensive knowledge and patterns for working with applesauce-core, a library that provides reactive utilities and patterns for building Nostr clients.
## When to Use This Skill
Use this skill when:
- Building reactive Nostr applications
- Managing event stores and caches
- Working with observable patterns for Nostr
- Implementing real-time updates
- Building timeline and feed views
- Managing replaceable events
- Working with profiles and metadata
- Creating efficient Nostr queries
## Core Concepts
### applesauce-core Overview
applesauce-core provides:
- **Event stores** - Reactive event caching and management
- **Queries** - Declarative event querying patterns
- **Observables** - RxJS-based reactive patterns
- **Profile helpers** - Profile metadata management
- **Timeline utilities** - Feed and timeline building
- **NIP helpers** - NIP-specific utilities
### Installation
```bash
npm install applesauce-core
```
### Basic Architecture
applesauce-core is built on reactive principles:
- Events are stored in reactive stores
- Queries return observables that update when new events arrive
- Components subscribe to observables for real-time updates
## Event Store
### Creating an Event Store
```javascript
import { EventStore } from 'applesauce-core';
// Create event store
const eventStore = new EventStore();
// Add events
eventStore.add(event1);
eventStore.add(event2);
// Add multiple events
eventStore.addMany([event1, event2, event3]);
// Check if event exists
const exists = eventStore.has(eventId);
// Get event by ID
const event = eventStore.get(eventId);
// Remove event
eventStore.remove(eventId);
// Clear all events
eventStore.clear();
```
### Event Store Queries
```javascript
// Get all events
const allEvents = eventStore.getAll();
// Get events by filter
const filtered = eventStore.filter({
kinds: [1],
authors: [pubkey]
});
// Get events by author
const authorEvents = eventStore.getByAuthor(pubkey);
// Get events by kind
const textNotes = eventStore.getByKind(1);
```
### Replaceable Events
applesauce-core handles replaceable events automatically:
```javascript
// For kind 0 (profile), only latest is kept
eventStore.add(profileEvent1); // stored
eventStore.add(profileEvent2); // replaces if newer
// For parameterized replaceable (30000-39999)
eventStore.add(articleEvent); // keyed by author + kind + d-tag
// Get replaceable event
const profile = eventStore.getReplaceable(0, pubkey);
const article = eventStore.getReplaceable(30023, pubkey, 'article-slug');
```
## Queries
### Query Patterns
```javascript
import { createQuery } from 'applesauce-core';
// Create a query
const query = createQuery(eventStore, {
kinds: [1],
limit: 50
});
// Subscribe to query results
query.subscribe(events => {
console.log('Current events:', events);
});
// Query updates automatically when new events added
eventStore.add(newEvent); // Subscribers notified
```
### Timeline Query
```javascript
import { TimelineQuery } from 'applesauce-core';
// Create timeline for user's notes
const timeline = new TimelineQuery(eventStore, {
kinds: [1],
authors: [userPubkey]
});
// Get observable of timeline
const timeline$ = timeline.events$;
// Subscribe
timeline$.subscribe(events => {
// Events sorted by created_at, newest first
renderTimeline(events);
});
```
### Profile Query
```javascript
import { ProfileQuery } from 'applesauce-core';
// Query profile metadata
const profileQuery = new ProfileQuery(eventStore, pubkey);
// Get observable
const profile$ = profileQuery.profile$;
profile$.subscribe(profile => {
if (profile) {
console.log('Name:', profile.name);
console.log('Picture:', profile.picture);
}
});
```
## Observables
### Working with RxJS
applesauce-core uses RxJS observables:
```javascript
import { map, filter, distinctUntilChanged } from 'rxjs/operators';
// Transform query results
const names$ = profileQuery.profile$.pipe(
filter(profile => profile !== null),
map(profile => profile.name),
distinctUntilChanged()
);
// Combine multiple observables
import { combineLatest } from 'rxjs';
const combined$ = combineLatest([
timeline$,
profile$
]).pipe(
map(([events, profile]) => ({
events,
authorName: profile?.name
}))
);
```
### Creating Custom Observables
```javascript
import { Observable } from 'rxjs';
function createEventObservable(store, filter) {
return new Observable(subscriber => {
// Initial emit
subscriber.next(store.filter(filter));
// Subscribe to store changes
const unsubscribe = store.onChange(() => {
subscriber.next(store.filter(filter));
});
// Cleanup
return () => unsubscribe();
});
}
```
## Profile Helpers
### Profile Metadata
```javascript
import { parseProfile, ProfileContent } from 'applesauce-core';
// Parse kind 0 content
const profileEvent = await getProfileEvent(pubkey);
const profile = parseProfile(profileEvent);
// Profile fields
console.log(profile.name); // Display name
console.log(profile.about); // Bio
console.log(profile.picture); // Avatar URL
console.log(profile.banner); // Banner image URL
console.log(profile.nip05); // NIP-05 identifier
console.log(profile.lud16); // Lightning address
console.log(profile.website); // Website URL
```
### Profile Store
```javascript
import { ProfileStore } from 'applesauce-core';
const profileStore = new ProfileStore(eventStore);
// Get profile observable
const profile$ = profileStore.getProfile(pubkey);
// Get multiple profiles
const profiles$ = profileStore.getProfiles([pubkey1, pubkey2]);
// Request profile load (triggers fetch if not cached)
profileStore.requestProfile(pubkey);
```
## Timeline Utilities
### Building Feeds
```javascript
import { Timeline } from 'applesauce-core';
// Create timeline
const timeline = new Timeline(eventStore);
// Add filter
timeline.setFilter({
kinds: [1, 6],
authors: followedPubkeys
});
// Get events observable
const events$ = timeline.events$;
// Load more (pagination)
timeline.loadMore(50);
// Refresh (get latest)
timeline.refresh();
```
### Thread Building
```javascript
import { ThreadBuilder } from 'applesauce-core';
// Build thread from root event
const thread = new ThreadBuilder(eventStore, rootEventId);
// Get thread observable
const thread$ = thread.thread$;
thread$.subscribe(threadData => {
console.log('Root:', threadData.root);
console.log('Replies:', threadData.replies);
console.log('Reply count:', threadData.replyCount);
});
```
### Reactions and Zaps
```javascript
import { ReactionStore, ZapStore } from 'applesauce-core';
// Reactions
const reactionStore = new ReactionStore(eventStore);
const reactions$ = reactionStore.getReactions(eventId);
reactions$.subscribe(reactions => {
console.log('Likes:', reactions.likes);
console.log('Custom:', reactions.custom);
});
// Zaps
const zapStore = new ZapStore(eventStore);
const zaps$ = zapStore.getZaps(eventId);
zaps$.subscribe(zaps => {
console.log('Total sats:', zaps.totalAmount);
console.log('Zap count:', zaps.count);
});
```
## NIP Helpers
### NIP-05 Verification
```javascript
import { verifyNip05 } from 'applesauce-core';
// Verify NIP-05
const result = await verifyNip05('alice@example.com', expectedPubkey);
if (result.valid) {
console.log('NIP-05 verified');
} else {
console.log('Verification failed:', result.error);
}
```
### NIP-10 Reply Parsing
```javascript
import { parseReplyTags } from 'applesauce-core';
// Parse reply structure
const parsed = parseReplyTags(event);
console.log('Root event:', parsed.root);
console.log('Reply to:', parsed.reply);
console.log('Mentions:', parsed.mentions);
```
### NIP-65 Relay Lists
```javascript
import { parseRelayList } from 'applesauce-core';
// Parse relay list event (kind 10002)
const relays = parseRelayList(relayListEvent);
console.log('Read relays:', relays.read);
console.log('Write relays:', relays.write);
```
## Integration with nostr-tools
### Using with SimplePool
```javascript
import { SimplePool } from 'nostr-tools';
import { EventStore } from 'applesauce-core';
const pool = new SimplePool();
const eventStore = new EventStore();
// Load events into store
pool.subscribeMany(relays, [filter], {
onevent(event) {
eventStore.add(event);
}
});
// Query store reactively
const timeline$ = createTimelineQuery(eventStore, filter);
```
### Publishing Events
```javascript
import { finalizeEvent } from 'nostr-tools';
// Create event
const event = finalizeEvent({
kind: 1,
content: 'Hello!',
created_at: Math.floor(Date.now() / 1000),
tags: []
}, secretKey);
// Add to local store immediately (optimistic update)
eventStore.add(event);
// Publish to relays
await pool.publish(relays, event);
```
## Svelte Integration
### Using in Svelte Components
```svelte
<script>
import { onMount, onDestroy } from 'svelte';
import { EventStore, TimelineQuery } from 'applesauce-core';
export let pubkey;
const eventStore = new EventStore();
let events = [];
let subscription;
onMount(() => {
const timeline = new TimelineQuery(eventStore, {
kinds: [1],
authors: [pubkey]
});
subscription = timeline.events$.subscribe(e => {
events = e;
});
});
onDestroy(() => {
subscription?.unsubscribe();
});
</script>
{#each events as event}
<div class="event">
{event.content}
</div>
{/each}
```
### Svelte Store Adapter
```javascript
import { readable } from 'svelte/store';
// Convert RxJS observable to Svelte store
function fromObservable(observable, initialValue) {
return readable(initialValue, set => {
const subscription = observable.subscribe(set);
return () => subscription.unsubscribe();
});
}
// Usage
const events$ = timeline.events$;
const eventsStore = fromObservable(events$, []);
```
```svelte
<script>
import { eventsStore } from './stores.js';
</script>
{#each $eventsStore as event}
<div>{event.content}</div>
{/each}
```
## Best Practices
### Store Management
1. **Single store instance** - Use one EventStore per app
2. **Clear stale data** - Implement cache limits
3. **Handle replaceable events** - Let store manage deduplication
4. **Unsubscribe** - Clean up subscriptions on component destroy
### Query Optimization
1. **Use specific filters** - Narrow queries perform better
2. **Limit results** - Use limit for initial loads
3. **Cache queries** - Reuse query instances
4. **Debounce updates** - Throttle rapid changes
### Memory Management
1. **Limit store size** - Implement LRU or time-based eviction
2. **Clean up observables** - Unsubscribe when done
3. **Use weak references** - For profile caches
4. **Paginate large feeds** - Don't load everything at once
### Reactive Patterns
1. **Prefer observables** - Over imperative queries
2. **Use operators** - Transform data with RxJS
3. **Combine streams** - For complex views
4. **Handle loading states** - Show placeholders
## Common Patterns
### Event Deduplication
```javascript
// EventStore handles deduplication automatically
eventStore.add(event1);
eventStore.add(event1); // No duplicate
// For manual deduplication
const seen = new Set();
events.filter(e => {
if (seen.has(e.id)) return false;
seen.add(e.id);
return true;
});
```
### Optimistic Updates
```javascript
async function publishNote(content) {
// Create event
const event = await createEvent(content);
// Add to store immediately (optimistic)
eventStore.add(event);
try {
// Publish to relays
await pool.publish(relays, event);
} catch (error) {
// Remove on failure
eventStore.remove(event.id);
throw error;
}
}
```
### Loading States
```javascript
import { BehaviorSubject, combineLatest } from 'rxjs';
const loading$ = new BehaviorSubject(true);
const events$ = timeline.events$;
const state$ = combineLatest([loading$, events$]).pipe(
map(([loading, events]) => ({
loading,
events,
empty: !loading && events.length === 0
}))
);
// Start loading
loading$.next(true);
await loadEvents();
loading$.next(false);
```
### Infinite Scroll
```javascript
function createInfiniteScroll(timeline, pageSize = 50) {
let loading = false;
async function loadMore() {
if (loading) return;
loading = true;
await timeline.loadMore(pageSize);
loading = false;
}
function onScroll(event) {
const { scrollTop, scrollHeight, clientHeight } = event.target;
if (scrollHeight - scrollTop <= clientHeight * 1.5) {
loadMore();
}
}
return { loadMore, onScroll };
}
```
## Troubleshooting
### Common Issues
**Events not updating:**
- Check subscription is active
- Verify events are being added to store
- Ensure filter matches events
**Memory growing:**
- Implement store size limits
- Clean up subscriptions
- Use weak references where appropriate
**Slow queries:**
- Add indexes for common queries
- Use more specific filters
- Implement pagination
**Stale data:**
- Implement refresh mechanisms
- Set up real-time subscriptions
- Handle replaceable event updates
## References
- **applesauce GitHub**: https://github.com/hzrd149/applesauce
- **RxJS Documentation**: https://rxjs.dev
- **nostr-tools**: https://github.com/nbd-wtf/nostr-tools
- **Nostr Protocol**: https://github.com/nostr-protocol/nostr
## Related Skills
- **nostr-tools** - Lower-level Nostr operations
- **applesauce-signers** - Event signing abstractions
- **svelte** - Building reactive UIs
- **nostr** - Nostr protocol fundamentals

757
.claude/skills/applesauce-signers/SKILL.md Normal file
View File

@@ -0,0 +1,757 @@
---
name: applesauce-signers
description: This skill should be used when working with applesauce-signers library for Nostr event signing, including NIP-07 browser extensions, NIP-46 remote signing, and custom signer implementations. Provides comprehensive knowledge of signing patterns and signer abstractions.
---
# applesauce-signers Skill
This skill provides comprehensive knowledge and patterns for working with applesauce-signers, a library that provides signing abstractions for Nostr applications.
## When to Use This Skill
Use this skill when:
- Implementing event signing in Nostr applications
- Integrating with NIP-07 browser extensions
- Working with NIP-46 remote signers
- Building custom signer implementations
- Managing signing sessions
- Handling signing requests and permissions
- Implementing multi-signer support
## Core Concepts
### applesauce-signers Overview
applesauce-signers provides:
- **Signer abstraction** - Unified interface for different signers
- **NIP-07 integration** - Browser extension support
- **NIP-46 support** - Remote signing (Nostr Connect)
- **Simple signers** - Direct key signing
- **Permission handling** - Manage signing requests
- **Observable patterns** - Reactive signing states
### Installation
```bash
npm install applesauce-signers
```
### Signer Interface
All signers implement a common interface:
```typescript
interface Signer {
// Get public key
getPublicKey(): Promise<string>;
// Sign event
signEvent(event: UnsignedEvent): Promise<SignedEvent>;
// Encrypt (NIP-04)
nip04Encrypt?(pubkey: string, plaintext: string): Promise<string>;
nip04Decrypt?(pubkey: string, ciphertext: string): Promise<string>;
// Encrypt (NIP-44)
nip44Encrypt?(pubkey: string, plaintext: string): Promise<string>;
nip44Decrypt?(pubkey: string, ciphertext: string): Promise<string>;
}
```
## Simple Signer
### Using Secret Key
```javascript
import { SimpleSigner } from 'applesauce-signers';
import { generateSecretKey } from 'nostr-tools';
// Create signer with existing key
const signer = new SimpleSigner(secretKey);
// Or generate new key
const newSecretKey = generateSecretKey();
const newSigner = new SimpleSigner(newSecretKey);
// Get public key
const pubkey = await signer.getPublicKey();
// Sign event
const unsignedEvent = {
kind: 1,
content: 'Hello Nostr!',
created_at: Math.floor(Date.now() / 1000),
tags: []
};
const signedEvent = await signer.signEvent(unsignedEvent);
```
### NIP-04 Encryption
```javascript
// Encrypt message
const ciphertext = await signer.nip04Encrypt(
recipientPubkey,
'Secret message'
);
// Decrypt message
const plaintext = await signer.nip04Decrypt(
senderPubkey,
ciphertext
);
```
### NIP-44 Encryption
```javascript
// Encrypt with NIP-44 (preferred)
const ciphertext = await signer.nip44Encrypt(
recipientPubkey,
'Secret message'
);
// Decrypt
const plaintext = await signer.nip44Decrypt(
senderPubkey,
ciphertext
);
```
## NIP-07 Signer
### Browser Extension Integration
```javascript
import { Nip07Signer } from 'applesauce-signers';
// Check if extension is available
if (window.nostr) {
const signer = new Nip07Signer();
// Get public key (may prompt user)
const pubkey = await signer.getPublicKey();
// Sign event (prompts user)
const signedEvent = await signer.signEvent(unsignedEvent);
}
```
### Handling Extension Availability
```javascript
function getAvailableSigner() {
if (typeof window !== 'undefined' && window.nostr) {
return new Nip07Signer();
}
return null;
}
// Wait for extension to load
async function waitForExtension(timeout = 3000) {
const start = Date.now();
while (Date.now() - start < timeout) {
if (window.nostr) {
return new Nip07Signer();
}
await new Promise(r => setTimeout(r, 100));
}
return null;
}
```
### Extension Permissions
```javascript
// Some extensions support granular permissions
const signer = new Nip07Signer();
// Request specific permissions
try {
// This varies by extension
await window.nostr.enable();
} catch (error) {
console.log('User denied permission');
}
```
## NIP-46 Remote Signer
### Nostr Connect
```javascript
import { Nip46Signer } from 'applesauce-signers';
// Create remote signer
const signer = new Nip46Signer({
// Remote signer's pubkey
remotePubkey: signerPubkey,
// Relays for communication
relays: ['wss://relay.example.com'],
// Local secret key for encryption
localSecretKey: localSecretKey,
// Optional: custom client name
clientName: 'My Nostr App'
});
// Connect to remote signer
await signer.connect();
// Get public key
const pubkey = await signer.getPublicKey();
// Sign event
const signedEvent = await signer.signEvent(unsignedEvent);
// Disconnect when done
signer.disconnect();
```
### Connection URL
```javascript
// Parse nostrconnect:// URL
function parseNostrConnectUrl(url) {
const parsed = new URL(url);
return {
pubkey: parsed.pathname.replace('//', ''),
relay: parsed.searchParams.get('relay'),
secret: parsed.searchParams.get('secret')
};
}
// Create signer from URL
const { pubkey, relay, secret } = parseNostrConnectUrl(connectUrl);
const signer = new Nip46Signer({
remotePubkey: pubkey,
relays: [relay],
localSecretKey: generateSecretKey(),
secret: secret
});
```
### Bunker URL
```javascript
// Parse bunker:// URL (NIP-46)
function parseBunkerUrl(url) {
const parsed = new URL(url);
return {
pubkey: parsed.pathname.replace('//', ''),
relays: parsed.searchParams.getAll('relay'),
secret: parsed.searchParams.get('secret')
};
}
const { pubkey, relays, secret } = parseBunkerUrl(bunkerUrl);
```
## Signer Management
### Signer Store
```javascript
import { SignerStore } from 'applesauce-signers';
const signerStore = new SignerStore();
// Set active signer
signerStore.setSigner(signer);
// Get active signer
const activeSigner = signerStore.getSigner();
// Clear signer (logout)
signerStore.clearSigner();
// Observable for signer changes
signerStore.signer$.subscribe(signer => {
if (signer) {
console.log('Logged in');
} else {
console.log('Logged out');
}
});
```
### Multi-Account Support
```javascript
class AccountManager {
constructor() {
this.accounts = new Map();
this.activeAccount = null;
}
addAccount(pubkey, signer) {
this.accounts.set(pubkey, signer);
}
removeAccount(pubkey) {
this.accounts.delete(pubkey);
if (this.activeAccount === pubkey) {
this.activeAccount = null;
}
}
switchAccount(pubkey) {
if (this.accounts.has(pubkey)) {
this.activeAccount = pubkey;
return this.accounts.get(pubkey);
}
return null;
}
getActiveSigner() {
return this.activeAccount
? this.accounts.get(this.activeAccount)
: null;
}
}
```
## Custom Signers
### Implementing a Custom Signer
```javascript
class CustomSigner {
constructor(options) {
this.options = options;
}
async getPublicKey() {
// Return public key
return this.options.pubkey;
}
async signEvent(event) {
// Implement signing logic
// Could call external API, hardware wallet, etc.
const signedEvent = await this.externalSign(event);
return signedEvent;
}
async nip04Encrypt(pubkey, plaintext) {
// Implement NIP-04 encryption
throw new Error('NIP-04 not supported');
}
async nip04Decrypt(pubkey, ciphertext) {
throw new Error('NIP-04 not supported');
}
async nip44Encrypt(pubkey, plaintext) {
// Implement NIP-44 encryption
throw new Error('NIP-44 not supported');
}
async nip44Decrypt(pubkey, ciphertext) {
throw new Error('NIP-44 not supported');
}
}
```
### Hardware Wallet Signer
```javascript
class HardwareWalletSigner {
constructor(devicePath) {
this.devicePath = devicePath;
}
async connect() {
// Connect to hardware device
this.device = await connectToDevice(this.devicePath);
}
async getPublicKey() {
// Get public key from device
return await this.device.getNostrPubkey();
}
async signEvent(event) {
// Sign on device (user confirms on device)
const signature = await this.device.signNostrEvent(event);
return {
...event,
pubkey: await this.getPublicKey(),
id: getEventHash(event),
sig: signature
};
}
}
```
### Read-Only Signer
```javascript
class ReadOnlySigner {
constructor(pubkey) {
this.pubkey = pubkey;
}
async getPublicKey() {
return this.pubkey;
}
async signEvent(event) {
throw new Error('Read-only mode: cannot sign events');
}
async nip04Encrypt(pubkey, plaintext) {
throw new Error('Read-only mode: cannot encrypt');
}
async nip04Decrypt(pubkey, ciphertext) {
throw new Error('Read-only mode: cannot decrypt');
}
}
```
## Signing Utilities
### Event Creation Helper
```javascript
async function createAndSignEvent(signer, template) {
const pubkey = await signer.getPublicKey();
const event = {
...template,
pubkey,
created_at: template.created_at || Math.floor(Date.now() / 1000)
};
return await signer.signEvent(event);
}
// Usage
const signedNote = await createAndSignEvent(signer, {
kind: 1,
content: 'Hello!',
tags: []
});
```
### Batch Signing
```javascript
async function signEvents(signer, events) {
const signed = [];
for (const event of events) {
const signedEvent = await signer.signEvent(event);
signed.push(signedEvent);
}
return signed;
}
// With parallelization (if signer supports)
async function signEventsParallel(signer, events) {
return Promise.all(
events.map(event => signer.signEvent(event))
);
}
```
## Svelte Integration
### Signer Context
```svelte
<!-- SignerProvider.svelte -->
<script>
import { setContext } from 'svelte';
import { writable } from 'svelte/store';
const signer = writable(null);
setContext('signer', {
signer,
setSigner: (s) => signer.set(s),
clearSigner: () => signer.set(null)
});
</script>
<slot />
```
```svelte
<!-- Component using signer -->
<script>
import { getContext } from 'svelte';
const { signer } = getContext('signer');
async function publishNote(content) {
if (!$signer) {
alert('Please login first');
return;
}
const event = await $signer.signEvent({
kind: 1,
content,
created_at: Math.floor(Date.now() / 1000),
tags: []
});
// Publish event...
}
</script>
```
### Login Component
```svelte
<script>
import { getContext } from 'svelte';
import { Nip07Signer, SimpleSigner } from 'applesauce-signers';
const { setSigner, clearSigner, signer } = getContext('signer');
let nsec = '';
async function loginWithExtension() {
if (window.nostr) {
setSigner(new Nip07Signer());
} else {
alert('No extension found');
}
}
function loginWithNsec() {
try {
const decoded = nip19.decode(nsec);
if (decoded.type === 'nsec') {
setSigner(new SimpleSigner(decoded.data));
nsec = '';
}
} catch (e) {
alert('Invalid nsec');
}
}
function logout() {
clearSigner();
}
</script>
{#if $signer}
<button on:click={logout}>Logout</button>
{:else}
<button on:click={loginWithExtension}>
Login with Extension
</button>
<div>
<input
type="password"
bind:value={nsec}
placeholder="nsec..."
/>
<button on:click={loginWithNsec}>
Login with Key
</button>
</div>
{/if}
```
## Best Practices
### Security
1. **Never store secret keys in plain text** - Use secure storage
2. **Prefer NIP-07** - Let extensions manage keys
3. **Clear keys on logout** - Don't leave in memory
4. **Validate before signing** - Check event content
### User Experience
1. **Show signing status** - Loading states
2. **Handle rejections gracefully** - User may cancel
3. **Provide fallbacks** - Multiple login options
4. **Remember preferences** - Store signer type
### Error Handling
```javascript
async function safeSign(signer, event) {
try {
return await signer.signEvent(event);
} catch (error) {
if (error.message.includes('rejected')) {
console.log('User rejected signing');
return null;
}
if (error.message.includes('timeout')) {
console.log('Signing timed out');
return null;
}
throw error;
}
}
```
### Permission Checking
```javascript
function hasEncryptionSupport(signer) {
return typeof signer.nip04Encrypt === 'function' ||
typeof signer.nip44Encrypt === 'function';
}
function getEncryptionMethod(signer) {
// Prefer NIP-44
if (typeof signer.nip44Encrypt === 'function') {
return 'nip44';
}
if (typeof signer.nip04Encrypt === 'function') {
return 'nip04';
}
return null;
}
```
## Common Patterns
### Signer Detection
```javascript
async function detectSigners() {
const available = [];
// Check NIP-07
if (typeof window !== 'undefined' && window.nostr) {
available.push({
type: 'nip07',
name: 'Browser Extension',
create: () => new Nip07Signer()
});
}
// Check stored credentials
const storedKey = localStorage.getItem('nsec');
if (storedKey) {
available.push({
type: 'stored',
name: 'Saved Key',
create: () => new SimpleSigner(storedKey)
});
}
return available;
}
```
### Auto-Reconnect for NIP-46
```javascript
class ReconnectingNip46Signer {
constructor(options) {
this.options = options;
this.signer = null;
}
async connect() {
this.signer = new Nip46Signer(this.options);
await this.signer.connect();
}
async signEvent(event) {
try {
return await this.signer.signEvent(event);
} catch (error) {
if (error.message.includes('disconnected')) {
await this.connect();
return await this.signer.signEvent(event);
}
throw error;
}
}
}
```
### Signer Type Persistence
```javascript
const SIGNER_KEY = 'nostr_signer_type';
function saveSigner(type, data) {
localStorage.setItem(SIGNER_KEY, JSON.stringify({ type, data }));
}
async function restoreSigner() {
const saved = localStorage.getItem(SIGNER_KEY);
if (!saved) return null;
const { type, data } = JSON.parse(saved);
switch (type) {
case 'nip07':
if (window.nostr) {
return new Nip07Signer();
}
break;
case 'simple':
// Don't store secret keys!
break;
case 'nip46':
const signer = new Nip46Signer(data);
await signer.connect();
return signer;
}
return null;
}
```
## Troubleshooting
### Common Issues
**Extension not detected:**
- Wait for page load
- Check window.nostr exists
- Verify extension is enabled
**Signing rejected:**
- User cancelled in extension
- Handle gracefully with error message
**NIP-46 connection fails:**
- Check relay is accessible
- Verify remote signer is online
- Check secret matches
**Encryption not supported:**
- Check signer has encrypt methods
- Fall back to alternative method
- Show user appropriate error
## References
- **applesauce GitHub**: https://github.com/hzrd149/applesauce
- **NIP-07 Specification**: https://github.com/nostr-protocol/nips/blob/master/07.md
- **NIP-46 Specification**: https://github.com/nostr-protocol/nips/blob/master/46.md
- **nostr-tools**: https://github.com/nbd-wtf/nostr-tools
## Related Skills
- **nostr-tools** - Event creation and signing utilities
- **applesauce-core** - Event stores and queries
- **nostr** - Nostr protocol fundamentals
- **svelte** - Building Nostr UIs

767
.claude/skills/nostr-tools/SKILL.md Normal file
View File

@@ -0,0 +1,767 @@
---
name: nostr-tools
description: This skill should be used when working with nostr-tools library for Nostr protocol operations, including event creation, signing, filtering, relay communication, and NIP implementations. Provides comprehensive knowledge of nostr-tools APIs and patterns.
---
# nostr-tools Skill
This skill provides comprehensive knowledge and patterns for working with nostr-tools, the most popular JavaScript/TypeScript library for Nostr protocol development.
## When to Use This Skill
Use this skill when:
- Building Nostr clients or applications
- Creating and signing Nostr events
- Connecting to Nostr relays
- Implementing NIP features
- Working with Nostr keys and cryptography
- Filtering and querying events
- Building relay pools or connections
- Implementing NIP-44/NIP-04 encryption
## Core Concepts
### nostr-tools Overview
nostr-tools provides:
- **Event handling** - Create, sign, verify events
- **Key management** - Generate, convert, encode keys
- **Relay communication** - Connect, subscribe, publish
- **NIP implementations** - NIP-04, NIP-05, NIP-19, NIP-44, etc.
- **Cryptographic operations** - Schnorr signatures, encryption
- **Filter building** - Query events by various criteria
### Installation
```bash
npm install nostr-tools
```
### Basic Imports
```javascript
// Core functionality
import {
SimplePool,
generateSecretKey,
getPublicKey,
finalizeEvent,
verifyEvent
} from 'nostr-tools';
// NIP-specific imports
import { nip04, nip05, nip19, nip44 } from 'nostr-tools';
// Relay operations
import { Relay } from 'nostr-tools/relay';
```
## Key Management
### Generating Keys
```javascript
import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
// Generate new secret key (Uint8Array)
const secretKey = generateSecretKey();
// Derive public key
const publicKey = getPublicKey(secretKey);
console.log('Secret key:', bytesToHex(secretKey));
console.log('Public key:', publicKey); // hex string
```
### Key Encoding (NIP-19)
```javascript
import { nip19 } from 'nostr-tools';
// Encode to bech32
const nsec = nip19.nsecEncode(secretKey);
const npub = nip19.npubEncode(publicKey);
const note = nip19.noteEncode(eventId);
console.log(nsec); // nsec1...
console.log(npub); // npub1...
console.log(note); // note1...
// Decode from bech32
const { type, data } = nip19.decode(npub);
// type: 'npub', data: publicKey (hex)
// Encode profile reference (nprofile)
const nprofile = nip19.nprofileEncode({
pubkey: publicKey,
relays: ['wss://relay.example.com']
});
// Encode event reference (nevent)
const nevent = nip19.neventEncode({
id: eventId,
relays: ['wss://relay.example.com'],
author: publicKey,
kind: 1
});
// Encode address (naddr) for replaceable events
const naddr = nip19.naddrEncode({
identifier: 'my-article',
pubkey: publicKey,
kind: 30023,
relays: ['wss://relay.example.com']
});
```
## Event Operations
### Event Structure
```javascript
// Unsigned event template
const eventTemplate = {
kind: 1,
created_at: Math.floor(Date.now() / 1000),
tags: [],
content: 'Hello Nostr!'
};
// Signed event (after finalizeEvent)
const signedEvent = {
id: '...', // 32-byte sha256 hash as hex
pubkey: '...', // 32-byte public key as hex
created_at: 1234567890,
kind: 1,
tags: [],
content: 'Hello Nostr!',
sig: '...' // 64-byte Schnorr signature as hex
};
```
### Creating and Signing Events
```javascript
import { finalizeEvent, verifyEvent } from 'nostr-tools/pure';
// Create event template
const eventTemplate = {
kind: 1,
created_at: Math.floor(Date.now() / 1000),
tags: [
['p', publicKey], // Mention
['e', eventId, '', 'reply'], // Reply
['t', 'nostr'] // Hashtag
],
content: 'Hello Nostr!'
};
// Sign event
const signedEvent = finalizeEvent(eventTemplate, secretKey);
// Verify event
const isValid = verifyEvent(signedEvent);
console.log('Event valid:', isValid);
```
### Event Kinds
```javascript
// Common event kinds
const KINDS = {
Metadata: 0, // Profile metadata (NIP-01)
Text: 1, // Short text note (NIP-01)
RecommendRelay: 2, // Relay recommendation
Contacts: 3, // Contact list (NIP-02)
EncryptedDM: 4, // Encrypted DM (NIP-04)
EventDeletion: 5, // Delete events (NIP-09)
Repost: 6, // Repost (NIP-18)
Reaction: 7, // Reaction (NIP-25)
ChannelCreation: 40, // Channel (NIP-28)
ChannelMessage: 42, // Channel message
Zap: 9735, // Zap receipt (NIP-57)
Report: 1984, // Report (NIP-56)
RelayList: 10002, // Relay list (NIP-65)
Article: 30023, // Long-form content (NIP-23)
};
```
### Creating Specific Events
```javascript
// Profile metadata (kind 0)
const profileEvent = finalizeEvent({
kind: 0,
created_at: Math.floor(Date.now() / 1000),
tags: [],
content: JSON.stringify({
name: 'Alice',
about: 'Nostr enthusiast',
picture: 'https://example.com/avatar.jpg',
nip05: 'alice@example.com',
lud16: 'alice@getalby.com'
})
}, secretKey);
// Contact list (kind 3)
const contactsEvent = finalizeEvent({
kind: 3,
created_at: Math.floor(Date.now() / 1000),
tags: [
['p', pubkey1, 'wss://relay1.com', 'alice'],
['p', pubkey2, 'wss://relay2.com', 'bob'],
['p', pubkey3, '', 'carol']
],
content: '' // Or JSON relay preferences
}, secretKey);
// Reply to an event
const replyEvent = finalizeEvent({
kind: 1,
created_at: Math.floor(Date.now() / 1000),
tags: [
['e', rootEventId, '', 'root'],
['e', parentEventId, '', 'reply'],
['p', parentEventPubkey]
],
content: 'This is a reply'
}, secretKey);
// Reaction (kind 7)
const reactionEvent = finalizeEvent({
kind: 7,
created_at: Math.floor(Date.now() / 1000),
tags: [
['e', eventId],
['p', eventPubkey]
],
content: '+' // or '-' or emoji
}, secretKey);
// Delete event (kind 5)
const deleteEvent = finalizeEvent({
kind: 5,
created_at: Math.floor(Date.now() / 1000),
tags: [
['e', eventIdToDelete],
['e', anotherEventIdToDelete]
],
content: 'Deletion reason'
}, secretKey);
```
## Relay Communication
### Using SimplePool
SimplePool is the recommended way to interact with multiple relays:
```javascript
import { SimplePool } from 'nostr-tools/pool';
const pool = new SimplePool();
const relays = [
'wss://relay.damus.io',
'wss://nos.lol',
'wss://relay.nostr.band'
];
// Subscribe to events
const subscription = pool.subscribeMany(
relays,
[
{
kinds: [1],
authors: [publicKey],
limit: 10
}
],
{
onevent(event) {
console.log('Received event:', event);
},
oneose() {
console.log('End of stored events');
}
}
);
// Close subscription when done
subscription.close();
// Publish event to all relays
const results = await Promise.allSettled(
pool.publish(relays, signedEvent)
);
// Query events (returns Promise)
const events = await pool.querySync(relays, {
kinds: [0],
authors: [publicKey]
});
// Get single event
const event = await pool.get(relays, {
ids: [eventId]
});
// Close pool when done
pool.close(relays);
```
### Direct Relay Connection
```javascript
import { Relay } from 'nostr-tools/relay';
const relay = await Relay.connect('wss://relay.damus.io');
console.log(`Connected to ${relay.url}`);
// Subscribe
const sub = relay.subscribe([
{
kinds: [1],
limit: 100
}
], {
onevent(event) {
console.log('Event:', event);
},
oneose() {
console.log('EOSE');
sub.close();
}
});
// Publish
await relay.publish(signedEvent);
// Close
relay.close();
```
### Handling Connection States
```javascript
import { Relay } from 'nostr-tools/relay';
const relay = await Relay.connect('wss://relay.example.com');
// Listen for disconnect
relay.onclose = () => {
console.log('Relay disconnected');
};
// Check connection status
console.log('Connected:', relay.connected);
```
## Filters
### Filter Structure
```javascript
const filter = {
// Event IDs
ids: ['abc123...'],
// Authors (pubkeys)
authors: ['pubkey1', 'pubkey2'],
// Event kinds
kinds: [1, 6, 7],
// Tags (single-letter keys)
'#e': ['eventId1', 'eventId2'],
'#p': ['pubkey1'],
'#t': ['nostr', 'bitcoin'],
'#d': ['article-identifier'],
// Time range
since: 1704067200, // Unix timestamp
until: 1704153600,
// Limit results
limit: 100,
// Search (NIP-50, if relay supports)
search: 'nostr protocol'
};
```
### Common Filter Patterns
```javascript
// User's recent posts
const userPosts = {
kinds: [1],
authors: [userPubkey],
limit: 50
};
// User's profile
const userProfile = {
kinds: [0],
authors: [userPubkey]
};
// User's contacts
const userContacts = {
kinds: [3],
authors: [userPubkey]
};
// Replies to an event
const replies = {
kinds: [1],
'#e': [eventId]
};
// Reactions to an event
const reactions = {
kinds: [7],
'#e': [eventId]
};
// Feed from followed users
const feed = {
kinds: [1, 6],
authors: followedPubkeys,
limit: 100
};
// Events mentioning user
const mentions = {
kinds: [1],
'#p': [userPubkey],
limit: 50
};
// Hashtag search
const hashtagEvents = {
kinds: [1],
'#t': ['bitcoin'],
limit: 100
};
// Replaceable event by d-tag
const replaceableEvent = {
kinds: [30023],
authors: [authorPubkey],
'#d': ['article-slug']
};
```
### Multiple Filters
```javascript
// Subscribe with multiple filters (OR logic)
const filters = [
{ kinds: [1], authors: [userPubkey], limit: 20 },
{ kinds: [1], '#p': [userPubkey], limit: 20 }
];
pool.subscribeMany(relays, filters, {
onevent(event) {
// Receives events matching ANY filter
}
});
```
## Encryption
### NIP-04 (Legacy DMs)
```javascript
import { nip04 } from 'nostr-tools';
// Encrypt message
const ciphertext = await nip04.encrypt(
secretKey,
recipientPubkey,
'Hello, this is secret!'
);
// Create encrypted DM event
const dmEvent = finalizeEvent({
kind: 4,
created_at: Math.floor(Date.now() / 1000),
tags: [['p', recipientPubkey]],
content: ciphertext
}, secretKey);
// Decrypt message
const plaintext = await nip04.decrypt(
secretKey,
senderPubkey,
ciphertext
);
```
### NIP-44 (Modern Encryption)
```javascript
import { nip44 } from 'nostr-tools';
// Get conversation key (cache this for multiple messages)
const conversationKey = nip44.getConversationKey(
secretKey,
recipientPubkey
);
// Encrypt
const ciphertext = nip44.encrypt(
'Hello with NIP-44!',
conversationKey
);
// Decrypt
const plaintext = nip44.decrypt(
ciphertext,
conversationKey
);
```
## NIP Implementations
### NIP-05 (DNS Identifier)
```javascript
import { nip05 } from 'nostr-tools';
// Query NIP-05 identifier
const profile = await nip05.queryProfile('alice@example.com');
if (profile) {
console.log('Pubkey:', profile.pubkey);
console.log('Relays:', profile.relays);
}
// Verify NIP-05 for a pubkey
const isValid = await nip05.queryProfile('alice@example.com')
.then(p => p?.pubkey === expectedPubkey);
```
### NIP-10 (Reply Threading)
```javascript
import { nip10 } from 'nostr-tools';
// Parse reply tags
const parsed = nip10.parse(event);
console.log('Root:', parsed.root); // Original event
console.log('Reply:', parsed.reply); // Direct parent
console.log('Mentions:', parsed.mentions); // Other mentions
console.log('Profiles:', parsed.profiles); // Mentioned pubkeys
```
### NIP-21 (nostr: URIs)
```javascript
// Parse nostr: URIs
const uri = 'nostr:npub1...';
const { type, data } = nip19.decode(uri.replace('nostr:', ''));
```
### NIP-27 (Content References)
```javascript
// Parse nostr:npub and nostr:note references in content
const content = 'Check out nostr:npub1abc... and nostr:note1xyz...';
const references = content.match(/nostr:(n[a-z]+1[a-z0-9]+)/g);
references?.forEach(ref => {
const decoded = nip19.decode(ref.replace('nostr:', ''));
console.log(decoded.type, decoded.data);
});
```
### NIP-57 (Zaps)
```javascript
import { nip57 } from 'nostr-tools';
// Validate zap receipt
const zapReceipt = await pool.get(relays, {
kinds: [9735],
'#e': [eventId]
});
const validatedZap = await nip57.validateZapRequest(zapReceipt);
```
## Utilities
### Hex and Bytes Conversion
```javascript
import { bytesToHex, hexToBytes } from '@noble/hashes/utils';
// Convert secret key to hex
const secretKeyHex = bytesToHex(secretKey);
// Convert hex back to bytes
const secretKeyBytes = hexToBytes(secretKeyHex);
```
### Event ID Calculation
```javascript
import { getEventHash } from 'nostr-tools/pure';
// Calculate event ID without signing
const eventId = getEventHash(unsignedEvent);
```
### Signature Operations
```javascript
import {
getSignature,
verifyEvent
} from 'nostr-tools/pure';
// Sign event data
const signature = getSignature(unsignedEvent, secretKey);
// Verify complete event
const isValid = verifyEvent(signedEvent);
```
## Best Practices
### Connection Management
1. **Use SimplePool** - Manages connections efficiently
2. **Limit concurrent connections** - Don't connect to too many relays
3. **Handle disconnections** - Implement reconnection logic
4. **Close subscriptions** - Always close when done
### Event Handling
1. **Verify events** - Always verify signatures
2. **Deduplicate** - Events may come from multiple relays
3. **Handle replaceable events** - Latest by created_at wins
4. **Validate content** - Don't trust event content blindly
### Key Security
1. **Never expose secret keys** - Keep in secure storage
2. **Use NIP-07 in browsers** - Let extensions handle signing
3. **Validate input** - Check key formats before use
### Performance
1. **Cache events** - Avoid re-fetching
2. **Use filters wisely** - Be specific, use limits
3. **Batch operations** - Combine related queries
4. **Close idle connections** - Free up resources
## Common Patterns
### Building a Feed
```javascript
const pool = new SimplePool();
const relays = ['wss://relay.damus.io', 'wss://nos.lol'];
async function loadFeed(followedPubkeys) {
const events = await pool.querySync(relays, {
kinds: [1, 6],
authors: followedPubkeys,
limit: 100
});
// Sort by timestamp
return events.sort((a, b) => b.created_at - a.created_at);
}
```
### Real-time Updates
```javascript
function subscribeToFeed(followedPubkeys, onEvent) {
return pool.subscribeMany(
relays,
[{ kinds: [1, 6], authors: followedPubkeys }],
{
onevent: onEvent,
oneose() {
console.log('Caught up with stored events');
}
}
);
}
```
### Profile Loading
```javascript
async function loadProfile(pubkey) {
const [metadata] = await pool.querySync(relays, {
kinds: [0],
authors: [pubkey],
limit: 1
});
if (metadata) {
return JSON.parse(metadata.content);
}
return null;
}
```
### Event Deduplication
```javascript
const seenEvents = new Set();
function handleEvent(event) {
if (seenEvents.has(event.id)) {
return; // Skip duplicate
}
seenEvents.add(event.id);
// Process event...
}
```
## Troubleshooting
### Common Issues
**Events not publishing:**
- Check relay is writable
- Verify event is properly signed
- Check relay's accepted kinds
**Subscription not receiving events:**
- Verify filter syntax
- Check relay has matching events
- Ensure subscription isn't closed
**Signature verification fails:**
- Check event structure is correct
- Verify keys are in correct format
- Ensure event hasn't been modified
**NIP-05 lookup fails:**
- Check CORS headers on server
- Verify .well-known path is correct
- Handle network timeouts
## References
- **nostr-tools GitHub**: https://github.com/nbd-wtf/nostr-tools
- **Nostr Protocol**: https://github.com/nostr-protocol/nostr
- **NIPs Repository**: https://github.com/nostr-protocol/nips
- **NIP-01 (Basic Protocol)**: https://github.com/nostr-protocol/nips/blob/master/01.md
## Related Skills
- **nostr** - Nostr protocol fundamentals
- **svelte** - Building Nostr UIs with Svelte
- **applesauce-core** - Higher-level Nostr client utilities
- **applesauce-signers** - Nostr signing abstractions

162
.claude/skills/nostr/README.md Normal file
View File

@@ -0,0 +1,162 @@
# Nostr Protocol Skill
A comprehensive Claude skill for working with the Nostr protocol and implementing Nostr clients and relays.
## Overview
This skill provides expert-level knowledge of the Nostr protocol, including:
- Complete NIP (Nostr Implementation Possibilities) reference
- Event structure and cryptographic operations
- Client-relay WebSocket communication
- Event kinds and their behaviors
- Best practices and common pitfalls
## Contents
### SKILL.md
The main skill file containing:
- Core protocol concepts
- Event structure and signing
- WebSocket communication patterns
- Cryptographic operations
- Common implementation patterns
- Quick reference guides
### Reference Files
#### references/nips-overview.md
Comprehensive documentation of all standard NIPs including:
- Core protocol NIPs (NIP-01, NIP-02, etc.)
- Social features (reactions, reposts, channels)
- Identity and discovery (NIP-05, NIP-65)
- Security and privacy (NIP-44, NIP-42)
- Lightning integration (NIP-47, NIP-57)
- Advanced features
#### references/event-kinds.md
Complete reference for all Nostr event kinds:
- Core events (0-999)
- Regular events (1000-9999)
- Replaceable events (10000-19999)
- Ephemeral events (20000-29999)
- Parameterized replaceable events (30000-39999)
- Event lifecycle behaviors
- Common patterns and examples
#### references/common-mistakes.md
Detailed guide on implementation pitfalls:
- Event creation and signing errors
- WebSocket communication issues
- Filter query problems
- Threading mistakes
- Relay management errors
- Security vulnerabilities
- UX considerations
- Testing strategies
## When to Use
Use this skill when:
- Implementing Nostr clients or relays
- Working with Nostr events and messages
- Handling cryptographic signatures and keys
- Implementing any NIP
- Building social features on Nostr
- Debugging Nostr applications
- Discussing Nostr protocol architecture
## Key Features
### Complete NIP Coverage
All standard NIPs documented with:
- Purpose and status
- Implementation details
- Code examples
- Usage patterns
- Interoperability notes
### Cryptographic Operations
Detailed guidance on:
- Event signing with Schnorr signatures
- Event ID calculation
- Signature verification
- Key management (BIP-39, NIP-06)
- Encryption (NIP-04, NIP-44)
### WebSocket Protocol
Complete reference for:
- Message types (EVENT, REQ, CLOSE, OK, EOSE, etc.)
- Filter queries and optimization
- Subscription management
- Connection handling
- Error handling
### Event Lifecycle
Understanding of:
- Regular events (immutable)
- Replaceable events (latest only)
- Ephemeral events (real-time only)
- Parameterized replaceable events (by identifier)
### Best Practices
Comprehensive guidance on:
- Multi-relay architecture
- NIP-65 relay lists
- Event caching
- Optimistic UI
- Security considerations
- Performance optimization
## Quick Start Examples
### Publishing a Note
```javascript
const event = {
pubkey: userPublicKey,
created_at: Math.floor(Date.now() / 1000),
kind: 1,
tags: [],
content: "Hello Nostr!"
}
event.id = calculateId(event)
event.sig = signEvent(event, privateKey)
ws.send(JSON.stringify(["EVENT", event]))
```
### Subscribing to Events
```javascript
const filter = {
kinds: [1],
authors: [followedPubkey],
limit: 50
}
ws.send(JSON.stringify(["REQ", "sub-id", filter]))
```
### Replying to a Note
```javascript
const reply = {
kind: 1,
tags: [
["e", originalEventId, "", "root"],
["p", originalAuthorPubkey]
],
content: "Great post!"
}
```
## Official Resources
- **NIPs Repository**: https://github.com/nostr-protocol/nips
- **Nostr Website**: https://nostr.com
- **Nostr Documentation**: https://nostr.how
- **NIP Status**: https://nostr-nips.com
## Skill Maintenance
This skill is based on the official Nostr NIPs repository. As new NIPs are proposed and implemented, this skill should be updated to reflect the latest standards and best practices.
## License
Based on public Nostr protocol specifications (MIT License).

449
.claude/skills/nostr/SKILL.md Normal file
View File

@@ -0,0 +1,449 @@
---
name: nostr
description: This skill should be used when working with the Nostr protocol, implementing Nostr clients or relays, handling Nostr events, or discussing Nostr Implementation Possibilities (NIPs). Provides comprehensive knowledge of Nostr's decentralized protocol, event structure, cryptographic operations, and all standard NIPs.
---
# Nostr Protocol Expert
## Purpose
This skill provides expert-level assistance with the Nostr protocol, a simple, open protocol for global, decentralized, and censorship-resistant social networks. The protocol is built on relays and cryptographic keys, enabling direct peer-to-peer communication without central servers.
## When to Use
Activate this skill when:
- Implementing Nostr clients or relays
- Working with Nostr events and messages
- Handling cryptographic signatures and keys (schnorr signatures on secp256k1)
- Implementing any Nostr Implementation Possibility (NIP)
- Building social networking features on Nostr
- Querying or filtering Nostr events
- Discussing Nostr protocol architecture
- Implementing WebSocket communication with relays
## Core Concepts
### The Protocol Foundation
Nostr operates on two main components:
1. **Clients** - Applications users run to read/write data
2. **Relays** - Servers that store and forward messages
Key principles:
- Everyone runs a client
- Anyone can run a relay
- Users identified by public keys
- Messages signed with private keys
- No central authority or trusted servers
### Events Structure
All data in Nostr is represented as events. An event is a JSON object with this structure:
```json
{
"id": "<32-bytes lowercase hex-encoded sha256 of the serialized event data>",
"pubkey": "<32-bytes lowercase hex-encoded public key of the event creator>",
"created_at": "<unix timestamp in seconds>",
"kind": "<integer identifying event type>",
"tags": [
["<tag name>", "<tag value>", "<optional third param>", "..."]
],
"content": "<arbitrary string>",
"sig": "<64-bytes lowercase hex of the schnorr signature of the sha256 hash of the serialized event data>"
}
```
### Event Kinds
Standard event kinds (from various NIPs):
- `0` - Metadata (user profile)
- `1` - Text note (short post)
- `2` - Recommend relay
- `3` - Contacts (following list)
- `4` - Encrypted direct messages
- `5` - Event deletion
- `6` - Repost
- `7` - Reaction (like, emoji reaction)
- `40` - Channel creation
- `41` - Channel metadata
- `42` - Channel message
- `43` - Channel hide message
- `44` - Channel mute user
- `1000-9999` - Regular events
- `10000-19999` - Replaceable events
- `20000-29999` - Ephemeral events
- `30000-39999` - Parameterized replaceable events
### Tags
Common tag types:
- `["e", "<event-id>", "<relay-url>", "<marker>"]` - Reference to an event
- `["p", "<pubkey>", "<relay-url>"]` - Reference to a user
- `["a", "<kind>:<pubkey>:<d-tag>", "<relay-url>"]` - Reference to a replaceable event
- `["d", "<identifier>"]` - Identifier for parameterized replaceable events
- `["r", "<url>"]` - Reference/link to a web resource
- `["t", "<hashtag>"]` - Hashtag
- `["g", "<geohash>"]` - Geolocation
- `["nonce", "<number>", "<difficulty>"]` - Proof of work
- `["subject", "<subject>"]` - Subject/title
- `["client", "<client-name>"]` - Client application used
## Key NIPs Reference
For detailed specifications, refer to **references/nips-overview.md**.
### Core Protocol NIPs
#### NIP-01: Basic Protocol Flow
The foundation of Nostr. Defines:
- Event structure and validation
- Event ID calculation (SHA256 of serialized event)
- Signature verification (schnorr signatures)
- Client-relay communication via WebSocket
- Message types: EVENT, REQ, CLOSE, EOSE, OK, NOTICE
#### NIP-02: Contact List and Petnames
Event kind `3` for following lists:
- Each `p` tag represents a followed user
- Optional relay URL and petname in tag
- Replaceable event (latest overwrites)
#### NIP-04: Encrypted Direct Messages
Event kind `4` for private messages:
- Content encrypted with shared secret (ECDH)
- `p` tag for recipient pubkey
- Deprecated in favor of NIP-44
#### NIP-05: Mapping Nostr Keys to DNS
Internet identifier format: `name@domain.com`
- `.well-known/nostr.json` endpoint
- Maps names to pubkeys
- Optional relay list
#### NIP-09: Event Deletion
Event kind `5` to request deletion:
- Contains `e` tags for events to delete
- Relays should delete referenced events
- Only works for own events
#### NIP-10: Text Note References (Threads)
Conventions for `e` and `p` tags in replies:
- Root event reference
- Reply event reference
- Mentions
- Marker types: "root", "reply", "mention"
#### NIP-11: Relay Information Document
HTTP endpoint for relay metadata:
- GET request to relay URL
- Returns JSON with relay information
- Supported NIPs, software, limitations
### Social Features NIPs
#### NIP-25: Reactions
Event kind `7` for reactions:
- Content usually "+" (like) or emoji
- `e` tag for reacted event
- `p` tag for event author
#### NIP-42: Authentication
Client authentication to relays:
- AUTH message from relay
- Client responds with event kind `22242`
- Proves key ownership
#### NIP-50: Search
Query filter extension for full-text search:
- `search` field in REQ filters
- Implementation-defined behavior
### Advanced NIPs
#### NIP-19: bech32-encoded Entities
Human-readable identifiers:
- `npub`: public key
- `nsec`: private key (sensitive!)
- `note`: note/event ID
- `nprofile`: profile with relay hints
- `nevent`: event with relay hints
- `naddr`: replaceable event coordinate
#### NIP-44: Encrypted Payloads
Improved encryption for direct messages:
- Versioned encryption scheme
- Better security than NIP-04
- ChaCha20-Poly1305 AEAD
#### NIP-65: Relay List Metadata
Event kind `10002` for relay lists:
- Read/write relay preferences
- Optimizes relay discovery
- Replaceable event
## Client-Relay Communication
### WebSocket Messages
#### From Client to Relay
**EVENT** - Publish an event:
```json
["EVENT", <event JSON>]
```
**REQ** - Request events (subscription):
```json
["REQ", <subscription_id>, <filters JSON>, <filters JSON>, ...]
```
**CLOSE** - Stop a subscription:
```json
["CLOSE", <subscription_id>]
```
**AUTH** - Respond to auth challenge:
```json
["AUTH", <signed event kind 22242>]
```
#### From Relay to Client
**EVENT** - Send event to client:
```json
["EVENT", <subscription_id>, <event JSON>]
```
**OK** - Acceptance/rejection notice:
```json
["OK", <event_id>, <true|false>, <message>]
```
**EOSE** - End of stored events:
```json
["EOSE", <subscription_id>]
```
**CLOSED** - Subscription closed:
```json
["CLOSED", <subscription_id>, <message>]
```
**NOTICE** - Human-readable message:
```json
["NOTICE", <message>]
```
**AUTH** - Authentication challenge:
```json
["AUTH", <challenge>]
```
### Filter Objects
Filters select events in REQ messages:
```json
{
"ids": ["<event-id>", ...],
"authors": ["<pubkey>", ...],
"kinds": [<kind number>, ...],
"#e": ["<event-id>", ...],
"#p": ["<pubkey>", ...],
"#a": ["<coordinate>", ...],
"#t": ["<hashtag>", ...],
"since": <unix timestamp>,
"until": <unix timestamp>,
"limit": <max number of events>
}
```
Filtering rules:
- Arrays are ORed together
- Different fields are ANDed
- Tag filters: `#<single-letter>` matches tag values
- Prefix matching allowed for `ids` and `authors`
## Cryptographic Operations
### Key Management
- **Private Key**: 32-byte random value, keep secure
- **Public Key**: Derived via secp256k1
- **Encoding**: Hex (lowercase) or bech32
### Event Signing (schnorr)
Steps to create a signed event:
1. Set all fields except `id` and `sig`
2. Serialize event data to JSON (specific order)
3. Calculate SHA256 hash → `id`
4. Sign `id` with schnorr signature → `sig`
Serialization format for ID calculation:
```json
[
0,
<pubkey>,
<created_at>,
<kind>,
<tags>,
<content>
]
```
### Event Verification
Steps to verify an event:
1. Verify ID matches SHA256 of serialized data
2. Verify signature is valid schnorr signature
3. Check created_at is reasonable (not far future)
4. Validate event structure and required fields
## Implementation Best Practices
### For Clients
1. **Connect to Multiple Relays**: Don't rely on single relay
2. **Cache Events**: Reduce redundant relay queries
3. **Verify Signatures**: Always verify event signatures
4. **Handle Replaceable Events**: Keep only latest version
5. **Respect User Privacy**: Careful with sensitive data
6. **Implement NIP-65**: Use user's preferred relays
7. **Proper Error Handling**: Handle relay disconnections
8. **Pagination**: Use `limit`, `since`, `until` for queries
### For Relays
1. **Validate Events**: Check signatures, IDs, structure
2. **Rate Limiting**: Prevent spam and abuse
3. **Storage Management**: Ephemeral events, retention policies
4. **Implement NIP-11**: Provide relay information
5. **WebSocket Optimization**: Handle many connections
6. **Filter Optimization**: Efficient event querying
7. **Consider NIP-42**: Authentication for write access
8. **Performance**: Index by pubkey, kind, tags, timestamp
### Security Considerations
1. **Never Expose Private Keys**: Handle nsec carefully
2. **Validate All Input**: Prevent injection attacks
3. **Use NIP-44**: For encrypted messages (not NIP-04)
4. **Check Event Timestamps**: Reject far-future events
5. **Implement Proof of Work**: NIP-13 for spam prevention
6. **Sanitize Content**: XSS prevention in displayed content
7. **Relay Trust**: Don't trust single relay for critical data
## Common Patterns
### Publishing a Note
```javascript
const event = {
pubkey: userPublicKey,
created_at: Math.floor(Date.now() / 1000),
kind: 1,
tags: [],
content: "Hello Nostr!",
}
// Calculate ID and sign
event.id = calculateId(event)
event.sig = signEvent(event, privateKey)
// Publish to relay
ws.send(JSON.stringify(["EVENT", event]))
```
### Subscribing to Notes
```javascript
const filter = {
kinds: [1],
authors: [followedPubkey1, followedPubkey2],
limit: 50
}
ws.send(JSON.stringify(["REQ", "my-sub", filter]))
```
### Replying to a Note
```javascript
const reply = {
kind: 1,
tags: [
["e", originalEventId, relayUrl, "root"],
["p", originalAuthorPubkey]
],
content: "Great post!",
// ... other fields
}
```
### Reacting to a Note
```javascript
const reaction = {
kind: 7,
tags: [
["e", eventId],
["p", eventAuthorPubkey]
],
content: "+", // or emoji
// ... other fields
}
```
## Development Resources
### Essential NIPs for Beginners
Start with these NIPs in order:
1. **NIP-01** - Basic protocol (MUST read)
2. **NIP-19** - Bech32 identifiers
3. **NIP-02** - Following lists
4. **NIP-10** - Threaded conversations
5. **NIP-25** - Reactions
6. **NIP-65** - Relay lists
### Testing and Development
- **Relay Implementations**: nostream, strfry, relay.py
- **Test Relays**: wss://relay.damus.io, wss://nos.lol
- **Libraries**: nostr-tools (JS), rust-nostr (Rust), python-nostr (Python)
- **Development Tools**: NostrDebug, Nostr Army Knife, nostril
- **Reference Clients**: Damus (iOS), Amethyst (Android), Snort (Web)
### Key Repositories
- **NIPs Repository**: https://github.com/nostr-protocol/nips
- **Awesome Nostr**: https://github.com/aljazceru/awesome-nostr
- **Nostr Resources**: https://nostr.how
## Reference Files
For comprehensive NIP details, see:
- **references/nips-overview.md** - Detailed descriptions of all standard NIPs
- **references/event-kinds.md** - Complete event kinds reference
- **references/common-mistakes.md** - Pitfalls and how to avoid them
## Quick Checklist
When implementing Nostr:
- [ ] Events have all required fields (id, pubkey, created_at, kind, tags, content, sig)
- [ ] Event IDs calculated correctly (SHA256 of serialization)
- [ ] Signatures verified (schnorr on secp256k1)
- [ ] WebSocket messages properly formatted
- [ ] Filter queries optimized with appropriate limits
- [ ] Handling replaceable events correctly
- [ ] Connected to multiple relays for redundancy
- [ ] Following relevant NIPs for features implemented
- [ ] Private keys never exposed or transmitted
- [ ] Event timestamps validated
## Official Resources
- **NIPs Repository**: https://github.com/nostr-protocol/nips
- **Nostr Website**: https://nostr.com
- **Nostr Documentation**: https://nostr.how
- **NIP Status**: https://nostr-nips.com

657
.claude/skills/nostr/references/common-mistakes.md Normal file
View File

@@ -0,0 +1,657 @@
# Common Nostr Implementation Mistakes and How to Avoid Them
This document highlights frequent errors made when implementing Nostr clients and relays, along with solutions.
## Event Creation and Signing
### Mistake 1: Incorrect Event ID Calculation
**Problem**: Wrong serialization order or missing fields when calculating SHA256.
**Correct Serialization**:
```json
[
0, // Must be integer 0
<pubkey>, // Lowercase hex string
<created_at>, // Unix timestamp integer
<kind>, // Integer
<tags>, // Array of arrays
<content> // String
]
```
**Common errors**:
- Using string "0" instead of integer 0
- Including `id` or `sig` fields in serialization
- Wrong field order
- Not using compact JSON (no spaces)
- Using uppercase hex
**Fix**: Serialize exactly as shown, compact JSON, SHA256 the UTF-8 bytes.
### Mistake 2: Wrong Signature Algorithm
**Problem**: Using ECDSA instead of Schnorr signatures.
**Correct**:
- Use Schnorr signatures (BIP-340)
- Curve: secp256k1
- Sign the 32-byte event ID
**Libraries**:
- JavaScript: noble-secp256k1
- Rust: secp256k1
- Go: btcsuite/btcd/btcec/v2/schnorr
- Python: secp256k1-py
### Mistake 3: Invalid created_at Timestamps
**Problem**: Events with far-future timestamps or very old timestamps.
**Best practices**:
- Use current Unix time: `Math.floor(Date.now() / 1000)`
- Relays often reject if `created_at > now + 15 minutes`
- Don't backdate events to manipulate ordering
**Fix**: Always use current time when creating events.
### Mistake 4: Malformed Tags
**Problem**: Tags that aren't arrays or have wrong structure.
**Correct format**:
```json
{
"tags": [
["e", "event-id", "relay-url", "marker"],
["p", "pubkey", "relay-url"],
["t", "hashtag"]
]
}
```
**Common errors**:
- Using objects instead of arrays: `{"e": "..."}` ❌
- Missing inner arrays: `["e", "event-id"]` when nested in tags is wrong
- Wrong nesting depth
- Non-string values (except for specific NIPs)
### Mistake 5: Not Handling Replaceable Events
**Problem**: Showing multiple versions of replaceable events.
**Event types**:
- **Replaceable (10000-19999)**: Same author + kind → replace
- **Parameterized Replaceable (30000-39999)**: Same author + kind + d-tag → replace
**Fix**:
```javascript
// For replaceable events
const key = `${event.pubkey}:${event.kind}`
if (latestEvents[key]?.created_at < event.created_at) {
latestEvents[key] = event
}
// For parameterized replaceable events
const dTag = event.tags.find(t => t[0] === 'd')?.[1] || ''
const key = `${event.pubkey}:${event.kind}:${dTag}`
if (latestEvents[key]?.created_at < event.created_at) {
latestEvents[key] = event
}
```
## WebSocket Communication
### Mistake 6: Not Handling EOSE
**Problem**: Loading indicators never finish or show wrong state.
**Solution**:
```javascript
const receivedEvents = new Set()
let eoseReceived = false
ws.onmessage = (msg) => {
const [type, ...rest] = JSON.parse(msg.data)
if (type === 'EVENT') {
const [subId, event] = rest
receivedEvents.add(event.id)
displayEvent(event)
}
if (type === 'EOSE') {
eoseReceived = true
hideLoadingSpinner()
}
}
```
### Mistake 7: Not Closing Subscriptions
**Problem**: Memory leaks and wasted bandwidth from unclosed subscriptions.
**Fix**: Always send CLOSE when done:
```javascript
ws.send(JSON.stringify(['CLOSE', subId]))
```
**Best practices**:
- Close when component unmounts
- Close before opening new subscription with same ID
- Use unique subscription IDs
- Track active subscriptions
### Mistake 8: Ignoring OK Messages
**Problem**: Not knowing if events were accepted or rejected.
**Solution**:
```javascript
ws.onmessage = (msg) => {
const [type, eventId, accepted, message] = JSON.parse(msg.data)
if (type === 'OK') {
if (!accepted) {
console.error(`Event ${eventId} rejected: ${message}`)
handleRejection(eventId, message)
}
}
}
```
**Common rejection reasons**:
- `pow:` - Insufficient proof of work
- `blocked:` - Pubkey or content blocked
- `rate-limited:` - Too many requests
- `invalid:` - Failed validation
### Mistake 9: Sending Events Before WebSocket Ready
**Problem**: Events lost because WebSocket not connected.
**Fix**:
```javascript
const sendWhenReady = (ws, message) => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(message)
} else {
ws.addEventListener('open', () => ws.send(message), { once: true })
}
}
```
### Mistake 10: Not Handling WebSocket Disconnections
**Problem**: App breaks when relay goes offline.
**Solution**: Implement reconnection with exponential backoff:
```javascript
let reconnectDelay = 1000
const maxDelay = 30000
const connect = () => {
const ws = new WebSocket(relayUrl)
ws.onclose = () => {
setTimeout(() => {
reconnectDelay = Math.min(reconnectDelay * 2, maxDelay)
connect()
}, reconnectDelay)
}
ws.onopen = () => {
reconnectDelay = 1000 // Reset on successful connection
resubscribe() // Re-establish subscriptions
}
}
```
## Filter Queries
### Mistake 11: Overly Broad Filters
**Problem**: Requesting too many events, overwhelming relay and client.
**Bad**:
```json
{
"kinds": [1],
"limit": 10000
}
```
**Good**:
```json
{
"kinds": [1],
"authors": ["<followed-users>"],
"limit": 50,
"since": 1234567890
}
```
**Best practices**:
- Always set reasonable `limit` (50-500)
- Filter by `authors` when possible
- Use `since`/`until` for time ranges
- Be specific with `kinds`
- Multiple smaller queries > one huge query
### Mistake 12: Not Using Prefix Matching
**Problem**: Full hex strings in filters unnecessarily.
**Optimization**:
```json
{
"ids": ["abc12345"], // 8 chars enough for uniqueness
"authors": ["def67890"]
}
```
Relays support prefix matching for `ids` and `authors`.
### Mistake 13: Duplicate Filter Fields
**Problem**: Redundant filter conditions.
**Bad**:
```json
{
"authors": ["pubkey1", "pubkey1"],
"kinds": [1, 1]
}
```
**Good**:
```json
{
"authors": ["pubkey1"],
"kinds": [1]
}
```
Deduplicate filter arrays.
## Threading and References
### Mistake 14: Incorrect Thread Structure
**Problem**: Missing root/reply markers or wrong tag order.
**Correct reply structure** (NIP-10):
```json
{
"kind": 1,
"tags": [
["e", "<root-event-id>", "<relay>", "root"],
["e", "<parent-event-id>", "<relay>", "reply"],
["p", "<author1-pubkey>"],
["p", "<author2-pubkey>"]
]
}
```
**Key points**:
- Root event should have "root" marker
- Direct parent should have "reply" marker
- Include `p` tags for all mentioned users
- Relay hints are optional but helpful
### Mistake 15: Missing p Tags in Replies
**Problem**: Authors not notified of replies.
**Fix**: Always add `p` tag for:
- Original author
- Authors mentioned in content
- Authors in the thread chain
```json
{
"tags": [
["e", "event-id", "", "reply"],
["p", "original-author"],
["p", "mentioned-user1"],
["p", "mentioned-user2"]
]
}
```
### Mistake 16: Not Using Markers
**Problem**: Ambiguous thread structure.
**Solution**: Always use markers in `e` tags:
- `root` - Root of thread
- `reply` - Direct parent
- `mention` - Referenced but not replied to
Without markers, clients must guess thread structure.
## Relay Management
### Mistake 17: Relying on Single Relay
**Problem**: Single point of failure, censorship vulnerability.
**Solution**: Connect to multiple relays (5-15 common):
```javascript
const relays = [
'wss://relay1.com',
'wss://relay2.com',
'wss://relay3.com'
]
const connections = relays.map(url => connect(url))
```
**Best practices**:
- Publish to 3-5 write relays
- Read from 5-10 read relays
- Use NIP-65 for user's preferred relays
- Fall back to NIP-05 relays
- Implement relay rotation on failure
### Mistake 18: Not Implementing NIP-65
**Problem**: Querying wrong relays, missing user's events.
**Correct flow**:
1. Fetch user's kind `10002` event (relay list)
2. Connect to their read relays to fetch their content
3. Connect to their write relays to send them messages
```javascript
async function getUserRelays(pubkey) {
// Fetch kind 10002
const relayList = await fetchEvent({
kinds: [10002],
authors: [pubkey]
})
const readRelays = []
const writeRelays = []
relayList.tags.forEach(([tag, url, mode]) => {
if (tag === 'r') {
if (!mode || mode === 'read') readRelays.push(url)
if (!mode || mode === 'write') writeRelays.push(url)
}
})
return { readRelays, writeRelays }
}
```
### Mistake 19: Not Respecting Relay Limitations
**Problem**: Violating relay policies, getting rate limited or banned.
**Solution**: Fetch and respect NIP-11 relay info:
```javascript
const getRelayInfo = async (relayUrl) => {
const url = relayUrl.replace('wss://', 'https://').replace('ws://', 'http://')
const response = await fetch(url, {
headers: { 'Accept': 'application/nostr+json' }
})
return response.json()
}
// Respect limitations
const info = await getRelayInfo(relayUrl)
const maxLimit = info.limitation?.max_limit || 500
const maxFilters = info.limitation?.max_filters || 10
```
## Security
### Mistake 20: Exposing Private Keys
**Problem**: Including nsec in client code, logs, or network requests.
**Never**:
- Store nsec in localStorage without encryption
- Log private keys
- Send nsec over network
- Display nsec to user unless explicitly requested
- Hard-code private keys
**Best practices**:
- Use NIP-07 (browser extension) when possible
- Encrypt keys at rest
- Use NIP-46 (remote signing) for web apps
- Warn users when showing nsec
### Mistake 21: Not Verifying Signatures
**Problem**: Accepting invalid events, vulnerability to attacks.
**Always verify**:
```javascript
const verifyEvent = (event) => {
// 1. Verify ID
const calculatedId = sha256(serializeEvent(event))
if (calculatedId !== event.id) return false
// 2. Verify signature
const signatureValid = schnorr.verify(
event.sig,
event.id,
event.pubkey
)
if (!signatureValid) return false
// 3. Check timestamp
const now = Math.floor(Date.now() / 1000)
if (event.created_at > now + 900) return false // 15 min future
return true
}
```
**Verify before**:
- Displaying to user
- Storing in database
- Using event data for logic
### Mistake 22: Using NIP-04 Encryption
**Problem**: Weak encryption, vulnerable to attacks.
**Solution**: Use NIP-44 instead:
- Modern authenticated encryption
- ChaCha20-Poly1305 AEAD
- Proper key derivation
- Version byte for upgradability
**Migration**: Update to NIP-44 for all new encrypted messages.
### Mistake 23: Not Sanitizing Content
**Problem**: XSS vulnerabilities in displayed content.
**Solution**: Sanitize before rendering:
```javascript
import DOMPurify from 'dompurify'
const safeContent = DOMPurify.sanitize(event.content, {
ALLOWED_TAGS: ['b', 'i', 'u', 'a', 'code', 'pre'],
ALLOWED_ATTR: ['href', 'target', 'rel']
})
```
**Especially critical for**:
- Markdown rendering
- Link parsing
- Image URLs
- User-provided HTML
## User Experience
### Mistake 24: Not Caching Events
**Problem**: Re-fetching same events repeatedly, poor performance.
**Solution**: Implement event cache:
```javascript
const eventCache = new Map()
const cacheEvent = (event) => {
eventCache.set(event.id, event)
}
const getCachedEvent = (eventId) => {
return eventCache.get(eventId)
}
```
**Cache strategies**:
- LRU eviction for memory management
- IndexedDB for persistence
- Invalidate replaceable events on update
- Cache metadata (kind 0) aggressively
### Mistake 25: Not Implementing Optimistic UI
**Problem**: Slow feeling app, waiting for relay confirmation.
**Solution**: Show user's events immediately:
```javascript
const publishEvent = async (event) => {
// Immediately show to user
displayEvent(event, { pending: true })
// Publish to relays
const results = await Promise.all(
relays.map(relay => relay.publish(event))
)
// Update status based on results
const success = results.some(r => r.accepted)
displayEvent(event, { pending: false, success })
}
```
### Mistake 26: Poor Loading States
**Problem**: User doesn't know if app is working.
**Solution**: Clear loading indicators:
- Show spinner until EOSE
- Display "Loading..." placeholder
- Show how many relays responded
- Indicate connection status per relay
### Mistake 27: Not Handling Large Threads
**Problem**: Loading entire thread at once, performance issues.
**Solution**: Implement pagination:
```javascript
const loadThread = async (eventId, cursor = null) => {
const filter = {
"#e": [eventId],
kinds: [1],
limit: 20,
until: cursor
}
const replies = await fetchEvents(filter)
return { replies, nextCursor: replies[replies.length - 1]?.created_at }
}
```
## Testing
### Mistake 28: Not Testing with Multiple Relays
**Problem**: App works with one relay but fails with others.
**Solution**: Test with:
- Fast relays
- Slow relays
- Unreliable relays
- Paid relays (auth required)
- Relays with different NIP support
### Mistake 29: Not Testing Edge Cases
**Critical tests**:
- Empty filter results
- WebSocket disconnections
- Malformed events
- Very long content
- Invalid signatures
- Relay errors
- Rate limiting
- Concurrent operations
### Mistake 30: Not Monitoring Performance
**Metrics to track**:
- Event verification time
- WebSocket latency per relay
- Events per second processed
- Memory usage (event cache)
- Subscription count
- Failed publishes
## Best Practices Checklist
**Event Creation**:
- [ ] Correct serialization for ID
- [ ] Schnorr signatures
- [ ] Current timestamp
- [ ] Valid tag structure
- [ ] Handle replaceable events
**WebSocket**:
- [ ] Handle EOSE
- [ ] Close subscriptions
- [ ] Process OK messages
- [ ] Check WebSocket state
- [ ] Reconnection logic
**Filters**:
- [ ] Set reasonable limits
- [ ] Specific queries
- [ ] Deduplicate arrays
- [ ] Use prefix matching
**Threading**:
- [ ] Use root/reply markers
- [ ] Include all p tags
- [ ] Proper thread structure
**Relays**:
- [ ] Multiple relays
- [ ] Implement NIP-65
- [ ] Respect limitations
- [ ] Handle failures
**Security**:
- [ ] Never expose nsec
- [ ] Verify all signatures
- [ ] Use NIP-44 encryption
- [ ] Sanitize content
**UX**:
- [ ] Cache events
- [ ] Optimistic UI
- [ ] Loading states
- [ ] Pagination
**Testing**:
- [ ] Multiple relays
- [ ] Edge cases
- [ ] Monitor performance
## Resources
- **nostr-tools**: JavaScript library with best practices
- **rust-nostr**: Rust implementation with strong typing
- **NIPs Repository**: Official specifications
- **Nostr Dev**: Community resources and help

361
.claude/skills/nostr/references/event-kinds.md Normal file
View File

@@ -0,0 +1,361 @@
# Nostr Event Kinds - Complete Reference
This document provides a comprehensive list of all standard and commonly-used Nostr event kinds.
## Standard Event Kinds
### Core Events (0-999)
#### Metadata and Profile
- **0**: `Metadata` - User profile information (name, about, picture, etc.)
- Replaceable
- Content: JSON with profile fields
#### Text Content
- **1**: `Text Note` - Short-form post (like a tweet)
- Regular event (not replaceable)
- Most common event type
#### Relay Recommendations
- **2**: `Recommend Relay` - Deprecated, use NIP-65 instead
#### Contact Lists
- **3**: `Contacts` - Following list with optional relay hints
- Replaceable
- Tags: `p` tags for each followed user
#### Encrypted Messages
- **4**: `Encrypted Direct Message` - Private message (NIP-04, deprecated)
- Regular event
- Use NIP-44 instead for better security
#### Content Management
- **5**: `Event Deletion` - Request to delete events
- Tags: `e` tags for events to delete
- Only works for own events
#### Sharing
- **6**: `Repost` - Share another event
- Tags: `e` for reposted event, `p` for original author
- May include original event in content
#### Reactions
- **7**: `Reaction` - Like, emoji reaction to event
- Content: "+" or emoji
- Tags: `e` for reacted event, `p` for author
### Channel Events (40-49)
- **40**: `Channel Creation` - Create a public chat channel
- **41**: `Channel Metadata` - Set channel name, about, picture
- **42**: `Channel Message` - Post message in channel
- **43**: `Channel Hide Message` - Hide a message in channel
- **44**: `Channel Mute User` - Mute a user in channel
### Regular Events (1000-9999)
Regular events are never deleted or replaced. All versions are kept.
- **1000**: `Example regular event`
- **1063**: `File Metadata` (NIP-94) - Metadata for shared files
- Tags: url, MIME type, hash, size, dimensions
### Replaceable Events (10000-19999)
Only the latest event of each kind is kept per pubkey.
- **10000**: `Mute List` - List of muted users/content
- **10001**: `Pin List` - Pinned events
- **10002**: `Relay List Metadata` (NIP-65) - User's preferred relays
- Critical for routing
- Tags: `r` with relay URLs and read/write markers
### Ephemeral Events (20000-29999)
Not stored by relays, only forwarded once.
- **20000**: `Example ephemeral event`
- **21000**: `Typing Indicator` - User is typing
- **22242**: `Client Authentication` (NIP-42) - Auth response to relay
### Parameterized Replaceable Events (30000-39999)
Replaced based on `d` tag value.
#### Lists (30000-30009)
- **30000**: `Categorized People List` - Custom people lists
- `d` tag: list identifier
- `p` tags: people in list
- **30001**: `Categorized Bookmark List` - Bookmark collections
- `d` tag: list identifier
- `e` or `a` tags: bookmarked items
- **30008**: `Badge Definition` (NIP-58) - Define a badge/achievement
- `d` tag: badge ID
- Tags: name, description, image
- **30009**: `Profile Badges` (NIP-58) - Badges displayed on profile
- `d` tag: badge ID
- `e` or `a` tags: badge awards
#### Long-form Content (30023)
- **30023**: `Long-form Article` (NIP-23) - Blog post, article
- `d` tag: article identifier (slug)
- Tags: title, summary, published_at, image
- Content: Markdown
#### Application Data (30078)
- **30078**: `Application-specific Data` (NIP-78)
- `d` tag: app-name:data-key
- Content: app-specific data (may be encrypted)
#### Other Parameterized Replaceables
- **31989**: `Application Handler Information` (NIP-89)
- Declares app can handle certain event kinds
- **31990**: `Handler Recommendation` (NIP-89)
- User's preferred apps for event kinds
## Special Event Kinds
### Authentication & Signing
- **22242**: `Client Authentication` - Prove key ownership to relay
- **24133**: `Nostr Connect` - Remote signer protocol (NIP-46)
### Lightning & Payments
- **9734**: `Zap Request` (NIP-57) - Request Lightning payment
- Not published to regular relays
- Sent to LNURL provider
- **9735**: `Zap Receipt` (NIP-57) - Proof of Lightning payment
- Published by LNURL provider
- Proves zap was paid
- **23194**: `Wallet Request` (NIP-47) - Request wallet operation
- **23195**: `Wallet Response` (NIP-47) - Response to wallet request
### Content & Annotations
- **1984**: `Reporting` (NIP-56) - Report content/users
- Tags: reason (spam, illegal, etc.)
- **9802**: `Highlights` (NIP-84) - Highlight text
- Content: highlighted text
- Tags: context, source event
### Badges & Reputation
- **8**: `Badge Award` (NIP-58) - Award a badge to someone
- Tags: `a` for badge definition, `p` for recipient
### Generic Events
- **16**: `Generic Repost` (NIP-18) - Repost any event kind
- More flexible than kind 6
- **27235**: `HTTP Auth` (NIP-98) - Authenticate HTTP requests
- Tags: URL, method
## Event Kind Ranges Summary
| Range | Type | Behavior | Examples |
|-------|------|----------|----------|
| 0-999 | Core | Varies | Metadata, notes, reactions |
| 1000-9999 | Regular | Immutable, all kept | File metadata |
| 10000-19999 | Replaceable | Only latest kept | Mute list, relay list |
| 20000-29999 | Ephemeral | Not stored | Typing, presence |
| 30000-39999 | Parameterized Replaceable | Replaced by `d` tag | Articles, lists, badges |
## Event Lifecycle
### Regular Events (1000-9999)
```
Event A published → Stored
Event A' published → Both A and A' stored
```
### Replaceable Events (10000-19999)
```
Event A published → Stored
Event A' published (same kind, same pubkey) → A deleted, A' stored
```
### Parameterized Replaceable Events (30000-39999)
```
Event A (d="foo") published → Stored
Event B (d="bar") published → Both stored (different d)
Event A' (d="foo") published → A deleted, A' stored (same d)
```
### Ephemeral Events (20000-29999)
```
Event A published → Forwarded to subscribers, NOT stored
```
## Common Patterns
### Metadata (Kind 0)
```json
{
"kind": 0,
"content": "{\"name\":\"Alice\",\"about\":\"Nostr user\",\"picture\":\"https://...\",\"nip05\":\"alice@example.com\"}",
"tags": []
}
```
### Text Note (Kind 1)
```json
{
"kind": 1,
"content": "Hello Nostr!",
"tags": [
["t", "nostr"],
["t", "hello"]
]
}
```
### Reply (Kind 1 with thread tags)
```json
{
"kind": 1,
"content": "Great post!",
"tags": [
["e", "<root-event-id>", "<relay>", "root"],
["e", "<parent-event-id>", "<relay>", "reply"],
["p", "<author-pubkey>"]
]
}
```
### Reaction (Kind 7)
```json
{
"kind": 7,
"content": "+",
"tags": [
["e", "<reacted-event-id>"],
["p", "<event-author-pubkey>"],
["k", "1"]
]
}
```
### Long-form Article (Kind 30023)
```json
{
"kind": 30023,
"content": "# My Article\n\nContent here...",
"tags": [
["d", "my-article-slug"],
["title", "My Article"],
["summary", "This is about..."],
["published_at", "1234567890"],
["t", "nostr"],
["image", "https://..."]
]
}
```
### Relay List (Kind 10002)
```json
{
"kind": 10002,
"content": "",
"tags": [
["r", "wss://relay1.com"],
["r", "wss://relay2.com", "write"],
["r", "wss://relay3.com", "read"]
]
}
```
### Zap Request (Kind 9734)
```json
{
"kind": 9734,
"content": "",
"tags": [
["relays", "wss://relay1.com", "wss://relay2.com"],
["amount", "21000"],
["lnurl", "lnurl..."],
["p", "<recipient-pubkey>"],
["e", "<event-id>"]
]
}
```
### File Metadata (Kind 1063)
```json
{
"kind": 1063,
"content": "My photo from the trip",
"tags": [
["url", "https://cdn.example.com/image.jpg"],
["m", "image/jpeg"],
["x", "abc123..."],
["size", "524288"],
["dim", "1920x1080"],
["blurhash", "LEHV6n..."]
]
}
```
### Report (Kind 1984)
```json
{
"kind": 1984,
"content": "This is spam",
"tags": [
["e", "<reported-event-id>", "<relay>"],
["p", "<reported-pubkey>"],
["report", "spam"]
]
}
```
## Future Event Kinds
The event kind space is open-ended. New NIPs may define new event kinds.
**Guidelines for new event kinds**:
1. Use appropriate range for desired behavior
2. Document in a NIP
3. Implement in at least 2 clients and 1 relay
4. Ensure backwards compatibility
5. Don't overlap with existing kinds
**Custom event kinds**:
- Applications can use undefined event kinds
- Document behavior for interoperability
- Consider proposing as a NIP if useful broadly
## Event Kind Selection Guide
**Choose based on lifecycle needs**:
- **Regular (1000-9999)**: When you need history
- User posts, comments, reactions
- Payment records, receipts
- Immutable records
- **Replaceable (10000-19999)**: When you need latest state
- User settings, preferences
- Mute/block lists
- Current status
- **Ephemeral (20000-29999)**: When you need real-time only
- Typing indicators
- Online presence
- Temporary notifications
- **Parameterized Replaceable (30000-39999)**: When you need multiple latest states
- Articles (one per slug)
- Product listings (one per product ID)
- Configuration sets (one per setting name)
## References
- NIPs Repository: https://github.com/nostr-protocol/nips
- NIP-16: Event Treatment
- NIP-01: Event structure
- Various feature NIPs for specific kinds

1170
.claude/skills/nostr/references/nips-overview.md Normal file
View File

File diff suppressed because it is too large Load Diff

119
.claude/skills/react/README.md Normal file
View File

@@ -0,0 +1,119 @@
# React 19 Skill
A comprehensive Claude skill for working with React 19, including hooks, components, server components, and modern React architecture.
## Contents
### Main Skill File
- **SKILL.md** - Main skill document with React 19 fundamentals, hooks, components, and best practices
### References
- **hooks-quick-reference.md** - Quick reference for all React hooks with examples
- **server-components.md** - Complete guide to React Server Components and Server Functions
- **performance.md** - Performance optimization strategies and techniques
### Examples
- **practical-patterns.tsx** - Real-world React patterns and solutions
## What This Skill Covers
### Core Topics
- React 19 features and improvements
- All built-in hooks (useState, useEffect, useTransition, useOptimistic, etc.)
- Component patterns and composition
- Server Components and Server Functions
- React Compiler and automatic optimization
- Performance optimization techniques
- Form handling and validation
- Error boundaries and error handling
- Context and global state management
- Code splitting and lazy loading
### Best Practices
- Component design principles
- State management strategies
- Performance optimization
- Error handling patterns
- TypeScript integration
- Testing considerations
- Accessibility guidelines
## When to Use This Skill
Use this skill when:
- Building React 19 applications
- Working with React hooks
- Implementing server components
- Optimizing React performance
- Troubleshooting React-specific issues
- Understanding concurrent features
- Working with forms and user input
- Implementing complex UI patterns
## Quick Start Examples
### Basic Component
```typescript
interface ButtonProps {
label: string
onClick: () => void
}
const Button = ({ label, onClick }: ButtonProps) => {
return <button onClick={onClick}>{label}</button>
}
```
### Using Hooks
```typescript
const Counter = () => {
const [count, setCount] = useState(0)
useEffect(() => {
console.log(`Count is: ${count}`)
}, [count])
return (
<button onClick={() => setCount(c => c + 1)}>
Count: {count}
</button>
)
}
```
### Server Component
```typescript
const Page = async () => {
const data = await fetchData()
return <div>{data}</div>
}
```
### Server Function
```typescript
'use server'
export async function createUser(formData: FormData) {
const name = formData.get('name')
return await db.user.create({ data: { name } })
}
```
## Related Skills
- **typescript** - TypeScript patterns for React
- **ndk** - Nostr integration with React
- **skill-creator** - Creating reusable component libraries
## Resources
- [React Documentation](https://react.dev)
- [React API Reference](https://react.dev/reference/react)
- [React Hooks Reference](https://react.dev/reference/react/hooks)
- [React Server Components](https://react.dev/reference/rsc)
- [React Compiler](https://react.dev/reference/react-compiler)
## Version
This skill is based on React 19.2 and includes the latest features and APIs.

1026
.claude/skills/react/SKILL.md Normal file
View File

File diff suppressed because it is too large Load Diff

878
.claude/skills/react/examples/practical-patterns.tsx Normal file
View File

@@ -0,0 +1,878 @@
# React Practical Examples
This file contains real-world examples of React patterns and solutions.
## Example 1: Custom Hook for Data Fetching
```typescript
import { useState, useEffect } from 'react'
interface FetchState<T> {
data: T | null
loading: boolean
error: Error | null
}
const useFetch = <T,>(url: string) => {
const [state, setState] = useState<FetchState<T>>({
data: null,
loading: true,
error: null
})
useEffect(() => {
let cancelled = false
const controller = new AbortController()
const fetchData = async () => {
try {
setState(prev => ({ ...prev, loading: true, error: null }))
const response = await fetch(url, {
signal: controller.signal
})
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`)
}
const data = await response.json()
if (!cancelled) {
setState({ data, loading: false, error: null })
}
} catch (error) {
if (!cancelled && error.name !== 'AbortError') {
setState({
data: null,
loading: false,
error: error as Error
})
}
}
}
fetchData()
return () => {
cancelled = true
controller.abort()
}
}, [url])
return state
}
// Usage
const UserProfile = ({ userId }: { userId: string }) => {
const { data, loading, error } = useFetch<User>(`/api/users/${userId}`)
if (loading) return <Spinner />
if (error) return <ErrorMessage error={error} />
if (!data) return null
return <UserCard user={data} />
}
```
## Example 2: Form with Validation
```typescript
import { useState, useCallback } from 'react'
import { z } from 'zod'
const userSchema = z.object({
name: z.string().min(2, 'Name must be at least 2 characters'),
email: z.string().email('Invalid email address'),
age: z.number().min(18, 'Must be 18 or older')
})
type UserForm = z.infer<typeof userSchema>
type FormErrors = Partial<Record<keyof UserForm, string>>
const UserForm = () => {
const [formData, setFormData] = useState<UserForm>({
name: '',
email: '',
age: 0
})
const [errors, setErrors] = useState<FormErrors>({})
const [isSubmitting, setIsSubmitting] = useState(false)
const handleChange = useCallback((
field: keyof UserForm,
value: string | number
) => {
setFormData(prev => ({ ...prev, [field]: value }))
// Clear error when user starts typing
setErrors(prev => ({ ...prev, [field]: undefined }))
}, [])
const handleSubmit = async (e: React.FormEvent) => {
e.preventDefault()
// Validate
const result = userSchema.safeParse(formData)
if (!result.success) {
const fieldErrors: FormErrors = {}
result.error.errors.forEach(err => {
const field = err.path[0] as keyof UserForm
fieldErrors[field] = err.message
})
setErrors(fieldErrors)
return
}
// Submit
setIsSubmitting(true)
try {
await submitUser(result.data)
// Success handling
} catch (error) {
console.error(error)
} finally {
setIsSubmitting(false)
}
}
return (
<form onSubmit={handleSubmit}>
<div>
<label htmlFor="name">Name</label>
<input
id="name"
value={formData.name}
onChange={e => handleChange('name', e.target.value)}
/>
{errors.name && <span className="error">{errors.name}</span>}
</div>
<div>
<label htmlFor="email">Email</label>
<input
id="email"
type="email"
value={formData.email}
onChange={e => handleChange('email', e.target.value)}
/>
{errors.email && <span className="error">{errors.email}</span>}
</div>
<div>
<label htmlFor="age">Age</label>
<input
id="age"
type="number"
value={formData.age || ''}
onChange={e => handleChange('age', Number(e.target.value))}
/>
{errors.age && <span className="error">{errors.age}</span>}
</div>
<button type="submit" disabled={isSubmitting}>
{isSubmitting ? 'Submitting...' : 'Submit'}
</button>
</form>
)
}
```
## Example 3: Modal with Portal
```typescript
import { createPortal } from 'react-dom'
import { useEffect, useRef, useState } from 'react'
interface ModalProps {
isOpen: boolean
onClose: () => void
children: React.ReactNode
title?: string
}
const Modal = ({ isOpen, onClose, children, title }: ModalProps) => {
const modalRef = useRef<HTMLDivElement>(null)
// Close on Escape key
useEffect(() => {
const handleEscape = (e: KeyboardEvent) => {
if (e.key === 'Escape') onClose()
}
if (isOpen) {
document.addEventListener('keydown', handleEscape)
// Prevent body scroll
document.body.style.overflow = 'hidden'
}
return () => {
document.removeEventListener('keydown', handleEscape)
document.body.style.overflow = 'unset'
}
}, [isOpen, onClose])
// Close on backdrop click
const handleBackdropClick = (e: React.MouseEvent) => {
if (e.target === modalRef.current) {
onClose()
}
}
if (!isOpen) return null
return createPortal(
<div
ref={modalRef}
className="fixed inset-0 bg-black/50 flex items-center justify-center z-50"
onClick={handleBackdropClick}
>
<div className="bg-white rounded-lg p-6 max-w-md w-full mx-4">
<div className="flex justify-between items-center mb-4">
{title && <h2 className="text-xl font-bold">{title}</h2>}
<button
onClick={onClose}
className="text-gray-500 hover:text-gray-700"
aria-label="Close modal"
>
✕
</button>
</div>
{children}
</div>
</div>,
document.body
)
}
// Usage
const App = () => {
const [isOpen, setIsOpen] = useState(false)
return (
<>
<button onClick={() => setIsOpen(true)}>Open Modal</button>
<Modal isOpen={isOpen} onClose={() => setIsOpen(false)} title="My Modal">
<p>Modal content goes here</p>
<button onClick={() => setIsOpen(false)}>Close</button>
</Modal>
</>
)
}
```
## Example 4: Infinite Scroll
```typescript
import { useState, useEffect, useRef, useCallback } from 'react'
interface InfiniteScrollProps<T> {
fetchData: (page: number) => Promise<T[]>
renderItem: (item: T, index: number) => React.ReactNode
loader?: React.ReactNode
endMessage?: React.ReactNode
}
const InfiniteScroll = <T extends { id: string | number },>({
fetchData,
renderItem,
loader = <div>Loading...</div>,
endMessage = <div>No more items</div>
}: InfiniteScrollProps<T>) => {
const [items, setItems] = useState<T[]>([])
const [page, setPage] = useState(1)
const [loading, setLoading] = useState(false)
const [hasMore, setHasMore] = useState(true)
const observerRef = useRef<IntersectionObserver | null>(null)
const loadMoreRef = useRef<HTMLDivElement>(null)
const loadMore = useCallback(async () => {
if (loading || !hasMore) return
setLoading(true)
try {
const newItems = await fetchData(page)
if (newItems.length === 0) {
setHasMore(false)
} else {
setItems(prev => [...prev, ...newItems])
setPage(prev => prev + 1)
}
} catch (error) {
console.error('Failed to load items:', error)
} finally {
setLoading(false)
}
}, [page, loading, hasMore, fetchData])
// Set up intersection observer
useEffect(() => {
observerRef.current = new IntersectionObserver(
entries => {
if (entries[0].isIntersecting) {
loadMore()
}
},
{ threshold: 0.1 }
)
const currentRef = loadMoreRef.current
if (currentRef) {
observerRef.current.observe(currentRef)
}
return () => {
if (observerRef.current && currentRef) {
observerRef.current.unobserve(currentRef)
}
}
}, [loadMore])
// Initial load
useEffect(() => {
loadMore()
}, [])
return (
<div>
{items.map((item, index) => (
<div key={item.id}>
{renderItem(item, index)}
</div>
))}
<div ref={loadMoreRef}>
{loading && loader}
{!loading && !hasMore && endMessage}
</div>
</div>
)
}
// Usage
const PostsList = () => {
const fetchPosts = async (page: number) => {
const response = await fetch(`/api/posts?page=${page}`)
return response.json()
}
return (
<InfiniteScroll<Post>
fetchData={fetchPosts}
renderItem={(post) => <PostCard post={post} />}
/>
)
}
```
## Example 5: Dark Mode Toggle
```typescript
import { createContext, useContext, useState, useEffect } from 'react'
type Theme = 'light' | 'dark'
interface ThemeContextType {
theme: Theme
toggleTheme: () => void
}
const ThemeContext = createContext<ThemeContextType | null>(null)
export const useTheme = () => {
const context = useContext(ThemeContext)
if (!context) {
throw new Error('useTheme must be used within ThemeProvider')
}
return context
}
export const ThemeProvider = ({ children }: { children: React.ReactNode }) => {
const [theme, setTheme] = useState<Theme>(() => {
// Check localStorage and system preference
const saved = localStorage.getItem('theme') as Theme | null
if (saved) return saved
if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
return 'dark'
}
return 'light'
})
useEffect(() => {
// Update DOM and localStorage
const root = document.documentElement
root.classList.remove('light', 'dark')
root.classList.add(theme)
localStorage.setItem('theme', theme)
}, [theme])
const toggleTheme = () => {
setTheme(prev => prev === 'light' ? 'dark' : 'light')
}
return (
<ThemeContext.Provider value={{ theme, toggleTheme }}>
{children}
</ThemeContext.Provider>
)
}
// Usage
const ThemeToggle = () => {
const { theme, toggleTheme } = useTheme()
return (
<button onClick={toggleTheme} aria-label="Toggle theme">
{theme === 'light' ? '🌙' : '☀️'}
</button>
)
}
```
## Example 6: Debounced Search
```typescript
import { useState, useEffect, useMemo } from 'react'
const useDebounce = <T,>(value: T, delay: number): T => {
const [debouncedValue, setDebouncedValue] = useState(value)
useEffect(() => {
const timer = setTimeout(() => {
setDebouncedValue(value)
}, delay)
return () => {
clearTimeout(timer)
}
}, [value, delay])
return debouncedValue
}
const SearchPage = () => {
const [query, setQuery] = useState('')
const [results, setResults] = useState<Product[]>([])
const [loading, setLoading] = useState(false)
const debouncedQuery = useDebounce(query, 500)
useEffect(() => {
if (!debouncedQuery) {
setResults([])
return
}
const searchProducts = async () => {
setLoading(true)
try {
const response = await fetch(`/api/search?q=${debouncedQuery}`)
const data = await response.json()
setResults(data)
} catch (error) {
console.error('Search failed:', error)
} finally {
setLoading(false)
}
}
searchProducts()
}, [debouncedQuery])
return (
<div>
<input
type="search"
value={query}
onChange={e => setQuery(e.target.value)}
placeholder="Search products..."
/>
{loading && <Spinner />}
{!loading && results.length > 0 && (
<div>
{results.map(product => (
<ProductCard key={product.id} product={product} />
))}
</div>
)}
{!loading && query && results.length === 0 && (
<p>No results found for "{query}"</p>
)}
</div>
)
}
```
## Example 7: Tabs Component
```typescript
import { createContext, useContext, useState, useId } from 'react'
interface TabsContextType {
activeTab: string
setActiveTab: (id: string) => void
tabsId: string
}
const TabsContext = createContext<TabsContextType | null>(null)
const useTabs = () => {
const context = useContext(TabsContext)
if (!context) throw new Error('Tabs compound components must be used within Tabs')
return context
}
interface TabsProps {
children: React.ReactNode
defaultValue: string
className?: string
}
const Tabs = ({ children, defaultValue, className }: TabsProps) => {
const [activeTab, setActiveTab] = useState(defaultValue)
const tabsId = useId()
return (
<TabsContext.Provider value={{ activeTab, setActiveTab, tabsId }}>
<div className={className}>
{children}
</div>
</TabsContext.Provider>
)
}
const TabsList = ({ children, className }: {
children: React.ReactNode
className?: string
}) => (
<div role="tablist" className={className}>
{children}
</div>
)
interface TabsTriggerProps {
value: string
children: React.ReactNode
className?: string
}
const TabsTrigger = ({ value, children, className }: TabsTriggerProps) => {
const { activeTab, setActiveTab, tabsId } = useTabs()
const isActive = activeTab === value
return (
<button
role="tab"
id={`${tabsId}-tab-${value}`}
aria-controls={`${tabsId}-panel-${value}`}
aria-selected={isActive}
onClick={() => setActiveTab(value)}
className={`${className} ${isActive ? 'active' : ''}`}
>
{children}
</button>
)
}
interface TabsContentProps {
value: string
children: React.ReactNode
className?: string
}
const TabsContent = ({ value, children, className }: TabsContentProps) => {
const { activeTab, tabsId } = useTabs()
if (activeTab !== value) return null
return (
<div
role="tabpanel"
id={`${tabsId}-panel-${value}`}
aria-labelledby={`${tabsId}-tab-${value}`}
className={className}
>
{children}
</div>
)
}
// Export compound component
export { Tabs, TabsList, TabsTrigger, TabsContent }
// Usage
const App = () => (
<Tabs defaultValue="profile">
<TabsList>
<TabsTrigger value="profile">Profile</TabsTrigger>
<TabsTrigger value="settings">Settings</TabsTrigger>
<TabsTrigger value="notifications">Notifications</TabsTrigger>
</TabsList>
<TabsContent value="profile">
<h2>Profile Content</h2>
</TabsContent>
<TabsContent value="settings">
<h2>Settings Content</h2>
</TabsContent>
<TabsContent value="notifications">
<h2>Notifications Content</h2>
</TabsContent>
</Tabs>
)
```
## Example 8: Error Boundary
```typescript
import { Component, ErrorInfo, ReactNode } from 'react'
interface Props {
children: ReactNode
fallback?: (error: Error, reset: () => void) => ReactNode
onError?: (error: Error, errorInfo: ErrorInfo) => void
}
interface State {
hasError: boolean
error: Error | null
}
class ErrorBoundary extends Component<Props, State> {
constructor(props: Props) {
super(props)
this.state = { hasError: false, error: null }
}
static getDerivedStateFromError(error: Error): State {
return { hasError: true, error }
}
componentDidCatch(error: Error, errorInfo: ErrorInfo) {
console.error('ErrorBoundary caught:', error, errorInfo)
this.props.onError?.(error, errorInfo)
}
reset = () => {
this.setState({ hasError: false, error: null })
}
render() {
if (this.state.hasError && this.state.error) {
if (this.props.fallback) {
return this.props.fallback(this.state.error, this.reset)
}
return (
<div className="error-boundary">
<h2>Something went wrong</h2>
<details>
<summary>Error details</summary>
<pre>{this.state.error.message}</pre>
</details>
<button onClick={this.reset}>Try again</button>
</div>
)
}
return this.props.children
}
}
// Usage
const App = () => (
<ErrorBoundary
fallback={(error, reset) => (
<div>
<h1>Oops! Something went wrong</h1>
<p>{error.message}</p>
<button onClick={reset}>Retry</button>
</div>
)}
onError={(error, errorInfo) => {
// Send to error tracking service
console.error('Error logged:', error, errorInfo)
}}
>
<YourApp />
</ErrorBoundary>
)
```
## Example 9: Custom Hook for Local Storage
```typescript
import { useState, useEffect, useCallback } from 'react'
const useLocalStorage = <T,>(
key: string,
initialValue: T
): [T, (value: T | ((val: T) => T)) => void, () => void] => {
// Get initial value from localStorage
const [storedValue, setStoredValue] = useState<T>(() => {
try {
const item = window.localStorage.getItem(key)
return item ? JSON.parse(item) : initialValue
} catch (error) {
console.error(`Error loading ${key} from localStorage:`, error)
return initialValue
}
})
// Update localStorage when value changes
const setValue = useCallback((value: T | ((val: T) => T)) => {
try {
const valueToStore = value instanceof Function ? value(storedValue) : value
setStoredValue(valueToStore)
window.localStorage.setItem(key, JSON.stringify(valueToStore))
// Dispatch storage event for other tabs
window.dispatchEvent(new Event('storage'))
} catch (error) {
console.error(`Error saving ${key} to localStorage:`, error)
}
}, [key, storedValue])
// Remove from localStorage
const removeValue = useCallback(() => {
try {
window.localStorage.removeItem(key)
setStoredValue(initialValue)
} catch (error) {
console.error(`Error removing ${key} from localStorage:`, error)
}
}, [key, initialValue])
// Listen for changes in other tabs
useEffect(() => {
const handleStorageChange = (e: StorageEvent) => {
if (e.key === key && e.newValue) {
setStoredValue(JSON.parse(e.newValue))
}
}
window.addEventListener('storage', handleStorageChange)
return () => window.removeEventListener('storage', handleStorageChange)
}, [key])
return [storedValue, setValue, removeValue]
}
// Usage
const UserPreferences = () => {
const [preferences, setPreferences, clearPreferences] = useLocalStorage('user-prefs', {
theme: 'light',
language: 'en',
notifications: true
})
return (
<div>
<label>
<input
type="checkbox"
checked={preferences.notifications}
onChange={e => setPreferences({
...preferences,
notifications: e.target.checked
})}
/>
Enable notifications
</label>
<button onClick={clearPreferences}>
Reset to defaults
</button>
</div>
)
}
```
## Example 10: Optimistic Updates with useOptimistic
```typescript
'use client'
import { useOptimistic } from 'react'
import { likePost, unlikePost } from './actions'
interface Post {
id: string
content: string
likes: number
isLiked: boolean
}
const PostCard = ({ post }: { post: Post }) => {
const [optimisticPost, addOptimistic] = useOptimistic(
post,
(currentPost, update: Partial<Post>) => ({
...currentPost,
...update
})
)
const handleLike = async () => {
// Optimistically update UI
addOptimistic({
likes: optimisticPost.likes + 1,
isLiked: true
})
try {
// Send server request
await likePost(post.id)
} catch (error) {
// Server will send correct state via revalidation
console.error('Failed to like post:', error)
}
}
const handleUnlike = async () => {
addOptimistic({
likes: optimisticPost.likes - 1,
isLiked: false
})
try {
await unlikePost(post.id)
} catch (error) {
console.error('Failed to unlike post:', error)
}
}
return (
<div className="post-card">
<p>{optimisticPost.content}</p>
<button
onClick={optimisticPost.isLiked ? handleUnlike : handleLike}
className={optimisticPost.isLiked ? 'liked' : ''}
>
❤️ {optimisticPost.likes}
</button>
</div>
)
}
```
## References
These examples demonstrate:
- Custom hooks for reusable logic
- Form handling with validation
- Portal usage for modals
- Infinite scroll with Intersection Observer
- Context for global state
- Debouncing for performance
- Compound components pattern
- Error boundaries
- LocalStorage integration
- Optimistic updates (React 19)

291
.claude/skills/react/references/hooks-quick-reference.md Normal file
View File

@@ -0,0 +1,291 @@
# React Hooks Quick Reference
## State Hooks
### useState
```typescript
const [state, setState] = useState<Type>(initialValue)
const [count, setCount] = useState(0)
// Functional update
setCount(prev => prev + 1)
// Lazy initialization
const [state, setState] = useState(() => expensiveComputation())
```
### useReducer
```typescript
type State = { count: number }
type Action = { type: 'increment' } | { type: 'decrement' }
const reducer = (state: State, action: Action): State => {
switch (action.type) {
case 'increment': return { count: state.count + 1 }
case 'decrement': return { count: state.count - 1 }
}
}
const [state, dispatch] = useReducer(reducer, { count: 0 })
dispatch({ type: 'increment' })
```
### useActionState (React 19)
```typescript
const [state, formAction, isPending] = useActionState(
async (previousState, formData: FormData) => {
// Server action
return await processForm(formData)
},
initialState
)
<form action={formAction}>
<button disabled={isPending}>Submit</button>
</form>
```
## Effect Hooks
### useEffect
```typescript
useEffect(() => {
// Side effect
const subscription = api.subscribe()
// Cleanup
return () => subscription.unsubscribe()
}, [dependencies])
```
**Timing**: After render & paint
**Use for**: Data fetching, subscriptions, DOM mutations
### useLayoutEffect
```typescript
useLayoutEffect(() => {
// Runs before paint
const height = ref.current.offsetHeight
setHeight(height)
}, [])
```
**Timing**: After render, before paint
**Use for**: DOM measurements, preventing flicker
### useInsertionEffect
```typescript
useInsertionEffect(() => {
// Insert styles before any DOM reads
const style = document.createElement('style')
style.textContent = css
document.head.appendChild(style)
return () => document.head.removeChild(style)
}, [css])
```
**Timing**: Before any DOM mutations
**Use for**: CSS-in-JS libraries
## Performance Hooks
### useMemo
```typescript
const memoizedValue = useMemo(() => {
return expensiveComputation(a, b)
}, [a, b])
```
**Use for**: Expensive calculations, stable object references
### useCallback
```typescript
const memoizedCallback = useCallback(() => {
doSomething(a, b)
}, [a, b])
```
**Use for**: Passing callbacks to optimized components
## Ref Hooks
### useRef
```typescript
// DOM reference
const ref = useRef<HTMLDivElement>(null)
ref.current?.focus()
// Mutable value (doesn't trigger re-render)
const countRef = useRef(0)
countRef.current += 1
```
### useImperativeHandle
```typescript
useImperativeHandle(ref, () => ({
focus: () => inputRef.current?.focus(),
clear: () => inputRef.current && (inputRef.current.value = '')
}), [])
```
## Context Hook
### useContext
```typescript
const value = useContext(MyContext)
```
Must be used within a Provider.
## Transition Hooks
### useTransition
```typescript
const [isPending, startTransition] = useTransition()
startTransition(() => {
setState(newValue) // Non-urgent update
})
```
### useDeferredValue
```typescript
const [input, setInput] = useState('')
const deferredInput = useDeferredValue(input)
// Use deferredInput for expensive operations
const results = useMemo(() => search(deferredInput), [deferredInput])
```
## Optimistic Updates (React 19)
### useOptimistic
```typescript
const [optimisticState, addOptimistic] = useOptimistic(
actualState,
(currentState, optimisticValue) => {
return [...currentState, optimisticValue]
}
)
```
## Other Hooks
### useId
```typescript
const id = useId()
<label htmlFor={id}>Name</label>
<input id={id} />
```
### useSyncExternalStore
```typescript
const state = useSyncExternalStore(
subscribe,
getSnapshot,
getServerSnapshot
)
```
### useDebugValue
```typescript
useDebugValue(isOnline ? 'Online' : 'Offline')
```
### use (React 19)
```typescript
// Read context or promise
const value = use(MyContext)
const data = use(fetchPromise) // Must be in Suspense
```
## Form Hooks (React DOM)
### useFormStatus
```typescript
import { useFormStatus } from 'react-dom'
const { pending, data, method, action } = useFormStatus()
```
## Hook Rules
1. **Only call at top level** - Not in loops, conditions, or nested functions
2. **Only call from React functions** - Components or custom hooks
3. **Custom hooks start with "use"** - Naming convention
4. **Same hooks in same order** - Every render must call same hooks
## Dependencies Best Practices
1. **Include all used values** - Variables, props, state from component scope
2. **Use ESLint plugin** - `eslint-plugin-react-hooks` enforces rules
3. **Functions as dependencies** - Wrap with useCallback or define outside component
4. **Object/array dependencies** - Use useMemo for stable references
## Common Patterns
### Fetching Data
```typescript
const [data, setData] = useState(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState(null)
useEffect(() => {
const controller = new AbortController()
fetch('/api/data', { signal: controller.signal })
.then(res => res.json())
.then(setData)
.catch(setError)
.finally(() => setLoading(false))
return () => controller.abort()
}, [])
```
### Debouncing
```typescript
const [value, setValue] = useState('')
const [debouncedValue, setDebouncedValue] = useState(value)
useEffect(() => {
const timer = setTimeout(() => {
setDebouncedValue(value)
}, 500)
return () => clearTimeout(timer)
}, [value])
```
### Previous Value
```typescript
const usePrevious = <T,>(value: T): T | undefined => {
const ref = useRef<T>()
useEffect(() => {
ref.current = value
})
return ref.current
}
```
### Interval
```typescript
useEffect(() => {
const id = setInterval(() => {
setCount(c => c + 1)
}, 1000)
return () => clearInterval(id)
}, [])
```
### Event Listeners
```typescript
useEffect(() => {
const handleResize = () => setWidth(window.innerWidth)
window.addEventListener('resize', handleResize)
return () => window.removeEventListener('resize', handleResize)
}, [])
```

658
.claude/skills/react/references/performance.md Normal file
View File

@@ -0,0 +1,658 @@
# React Performance Optimization Guide
## Overview
This guide covers performance optimization strategies for React 19 applications.
## Measurement & Profiling
### React DevTools Profiler
Record performance data:
1. Open React DevTools
2. Go to Profiler tab
3. Click record button
4. Interact with app
5. Stop recording
6. Analyze flame graph and ranked chart
### Profiler Component
```typescript
import { Profiler } from 'react'
const App = () => {
const onRender = (
id: string,
phase: 'mount' | 'update',
actualDuration: number,
baseDuration: number,
startTime: number,
commitTime: number
) => {
console.log({
component: id,
phase,
actualDuration, // Time spent rendering this update
baseDuration // Estimated time without memoization
})
}
return (
<Profiler id="App" onRender={onRender}>
<YourApp />
</Profiler>
)
}
```
### Performance Metrics
```typescript
// Custom performance tracking
const startTime = performance.now()
// ... do work
const endTime = performance.now()
console.log(`Operation took ${endTime - startTime}ms`)
// React rendering metrics
import { unstable_trace as trace } from 'react'
trace('expensive-operation', async () => {
await performExpensiveOperation()
})
```
## Memoization Strategies
### React.memo
Prevent unnecessary re-renders:
```typescript
// Basic memoization
const ExpensiveComponent = memo(({ data }: Props) => {
return <div>{processData(data)}</div>
})
// Custom comparison
const MemoizedComponent = memo(
({ user }: Props) => <UserCard user={user} />,
(prevProps, nextProps) => {
// Return true if props are equal (skip render)
return prevProps.user.id === nextProps.user.id
}
)
```
**When to use:**
- Component renders often with same props
- Rendering is expensive
- Component receives complex prop objects
**When NOT to use:**
- Props change frequently
- Component is already fast
- Premature optimization
### useMemo
Memoize computed values:
```typescript
const SortedList = ({ items, filter }: Props) => {
// Without memoization - runs every render
const filteredItems = items.filter(item => item.type === filter)
const sortedItems = filteredItems.sort((a, b) => a.name.localeCompare(b.name))
// With memoization - only runs when dependencies change
const sortedFilteredItems = useMemo(() => {
const filtered = items.filter(item => item.type === filter)
return filtered.sort((a, b) => a.name.localeCompare(b.name))
}, [items, filter])
return (
<ul>
{sortedFilteredItems.map(item => (
<li key={item.id}>{item.name}</li>
))}
</ul>
)
}
```
**When to use:**
- Expensive calculations (sorting, filtering large arrays)
- Creating stable object references
- Computed values used as dependencies
### useCallback
Memoize callback functions:
```typescript
const Parent = () => {
const [count, setCount] = useState(0)
// Without useCallback - new function every render
const handleClick = () => {
setCount(c => c + 1)
}
// With useCallback - stable function reference
const handleClickMemo = useCallback(() => {
setCount(c => c + 1)
}, [])
return <MemoizedChild onClick={handleClickMemo} />
}
const MemoizedChild = memo(({ onClick }: Props) => {
return <button onClick={onClick}>Click</button>
})
```
**When to use:**
- Passing callbacks to memoized components
- Callback is used in dependency array
- Callback is expensive to create
## React Compiler (Automatic Optimization)
### Enable React Compiler
React 19 can automatically optimize without manual memoization:
```javascript
// babel.config.js
module.exports = {
plugins: [
['react-compiler', {
compilationMode: 'all', // Optimize all components
}]
]
}
```
### Compilation Modes
```javascript
{
compilationMode: 'annotation', // Only components with "use memo"
compilationMode: 'all', // All components (recommended)
compilationMode: 'infer' // Based on component complexity
}
```
### Directives
```typescript
// Force memoization
'use memo'
const Component = ({ data }: Props) => {
return <div>{data}</div>
}
// Prevent memoization
'use no memo'
const SimpleComponent = ({ text }: Props) => {
return <span>{text}</span>
}
```
## State Management Optimization
### State Colocation
Keep state as close as possible to where it's used:
```typescript
// Bad - state too high
const App = () => {
const [showModal, setShowModal] = useState(false)
return (
<>
<Header />
<Content />
<Modal show={showModal} onClose={() => setShowModal(false)} />
</>
)
}
// Good - state colocated
const App = () => {
return (
<>
<Header />
<Content />
<ModalContainer />
</>
)
}
const ModalContainer = () => {
const [showModal, setShowModal] = useState(false)
return <Modal show={showModal} onClose={() => setShowModal(false)} />
}
```
### Split Context
Avoid unnecessary re-renders by splitting context:
```typescript
// Bad - single context causes all consumers to re-render
const AppContext = createContext({ user, theme, settings })
// Good - split into separate contexts
const UserContext = createContext(user)
const ThemeContext = createContext(theme)
const SettingsContext = createContext(settings)
```
### Context with useMemo
```typescript
const ThemeProvider = ({ children }: Props) => {
const [theme, setTheme] = useState('light')
// Memoize context value to prevent unnecessary re-renders
const value = useMemo(() => ({
theme,
setTheme
}), [theme])
return (
<ThemeContext.Provider value={value}>
{children}
</ThemeContext.Provider>
)
}
```
## Code Splitting & Lazy Loading
### React.lazy
Split components into separate bundles:
```typescript
import { lazy, Suspense } from 'react'
// Lazy load components
const Dashboard = lazy(() => import('./Dashboard'))
const Settings = lazy(() => import('./Settings'))
const Profile = lazy(() => import('./Profile'))
const App = () => {
return (
<Suspense fallback={<Loading />}>
<Routes>
<Route path="/dashboard" element={<Dashboard />} />
<Route path="/settings" element={<Settings />} />
<Route path="/profile" element={<Profile />} />
</Routes>
</Suspense>
)
}
```
### Route-based Splitting
```typescript
// App.tsx
const routes = [
{ path: '/', component: lazy(() => import('./pages/Home')) },
{ path: '/about', component: lazy(() => import('./pages/About')) },
{ path: '/products', component: lazy(() => import('./pages/Products')) },
]
const App = () => (
<Suspense fallback={<PageLoader />}>
<Routes>
{routes.map(({ path, component: Component }) => (
<Route key={path} path={path} element={<Component />} />
))}
</Routes>
</Suspense>
)
```
### Component-based Splitting
```typescript
// Split expensive components
const HeavyChart = lazy(() => import('./HeavyChart'))
const Dashboard = () => {
const [showChart, setShowChart] = useState(false)
return (
<>
<button onClick={() => setShowChart(true)}>
Load Chart
</button>
{showChart && (
<Suspense fallback={<ChartSkeleton />}>
<HeavyChart />
</Suspense>
)}
</>
)
}
```
## List Rendering Optimization
### Keys
Always use stable, unique keys:
```typescript
// Bad - index as key (causes issues on reorder/insert)
{items.map((item, index) => (
<Item key={index} data={item} />
))}
// Good - unique ID as key
{items.map(item => (
<Item key={item.id} data={item} />
))}
// For static lists without IDs
{items.map(item => (
<Item key={`${item.name}-${item.category}`} data={item} />
))}
```
### Virtualization
For long lists, render only visible items:
```typescript
import { useVirtualizer } from '@tanstack/react-virtual'
const VirtualList = ({ items }: { items: Item[] }) => {
const parentRef = useRef<HTMLDivElement>(null)
const virtualizer = useVirtualizer({
count: items.length,
getScrollElement: () => parentRef.current,
estimateSize: () => 50, // Estimated item height
overscan: 5 // Render 5 extra items above/below viewport
})
return (
<div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
<div
style={{
height: `${virtualizer.getTotalSize()}px`,
position: 'relative'
}}
>
{virtualizer.getVirtualItems().map(virtualItem => (
<div
key={virtualItem.key}
style={{
position: 'absolute',
top: 0,
left: 0,
width: '100%',
height: `${virtualItem.size}px`,
transform: `translateY(${virtualItem.start}px)`
}}
>
<Item data={items[virtualItem.index]} />
</div>
))}
</div>
</div>
)
}
```
### Pagination
```typescript
const PaginatedList = ({ items }: Props) => {
const [page, setPage] = useState(1)
const itemsPerPage = 20
const paginatedItems = useMemo(() => {
const start = (page - 1) * itemsPerPage
const end = start + itemsPerPage
return items.slice(start, end)
}, [items, page, itemsPerPage])
return (
<>
{paginatedItems.map(item => (
<Item key={item.id} data={item} />
))}
<Pagination
page={page}
total={Math.ceil(items.length / itemsPerPage)}
onChange={setPage}
/>
</>
)
}
```
## Transitions & Concurrent Features
### useTransition
Keep UI responsive during expensive updates:
```typescript
const SearchPage = () => {
const [query, setQuery] = useState('')
const [results, setResults] = useState([])
const [isPending, startTransition] = useTransition()
const handleSearch = (value: string) => {
setQuery(value) // Urgent - update input immediately
// Non-urgent - can be interrupted
startTransition(() => {
const filtered = expensiveFilter(items, value)
setResults(filtered)
})
}
return (
<>
<input value={query} onChange={e => handleSearch(e.target.value)} />
{isPending && <Spinner />}
<ResultsList results={results} />
</>
)
}
```
### useDeferredValue
Defer non-urgent renders:
```typescript
const SearchPage = () => {
const [query, setQuery] = useState('')
const deferredQuery = useDeferredValue(query)
// Input updates immediately
// Results update with deferred value (can be interrupted)
const results = useMemo(() => {
return expensiveFilter(items, deferredQuery)
}, [deferredQuery])
return (
<>
<input value={query} onChange={e => setQuery(e.target.value)} />
<ResultsList results={results} />
</>
)
}
```
## Image & Asset Optimization
### Lazy Load Images
```typescript
const LazyImage = ({ src, alt }: Props) => {
const [isLoaded, setIsLoaded] = useState(false)
return (
<div className="relative">
{!isLoaded && <ImageSkeleton />}
<img
src={src}
alt={alt}
loading="lazy" // Native lazy loading
onLoad={() => setIsLoaded(true)}
className={isLoaded ? 'opacity-100' : 'opacity-0'}
/>
</div>
)
}
```
### Next.js Image Component
```typescript
import Image from 'next/image'
const OptimizedImage = () => (
<Image
src="/hero.jpg"
alt="Hero"
width={800}
height={600}
priority // Load immediately for above-fold images
placeholder="blur"
blurDataURL="data:image/jpeg;base64,..."
/>
)
```
## Bundle Size Optimization
### Tree Shaking
Import only what you need:
```typescript
// Bad - imports entire library
import _ from 'lodash'
// Good - import only needed functions
import debounce from 'lodash/debounce'
import throttle from 'lodash/throttle'
// Even better - use native methods when possible
const debounce = (fn, delay) => {
let timeoutId
return (...args) => {
clearTimeout(timeoutId)
timeoutId = setTimeout(() => fn(...args), delay)
}
}
```
### Analyze Bundle
```bash
# Next.js
ANALYZE=true npm run build
# Create React App
npm install --save-dev webpack-bundle-analyzer
```
### Dynamic Imports
```typescript
// Load library only when needed
const handleExport = async () => {
const { jsPDF } = await import('jspdf')
const doc = new jsPDF()
doc.save('report.pdf')
}
```
## Common Performance Pitfalls
### 1. Inline Object Creation
```typescript
// Bad - new object every render
<Component style={{ margin: 10 }} />
// Good - stable reference
const style = { margin: 10 }
<Component style={style} />
// Or use useMemo
const style = useMemo(() => ({ margin: 10 }), [])
```
### 2. Inline Functions
```typescript
// Bad - new function every render (if child is memoized)
<MemoizedChild onClick={() => handleClick(id)} />
// Good
const handleClickMemo = useCallback(() => handleClick(id), [id])
<MemoizedChild onClick={handleClickMemo} />
```
### 3. Spreading Props
```typescript
// Bad - causes re-renders even when props unchanged
<Component {...props} />
// Good - pass only needed props
<Component value={props.value} onChange={props.onChange} />
```
### 4. Large Context
```typescript
// Bad - everything re-renders on any state change
const AppContext = createContext({ user, theme, cart, settings, ... })
// Good - split into focused contexts
const UserContext = createContext(user)
const ThemeContext = createContext(theme)
const CartContext = createContext(cart)
```
## Performance Checklist
- [ ] Measure before optimizing (use Profiler)
- [ ] Use React DevTools to identify slow components
- [ ] Implement code splitting for large routes
- [ ] Lazy load below-the-fold content
- [ ] Virtualize long lists
- [ ] Memoize expensive calculations
- [ ] Split large contexts
- [ ] Colocate state close to usage
- [ ] Use transitions for non-urgent updates
- [ ] Optimize images and assets
- [ ] Analyze and minimize bundle size
- [ ] Remove console.logs in production
- [ ] Use production build for testing
- [ ] Monitor real-world performance metrics
## References
- React Performance: https://react.dev/learn/render-and-commit
- React Profiler: https://react.dev/reference/react/Profiler
- React Compiler: https://react.dev/reference/react-compiler
- Web Vitals: https://web.dev/vitals/

656
.claude/skills/react/references/server-components.md Normal file
View File

@@ -0,0 +1,656 @@
# React Server Components & Server Functions
## Overview
React Server Components (RSC) allow components to render on the server, improving performance and enabling direct data access. Server Functions allow client components to call server-side functions.
## Server Components
### What are Server Components?
Components that run **only on the server**:
- Can access databases directly
- Zero bundle size (code stays on server)
- Better performance (less JavaScript to client)
- Automatic code splitting
### Creating Server Components
```typescript
// app/products/page.tsx
// Server Component by default in App Router
import { db } from '@/lib/db'
const ProductsPage = async () => {
// Direct database access
const products = await db.product.findMany({
where: { active: true },
include: { category: true }
})
return (
<div>
<h1>Products</h1>
{products.map(product => (
<ProductCard key={product.id} product={product} />
))}
</div>
)
}
export default ProductsPage
```
### Server Component Rules
**Can do:**
- Access databases and APIs directly
- Use server-only modules (fs, path, etc.)
- Keep secrets secure (API keys, tokens)
- Reduce client bundle size
- Use async/await at top level
**Cannot do:**
- Use hooks (useState, useEffect, etc.)
- Use browser APIs (window, document)
- Attach event handlers (onClick, etc.)
- Use Context
### Mixing Server and Client Components
```typescript
// Server Component (default)
const Page = async () => {
const data = await fetchData()
return (
<div>
<ServerComponent data={data} />
{/* Client component for interactivity */}
<ClientComponent initialData={data} />
</div>
)
}
// Client Component
'use client'
import { useState } from 'react'
const ClientComponent = ({ initialData }) => {
const [count, setCount] = useState(0)
return (
<button onClick={() => setCount(c => c + 1)}>
{count}
</button>
)
}
```
### Server Component Patterns
#### Data Fetching
```typescript
// app/user/[id]/page.tsx
interface PageProps {
params: { id: string }
}
const UserPage = async ({ params }: PageProps) => {
const user = await db.user.findUnique({
where: { id: params.id }
})
if (!user) {
notFound() // Next.js 404
}
return <UserProfile user={user} />
}
```
#### Parallel Data Fetching
```typescript
const DashboardPage = async () => {
// Fetch in parallel
const [user, orders, stats] = await Promise.all([
fetchUser(),
fetchOrders(),
fetchStats()
])
return (
<>
<UserHeader user={user} />
<OrdersList orders={orders} />
<StatsWidget stats={stats} />
</>
)
}
```
#### Streaming with Suspense
```typescript
const Page = () => {
return (
<>
<Header />
<Suspense fallback={<ProductsSkeleton />}>
<Products />
</Suspense>
<Suspense fallback={<ReviewsSkeleton />}>
<Reviews />
</Suspense>
</>
)
}
const Products = async () => {
const products = await fetchProducts() // Slow query
return <ProductsList products={products} />
}
```
## Server Functions (Server Actions)
### What are Server Functions?
Functions that run on the server but can be called from client components:
- Marked with `'use server'` directive
- Can mutate data
- Integrated with forms
- Type-safe with TypeScript
### Creating Server Functions
#### File-level directive
```typescript
// app/actions.ts
'use server'
import { db } from '@/lib/db'
import { revalidatePath } from 'next/cache'
export async function createProduct(formData: FormData) {
const name = formData.get('name') as string
const price = Number(formData.get('price'))
const product = await db.product.create({
data: { name, price }
})
revalidatePath('/products')
return product
}
export async function deleteProduct(id: string) {
await db.product.delete({ where: { id } })
revalidatePath('/products')
}
```
#### Function-level directive
```typescript
// Inside a Server Component
const MyComponent = async () => {
async function handleSubmit(formData: FormData) {
'use server'
const email = formData.get('email') as string
await saveEmail(email)
}
return <form action={handleSubmit}>...</form>
}
```
### Using Server Functions
#### With Forms
```typescript
'use client'
import { createProduct } from './actions'
const ProductForm = () => {
return (
<form action={createProduct}>
<input name="name" required />
<input name="price" type="number" required />
<button type="submit">Create</button>
</form>
)
}
```
#### With useActionState
```typescript
'use client'
import { useActionState } from 'react'
import { createProduct } from './actions'
type FormState = {
message: string
success: boolean
} | null
const ProductForm = () => {
const [state, formAction, isPending] = useActionState<FormState>(
async (previousState, formData: FormData) => {
try {
await createProduct(formData)
return { message: 'Product created!', success: true }
} catch (error) {
return { message: 'Failed to create product', success: false }
}
},
null
)
return (
<form action={formAction}>
<input name="name" required />
<input name="price" type="number" required />
<button disabled={isPending}>
{isPending ? 'Creating...' : 'Create'}
</button>
{state?.message && (
<p className={state.success ? 'text-green-600' : 'text-red-600'}>
{state.message}
</p>
)}
</form>
)
}
```
#### Programmatic Invocation
```typescript
'use client'
import { deleteProduct } from './actions'
const DeleteButton = ({ productId }: { productId: string }) => {
const [isPending, setIsPending] = useState(false)
const handleDelete = async () => {
setIsPending(true)
try {
await deleteProduct(productId)
} catch (error) {
console.error(error)
} finally {
setIsPending(false)
}
}
return (
<button onClick={handleDelete} disabled={isPending}>
{isPending ? 'Deleting...' : 'Delete'}
</button>
)
}
```
### Server Function Patterns
#### Validation with Zod
```typescript
'use server'
import { z } from 'zod'
const ProductSchema = z.object({
name: z.string().min(3),
price: z.number().positive(),
description: z.string().optional()
})
export async function createProduct(formData: FormData) {
const rawData = {
name: formData.get('name'),
price: Number(formData.get('price')),
description: formData.get('description')
}
// Validate
const result = ProductSchema.safeParse(rawData)
if (!result.success) {
return {
success: false,
errors: result.error.flatten().fieldErrors
}
}
// Create product
const product = await db.product.create({
data: result.data
})
revalidatePath('/products')
return { success: true, product }
}
```
#### Authentication Check
```typescript
'use server'
import { auth } from '@/lib/auth'
import { redirect } from 'next/navigation'
export async function createOrder(formData: FormData) {
const session = await auth()
if (!session?.user) {
redirect('/login')
}
const order = await db.order.create({
data: {
userId: session.user.id,
// ... other fields
}
})
return order
}
```
#### Error Handling
```typescript
'use server'
export async function updateProfile(formData: FormData) {
try {
const userId = await getCurrentUserId()
const profile = await db.user.update({
where: { id: userId },
data: {
name: formData.get('name') as string,
bio: formData.get('bio') as string
}
})
revalidatePath('/profile')
return { success: true, profile }
} catch (error) {
console.error('Failed to update profile:', error)
return {
success: false,
error: 'Failed to update profile. Please try again.'
}
}
}
```
#### Optimistic Updates
```typescript
'use client'
import { useOptimistic } from 'react'
import { likePost } from './actions'
const Post = ({ post }: { post: Post }) => {
const [optimisticLikes, addOptimisticLike] = useOptimistic(
post.likes,
(currentLikes) => currentLikes + 1
)
const handleLike = async () => {
addOptimisticLike(null)
await likePost(post.id)
}
return (
<div>
<p>{post.content}</p>
<button onClick={handleLike}>
❤️ {optimisticLikes}
</button>
</div>
)
}
```
## Data Mutations & Revalidation
### revalidatePath
Invalidate cached data for a path:
```typescript
'use server'
import { revalidatePath } from 'next/cache'
export async function createPost(formData: FormData) {
await db.post.create({ data: {...} })
// Revalidate the posts page
revalidatePath('/posts')
// Revalidate with layout
revalidatePath('/posts', 'layout')
}
```
### revalidateTag
Invalidate cached data by tag:
```typescript
'use server'
import { revalidateTag } from 'next/cache'
export async function updateProduct(id: string, data: ProductData) {
await db.product.update({ where: { id }, data })
// Revalidate all queries tagged with 'products'
revalidateTag('products')
}
```
### redirect
Redirect after mutation:
```typescript
'use server'
import { redirect } from 'next/navigation'
export async function createPost(formData: FormData) {
const post = await db.post.create({ data: {...} })
// Redirect to the new post
redirect(`/posts/${post.id}`)
}
```
## Caching with Server Components
### cache Function
Deduplicate requests within a render:
```typescript
import { cache } from 'react'
export const getUser = cache(async (id: string) => {
return await db.user.findUnique({ where: { id } })
})
// Called multiple times but only fetches once per render
const Page = async () => {
const user1 = await getUser('123')
const user2 = await getUser('123') // Uses cached result
return <div>...</div>
}
```
### Next.js fetch Caching
```typescript
// Cached by default
const data = await fetch('https://api.example.com/data')
// Revalidate every 60 seconds
const data = await fetch('https://api.example.com/data', {
next: { revalidate: 60 }
})
// Never cache
const data = await fetch('https://api.example.com/data', {
cache: 'no-store'
})
// Tag for revalidation
const data = await fetch('https://api.example.com/data', {
next: { tags: ['products'] }
})
```
## Best Practices
### 1. Component Placement
- Keep interactive components client-side
- Use server components for data fetching
- Place 'use client' as deep as possible in tree
### 2. Data Fetching
- Fetch in parallel when possible
- Use Suspense for streaming
- Cache expensive operations
### 3. Server Functions
- Validate all inputs
- Check authentication/authorization
- Handle errors gracefully
- Return serializable data only
### 4. Performance
- Minimize client JavaScript
- Use streaming for slow queries
- Implement proper caching
- Optimize database queries
### 5. Security
- Never expose secrets to client
- Validate server function inputs
- Use environment variables
- Implement rate limiting
## Common Patterns
### Layout with Dynamic Data
```typescript
// app/layout.tsx
const RootLayout = async ({ children }: { children: React.ReactNode }) => {
const user = await getCurrentUser()
return (
<html>
<body>
<Header user={user} />
{children}
<Footer />
</body>
</html>
)
}
```
### Loading States
```typescript
// app/products/loading.tsx
export default function Loading() {
return <ProductsSkeleton />
}
// app/products/page.tsx
const ProductsPage = async () => {
const products = await fetchProducts()
return <ProductsList products={products} />
}
```
### Error Boundaries
```typescript
// app/products/error.tsx
'use client'
export default function Error({
error,
reset
}: {
error: Error
reset: () => void
}) {
return (
<div>
<h2>Something went wrong!</h2>
<p>{error.message}</p>
<button onClick={reset}>Try again</button>
</div>
)
}
```
### Search with Server Functions
```typescript
'use client'
import { searchProducts } from './actions'
import { useDeferredValue, useState, useEffect } from 'react'
const SearchPage = () => {
const [query, setQuery] = useState('')
const [results, setResults] = useState([])
const deferredQuery = useDeferredValue(query)
useEffect(() => {
if (deferredQuery) {
searchProducts(deferredQuery).then(setResults)
}
}, [deferredQuery])
return (
<>
<input
value={query}
onChange={e => setQuery(e.target.value)}
/>
<ResultsList results={results} />
</>
)
}
```
## Troubleshooting
### Common Issues
1. **"Cannot use hooks in Server Component"**
- Add 'use client' directive
- Move state logic to client component
2. **"Functions cannot be passed to Client Components"**
- Use Server Functions instead
- Pass data, not functions
3. **Hydration mismatches**
- Ensure server and client render same HTML
- Use useEffect for browser-only code
4. **Slow initial load**
- Implement Suspense boundaries
- Use streaming rendering
- Optimize database queries
## References
- React Server Components: https://react.dev/reference/rsc/server-components
- Server Functions: https://react.dev/reference/rsc/server-functions
- Next.js App Router: https://nextjs.org/docs/app

86
CLAUDE.md Normal file
View File

@@ -0,0 +1,86 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Grimoire is a Nostr protocol explorer and developer tool. It's a tiling window manager interface where each window is a Nostr "app" (profile viewer, event feed, NIP documentation, etc.). Commands are launched Unix-style via Cmd+K palette.
**Stack**: React 19 + TypeScript + Vite + TailwindCSS + Jotai + Dexie + Applesauce
## Core Architecture
### Dual State System
**UI State** (`src/core/state.ts` + `src/core/logic.ts`):
- Jotai atom persisted to localStorage
- Pure functions for all mutations: `(state, payload) => newState`
- Manages workspaces, windows, layout tree, active account
**Nostr State** (`src/services/event-store.ts`):
- Singleton `EventStore` from applesauce-core
- Single source of truth for all Nostr events
- Reactive: components subscribe via hooks, auto-update on new events
- Handles replaceable events automatically (profiles, contact lists, etc.)
**Critical**: Don't create new EventStore or RelayPool instances - use the singletons in `src/services/`
### Window System
Windows are rendered in a recursive binary split layout (via `react-mosaic-component`):
- Each window has: `id` (UUID), `appId` (type identifier), `title`, `props`
- Layout is a tree: leaf nodes are window IDs, branch nodes split space
- **Never manipulate layout tree directly** - use callbacks from mosaic
Workspaces are virtual desktops, each with its own layout tree.
### Command System
`src/types/man.ts` defines all commands as Unix man pages:
- Each command has an `appId` (which app to open) and `argParser` (CLI → props)
- Parsers can be async (e.g., resolving NIP-05 addresses)
- Command pattern: user types `profile alice@example.com` → parser resolves → opens ProfileViewer with props
### Reactive Nostr Pattern
Applesauce uses RxJS observables for reactive data flow:
1. Events arrive from relays → added to EventStore
2. Queries/hooks subscribe to EventStore observables
3. Components re-render automatically when events update
4. Replaceable events (kind 0, 3, 10000-19999, 30000-39999) auto-replace older versions
Use hooks like `useProfile()`, `useNostrEvent()`, `useTimeline()` - they handle subscriptions.
## Key Conventions
- **Path Alias**: `@/` = `./src/`
- **Styling**: Tailwind + HSL CSS variables (theme tokens defined in `index.css`)
- **Types**: Prefer types from `applesauce-core`, extend in `src/types/` when needed
- **File Organization**: By domain (`nostr/`, `ui/`, `services/`, `hooks/`, `lib/`)
- **State Logic**: All UI state mutations go through `src/core/logic.ts` pure functions
## Important Patterns
**Adding New Commands**:
1. Add entry to `manPages` in `src/types/man.ts`
2. Create parser in `src/lib/*-parser.ts` if argument parsing needed
3. Create viewer component for the `appId`
4. Wire viewer into window rendering (`WindowTitle.tsx`)
**Working with Nostr Data**:
- Event data comes from singleton EventStore (reactive)
- Metadata cached in Dexie (`src/services/db.ts`) for offline access
- Active account stored in Jotai state, synced via `useAccountSync` hook
- Use inbox/outbox relay pattern for user relay lists
**Mosaic Layout**:
- Layout mutations via `updateLayout()` callback only
- Don't traverse or modify layout tree manually
- Adding/removing windows handled by `logic.ts` functions
## Critical Notes
- React 19 features in use (ensure compatibility)
- LocalStorage persistence has quota handling built-in
- Dark mode is default (controlled via HTML class)
- EventStore handles event deduplication and replaceability automatically