mirror of
https://github.com/purrgrammer/grimoire.git
synced 2026-04-08 14:37:04 +02:00
refactor: cleanup skills
This commit is contained in:
Alejandro Gómez
@@ -81,7 +81,49 @@ Read the current file, then apply changes carefully.
|
||||
- Every NIP in `VALID_NIPS` should have a corresponding entry in `NIP_METADATA` (`src/lib/nip-icons.ts`)
|
||||
- Flag and fix any inconsistencies
|
||||
|
||||
## Step 6: Verify
|
||||
## Step 6: Update the Nostr skill
|
||||
|
||||
Using the upstream data fetched in Step 1, update the Nostr protocol skill files in `.claude/skills/nostr/`.
|
||||
|
||||
### Update `references/event-kinds.md`
|
||||
|
||||
Regenerate this file from the upstream Event Kinds table. For each kind:
|
||||
- Kind number, name, NIP reference
|
||||
- Replaceability behavior (based on kind range)
|
||||
- Brief description of purpose and key tags
|
||||
|
||||
Preserve the existing document structure:
|
||||
- Section grouping: Core Events (0-999), Regular (1000-9999), Replaceable (10000-19999), Ephemeral (20000-29999), Parameterized Replaceable (30000-39999)
|
||||
- The "Event Kind Ranges Summary" table
|
||||
- The "Common Patterns" section with JSON examples for frequently-used kinds (kinds 0, 1, 7, 10002, 30023)
|
||||
- The "Event Kind Selection Guide" section
|
||||
|
||||
### Update `references/nips-overview.md`
|
||||
|
||||
Update NIP entries to match upstream:
|
||||
- Add new NIPs with a brief description of purpose and key details
|
||||
- Update titles/descriptions that changed upstream
|
||||
- Mark deprecated NIPs with their status
|
||||
- Maintain the existing grouping structure (Core Protocol, Social Features, Advanced, etc.)
|
||||
- Place new NIPs in the appropriate section based on their topic
|
||||
|
||||
### Update the Key NIPs table in `SKILL.md`
|
||||
|
||||
Update the "Key NIPs Reference" table in `.claude/skills/nostr/SKILL.md`:
|
||||
- Keep it as a curated summary (15-20 most important NIPs), not an exhaustive list
|
||||
- Add any newly-important NIPs (final status, widely implemented)
|
||||
- Remove deprecated NIPs from the table
|
||||
- Update descriptions if they changed upstream
|
||||
|
||||
Also update the "Common kinds" one-liner in the "Event Kind Ranges" section if new widely-used kinds were added.
|
||||
|
||||
### Do NOT change in `SKILL.md`:
|
||||
- The protocol fundamentals sections (event structure, tags, filters, WebSocket messages)
|
||||
- The nostr-tools code examples
|
||||
- The "Common Patterns" code examples
|
||||
- The "Security Essentials" section
|
||||
|
||||
## Step 7: Verify
|
||||
|
||||
```bash
|
||||
npm run lint && npm run test:run && npm run build
|
||||
@@ -89,11 +131,12 @@ npm run lint && npm run test:run && npm run build
|
||||
|
||||
Fix any lint/type/build issues before reporting.
|
||||
|
||||
## Step 7: Report
|
||||
## Step 8: Report
|
||||
|
||||
Summarize:
|
||||
- NIPs added / removed / title-updated
|
||||
- NIP icons added / updated in `nip-icons.ts`
|
||||
- Kinds added / updated (with icon choices explained for new ones)
|
||||
- Nostr skill files updated (which reference files changed, what was added/removed)
|
||||
- Inconsistencies found and resolved
|
||||
- Verification results (lint/test/build)
|
||||
|
||||
@@ -1,623 +0,0 @@
|
||||
---
|
||||
name: applesauce-common
|
||||
description: This skill should be used when working with applesauce-common library for social/NIP-specific helpers, casting system, blueprints, and operations. New in applesauce v5 - contains helpers that moved from applesauce-core.
|
||||
---
|
||||
|
||||
# applesauce-common Skill (v5)
|
||||
|
||||
This skill provides comprehensive knowledge for working with applesauce-common, a new package in applesauce v5 that contains social/NIP-specific utilities, the casting system, blueprints, and operations.
|
||||
|
||||
**Note**: applesauce-common was introduced in v5. Many helpers that were previously in `applesauce-core/helpers` have moved here.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
Use this skill when:
|
||||
- Working with article, highlight, threading, zap, or reaction helpers
|
||||
- Using the casting system for typed event access
|
||||
- Creating events with blueprints
|
||||
- Modifying events with operations
|
||||
- Working with NIP-specific social features
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
applesauce-common/
|
||||
├── helpers/ # Social/NIP-specific helpers
|
||||
│ ├── article.js # NIP-23 article helpers
|
||||
│ ├── highlight.js # NIP-84 highlight helpers
|
||||
│ ├── threading.js # NIP-10 thread helpers
|
||||
│ ├── comment.js # NIP-22 comment helpers
|
||||
│ ├── zap.js # NIP-57 zap helpers
|
||||
│ ├── reaction.js # NIP-25 reaction helpers
|
||||
│ ├── lists.js # NIP-51 list helpers
|
||||
│ └── ...
|
||||
├── casts/ # Typed event classes
|
||||
│ ├── Note.js
|
||||
│ ├── User.js
|
||||
│ ├── Profile.js
|
||||
│ ├── Article.js
|
||||
│ └── ...
|
||||
├── blueprints/ # Event creation blueprints
|
||||
└── operations/ # Event modification operations
|
||||
```
|
||||
|
||||
## Helpers (Migrated from applesauce-core)
|
||||
|
||||
### Article Helpers (NIP-23)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getArticleTitle,
|
||||
getArticleSummary,
|
||||
getArticleImage,
|
||||
getArticlePublished
|
||||
} from 'applesauce-common/helpers/article';
|
||||
|
||||
// All helpers cache internally - no useMemo needed
|
||||
const title = getArticleTitle(event);
|
||||
const summary = getArticleSummary(event);
|
||||
const image = getArticleImage(event);
|
||||
const publishedAt = getArticlePublished(event);
|
||||
```
|
||||
|
||||
### Highlight Helpers (NIP-84)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getHighlightText,
|
||||
getHighlightSourceUrl,
|
||||
getHighlightSourceEventPointer,
|
||||
getHighlightSourceAddressPointer,
|
||||
getHighlightContext,
|
||||
getHighlightComment
|
||||
} from 'applesauce-common/helpers/highlight';
|
||||
|
||||
const text = getHighlightText(event);
|
||||
const sourceUrl = getHighlightSourceUrl(event);
|
||||
const eventPointer = getHighlightSourceEventPointer(event);
|
||||
const addressPointer = getHighlightSourceAddressPointer(event);
|
||||
const context = getHighlightContext(event);
|
||||
const comment = getHighlightComment(event);
|
||||
```
|
||||
|
||||
### Threading Helpers (NIP-10)
|
||||
|
||||
```typescript
|
||||
import { getNip10References } from 'applesauce-common/helpers/threading';
|
||||
|
||||
// Parse NIP-10 thread structure
|
||||
const refs = getNip10References(event);
|
||||
|
||||
if (refs.root) {
|
||||
console.log('Root event:', refs.root.e);
|
||||
console.log('Root address:', refs.root.a);
|
||||
}
|
||||
|
||||
if (refs.reply) {
|
||||
console.log('Reply to:', refs.reply.e);
|
||||
}
|
||||
```
|
||||
|
||||
### Comment Helpers (NIP-22)
|
||||
|
||||
```typescript
|
||||
import { getCommentReplyPointer } from 'applesauce-common/helpers/comment';
|
||||
|
||||
const pointer = getCommentReplyPointer(event);
|
||||
if (pointer) {
|
||||
// Handle reply target
|
||||
}
|
||||
```
|
||||
|
||||
### Zap Helpers (NIP-57)
|
||||
|
||||
```typescript
|
||||
import {
|
||||
getZapAmount,
|
||||
getZapSender,
|
||||
getZapRecipient,
|
||||
getZapComment
|
||||
} from 'applesauce-common/helpers/zap';
|
||||
|
||||
const amount = getZapAmount(event); // In millisats
|
||||
const sender = getZapSender(event); // Pubkey
|
||||
const recipient = getZapRecipient(event);
|
||||
const comment = getZapComment(event);
|
||||
```
|
||||
|
||||
### List Helpers (NIP-51)
|
||||
|
||||
```typescript
|
||||
import { getRelaysFromList } from 'applesauce-common/helpers/lists';
|
||||
|
||||
const relays = getRelaysFromList(event);
|
||||
```
|
||||
|
||||
## Casting System
|
||||
|
||||
The casting system transforms raw Nostr events into typed classes with both synchronous properties and reactive observables.
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```typescript
|
||||
import { castEvent, Note, User, Profile } from 'applesauce-common/casts';
|
||||
|
||||
// Cast an event to a typed class
|
||||
const note = castEvent(event, Note, eventStore);
|
||||
|
||||
// Access synchronous properties
|
||||
console.log(note.id);
|
||||
console.log(note.createdAt);
|
||||
console.log(note.isReply);
|
||||
|
||||
// Subscribe to reactive observables
|
||||
note.author.profile$.subscribe(profile => {
|
||||
console.log('Author name:', profile?.name);
|
||||
});
|
||||
```
|
||||
|
||||
### Available Casts
|
||||
|
||||
- **Note** - Kind 1 short text notes
|
||||
- **User** - User with profile and social graph
|
||||
- **Profile** - Kind 0 profile metadata
|
||||
- **Article** - Kind 30023 long-form articles
|
||||
- **Reaction** - Kind 7 reactions
|
||||
- **Zap** - Kind 9735 zap receipts
|
||||
- **Comment** - NIP-22 comments
|
||||
- **Share** - Reposts/quotes
|
||||
- **Bookmarks** - NIP-51 bookmarks
|
||||
- **Mutes** - NIP-51 mute lists
|
||||
|
||||
### With React
|
||||
|
||||
```typescript
|
||||
import { use$ } from 'applesauce-react/hooks';
|
||||
import { castEvent, Note } from 'applesauce-common/casts';
|
||||
|
||||
function NoteComponent({ event }) {
|
||||
const note = castEvent(event, Note, eventStore);
|
||||
|
||||
// Subscribe to author's profile
|
||||
const profile = use$(note.author.profile$);
|
||||
|
||||
// Subscribe to replies
|
||||
const replies = use$(note.replies$);
|
||||
|
||||
return (
|
||||
<div>
|
||||
<span>{profile?.name}</span>
|
||||
<p>{note.content}</p>
|
||||
<span>{replies?.length} replies</span>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Blueprints
|
||||
|
||||
Blueprints are factory functions that create Nostr events with automatic tag extraction and proper NIP compliance. They eliminate manual tag building and reduce boilerplate code significantly.
|
||||
|
||||
### Key Benefits
|
||||
|
||||
1. **Automatic Tag Extraction**: Blueprints automatically extract hashtags (#word), mentions (nostr:npub), and event quotes (nostr:note/nevent) from text content
|
||||
2. **NIP Compliance**: Each blueprint follows the correct NIP specifications for its event type
|
||||
3. **Less Code**: Replace 50-100 lines of manual tag building with 5-10 lines
|
||||
4. **Type Safety**: Full TypeScript support with proper types for all options
|
||||
5. **Maintainable**: Centralized event building logic that's easier to update
|
||||
|
||||
### Using Blueprints
|
||||
|
||||
```typescript
|
||||
import { EventFactory } from 'applesauce-core/event-factory';
|
||||
import { NoteBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
const factory = new EventFactory();
|
||||
factory.setSigner(signer);
|
||||
|
||||
// Create event from blueprint
|
||||
const draft = await factory.create(NoteBlueprint, content, options);
|
||||
const event = await factory.sign(draft);
|
||||
```
|
||||
|
||||
### NoteBlueprint (Kind 1)
|
||||
|
||||
Creates short text notes with automatic hashtag, mention, and quote extraction.
|
||||
|
||||
**What it handles automatically:**
|
||||
- Extracts `#hashtags` from content → `t` tags
|
||||
- Extracts `nostr:npub...` mentions → `p` tags
|
||||
- Extracts `nostr:note...` and `nostr:nevent...` quotes → `q` tags (NIP-18)
|
||||
- Adds custom emoji tags (NIP-30)
|
||||
|
||||
```typescript
|
||||
import { NoteBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
// Simple note
|
||||
const draft = await factory.create(
|
||||
NoteBlueprint,
|
||||
'Hello #nostr! Check out nostr:npub1abc...',
|
||||
{}
|
||||
);
|
||||
|
||||
// With custom emojis
|
||||
const draft = await factory.create(
|
||||
NoteBlueprint,
|
||||
'Hello :rocket:!',
|
||||
{
|
||||
emojis: [{ shortcode: 'rocket', url: 'https://example.com/rocket.png' }]
|
||||
}
|
||||
);
|
||||
|
||||
// The blueprint automatically adds:
|
||||
// - ["t", "nostr"] for #nostr
|
||||
// - ["p", "decoded-pubkey"] for the npub mention
|
||||
// - ["emoji", "rocket", "https://example.com/rocket.png"] for custom emoji
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `emojis?: Array<{ shortcode: string; url: string }>` - Custom emojis (NIP-30)
|
||||
- `contentWarning?: boolean | string` - Content warning tag
|
||||
|
||||
**Before/After Example:**
|
||||
```typescript
|
||||
// ❌ BEFORE: Manual tag building (~70 lines)
|
||||
const hashtags = content.match(/#(\w+)/g)?.map(tag => tag.slice(1)) || [];
|
||||
const mentionRegex = /nostr:(npub1[a-z0-9]+)/g;
|
||||
const mentions = [];
|
||||
let match;
|
||||
while ((match = mentionRegex.exec(content)) !== null) {
|
||||
try {
|
||||
const { data } = nip19.decode(match[1]);
|
||||
mentions.push(data);
|
||||
} catch (e) { /* ignore */ }
|
||||
}
|
||||
// ... more extraction logic ...
|
||||
draft.tags = [
|
||||
...hashtags.map(t => ['t', t]),
|
||||
...mentions.map(p => ['p', p]),
|
||||
// ... more tags ...
|
||||
];
|
||||
|
||||
// ✅ AFTER: Blueprint handles everything
|
||||
const draft = await factory.create(NoteBlueprint, content, { emojis });
|
||||
```
|
||||
|
||||
### NoteReplyBlueprint (Kind 1 Reply)
|
||||
|
||||
Creates threaded note replies following NIP-10 conventions.
|
||||
|
||||
**What it handles automatically:**
|
||||
- Extracts root event from parent's tags (NIP-10)
|
||||
- Adds proper `e` tags with markers (root, reply)
|
||||
- Copies `p` tags from parent for notifications
|
||||
- Extracts hashtags, mentions, and quotes from content
|
||||
- Uses `q` tags for quotes instead of `e` tags (correct semantic)
|
||||
|
||||
```typescript
|
||||
import { NoteReplyBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
// Reply to a note
|
||||
const parentEvent = await eventStore.event(parentId).toPromise();
|
||||
|
||||
const draft = await factory.create(
|
||||
NoteReplyBlueprint,
|
||||
parentEvent,
|
||||
'Great point! #bitcoin',
|
||||
{
|
||||
emojis: [{ shortcode: 'fire', url: 'https://example.com/fire.png' }]
|
||||
}
|
||||
);
|
||||
|
||||
// The blueprint automatically:
|
||||
// 1. Finds root from parent's tags (if parent is also a reply)
|
||||
// 2. Adds ["e", rootId, relay, "root"]
|
||||
// 3. Adds ["e", parentId, relay, "reply"]
|
||||
// 4. Copies all ["p", ...] tags from parent
|
||||
// 5. Extracts #bitcoin → ["t", "bitcoin"]
|
||||
// 6. Adds emoji tag
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `emojis?: Array<{ shortcode: string; url: string }>` - Custom emojis
|
||||
- `contentWarning?: boolean | string` - Content warning
|
||||
|
||||
**Before/After Example:**
|
||||
```typescript
|
||||
// ❌ BEFORE: Manual NIP-10 threading (~95 lines)
|
||||
const parentRefs = getNip10References(parentEvent);
|
||||
const rootId = parentRefs.root?.e || parentEvent.id;
|
||||
const rootRelay = parentRefs.root?.relay || '';
|
||||
|
||||
draft.tags = [
|
||||
['e', rootId, rootRelay, 'root'],
|
||||
['e', parentEvent.id, '', 'reply'],
|
||||
];
|
||||
|
||||
// Copy p-tags from parent
|
||||
const parentPTags = parentEvent.tags.filter(t => t[0] === 'p');
|
||||
draft.tags.push(...parentPTags);
|
||||
if (!parentPTags.some(t => t[1] === parentEvent.pubkey)) {
|
||||
draft.tags.push(['p', parentEvent.pubkey]);
|
||||
}
|
||||
// ... hashtag extraction ...
|
||||
// ... mention extraction ...
|
||||
|
||||
// ✅ AFTER: Blueprint handles NIP-10 threading
|
||||
const draft = await factory.create(
|
||||
NoteReplyBlueprint,
|
||||
parentEvent,
|
||||
content,
|
||||
{ emojis }
|
||||
);
|
||||
```
|
||||
|
||||
### ReactionBlueprint (Kind 7)
|
||||
|
||||
Creates reactions to events (likes, custom emoji reactions).
|
||||
|
||||
**What it handles automatically:**
|
||||
- Adds `e` tag pointing to reacted event
|
||||
- Adds `k` tag for event kind
|
||||
- Adds `p` tag for event author
|
||||
- Handles custom emoji reactions (`:shortcode:` format)
|
||||
- Supports both string emoji and Emoji objects
|
||||
|
||||
```typescript
|
||||
import { ReactionBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
// Simple like (+ emoji)
|
||||
const draft = await factory.create(ReactionBlueprint, messageEvent, '+');
|
||||
|
||||
// Custom emoji reaction
|
||||
const draft = await factory.create(
|
||||
ReactionBlueprint,
|
||||
messageEvent,
|
||||
{
|
||||
shortcode: 'rocket',
|
||||
url: 'https://example.com/rocket.png'
|
||||
}
|
||||
);
|
||||
|
||||
// String emoji
|
||||
const draft = await factory.create(ReactionBlueprint, messageEvent, '🚀');
|
||||
|
||||
// The blueprint automatically adds:
|
||||
// - ["e", messageEvent.id]
|
||||
// - ["k", messageEvent.kind.toString()]
|
||||
// - ["p", messageEvent.pubkey]
|
||||
// For custom emoji: ["emoji", "rocket", "url"]
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- Second parameter: `emoji?: string | { shortcode: string; url: string }`
|
||||
|
||||
**Before/After Example:**
|
||||
```typescript
|
||||
// ❌ BEFORE: Manual reaction building (~15 lines per adapter)
|
||||
draft.kind = 7;
|
||||
draft.content = typeof emoji === 'string' ? emoji : `:${emoji.shortcode}:`;
|
||||
draft.tags = [
|
||||
['e', messageEvent.id],
|
||||
['k', messageEvent.kind.toString()],
|
||||
['p', messageEvent.pubkey],
|
||||
];
|
||||
if (typeof emoji === 'object') {
|
||||
draft.tags.push(['emoji', emoji.shortcode, emoji.url]);
|
||||
}
|
||||
|
||||
// ✅ AFTER: Blueprint handles reactions
|
||||
const draft = await factory.create(ReactionBlueprint, messageEvent, emoji);
|
||||
```
|
||||
|
||||
### GroupMessageBlueprint (Kind 9 - NIP-29)
|
||||
|
||||
Creates NIP-29 group chat messages.
|
||||
|
||||
**What it handles automatically:**
|
||||
- Adds `h` tag with group ID
|
||||
- Extracts hashtags, mentions, and quotes from content
|
||||
- Adds custom emoji tags
|
||||
- Handles message threading with `previous` field
|
||||
|
||||
```typescript
|
||||
import { GroupMessageBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
// Send message to NIP-29 group
|
||||
const draft = await factory.create(
|
||||
GroupMessageBlueprint,
|
||||
{ id: groupId, relay: relayUrl },
|
||||
'Hello group! #welcome',
|
||||
{
|
||||
previous: [], // Array of previous message events for threading
|
||||
emojis: [{ shortcode: 'wave', url: 'https://example.com/wave.png' }]
|
||||
}
|
||||
);
|
||||
|
||||
// The blueprint automatically adds:
|
||||
// - ["h", groupId]
|
||||
// - ["t", "welcome"] for #welcome hashtag
|
||||
// - ["emoji", "wave", "url"] for custom emoji
|
||||
```
|
||||
|
||||
**Options:**
|
||||
- `previous?: NostrEvent[]` - Previous messages for threading (required, use `[]` if no threading)
|
||||
- `emojis?: Array<{ shortcode: string; url: string }>` - Custom emojis
|
||||
|
||||
**Note:** The `previous` field is required by the type, but can be an empty array if you don't need threading.
|
||||
|
||||
### DeleteBlueprint (Kind 5 - NIP-09)
|
||||
|
||||
Creates event deletion requests.
|
||||
|
||||
**What it handles automatically:**
|
||||
- Adds `e` tags for each event to delete
|
||||
- Sets proper kind and content format
|
||||
- Adds optional reason in content
|
||||
|
||||
```typescript
|
||||
import { DeleteBlueprint } from 'applesauce-common/blueprints';
|
||||
|
||||
// Delete single event
|
||||
const draft = await factory.create(
|
||||
DeleteBlueprint,
|
||||
[eventToDelete],
|
||||
'Accidental post'
|
||||
);
|
||||
|
||||
// Delete multiple events
|
||||
const draft = await factory.create(
|
||||
DeleteBlueprint,
|
||||
[event1, event2, event3],
|
||||
'Cleaning up old posts'
|
||||
);
|
||||
|
||||
// Without reason
|
||||
const draft = await factory.create(DeleteBlueprint, [event], '');
|
||||
|
||||
// The blueprint automatically:
|
||||
// - Sets kind to 5
|
||||
// - Adds ["e", eventId] for each event
|
||||
// - Sets content to reason (or empty)
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `events: (string | NostrEvent)[]` - Events to delete (IDs or full events)
|
||||
- `reason?: string` - Optional deletion reason
|
||||
|
||||
### Adding Custom Tags
|
||||
|
||||
Blueprints handle common tags automatically, but you can add custom tags afterward:
|
||||
|
||||
```typescript
|
||||
// Create with blueprint
|
||||
const draft = await factory.create(NoteBlueprint, content, { emojis });
|
||||
|
||||
// Add custom tags not handled by blueprint
|
||||
draft.tags.push(['client', 'grimoire', '31990:...']);
|
||||
draft.tags.push(['a', `${kind}:${pubkey}:${identifier}`]);
|
||||
|
||||
// Add NIP-92 imeta tags for blob attachments
|
||||
for (const blob of blobAttachments) {
|
||||
draft.tags.push(['imeta', `url ${blob.url}`, `x ${blob.sha256}`, ...]);
|
||||
}
|
||||
|
||||
// Sign the modified draft
|
||||
const event = await factory.sign(draft);
|
||||
```
|
||||
|
||||
### Protocol-Specific Tag Additions
|
||||
|
||||
Some protocols require additional tags beyond what blueprints provide:
|
||||
|
||||
```typescript
|
||||
// NIP-29: Add q-tag for replies (not in blueprint yet)
|
||||
const draft = await factory.create(GroupMessageBlueprint, group, content, options);
|
||||
if (replyToId) {
|
||||
draft.tags.push(['q', replyToId]);
|
||||
}
|
||||
|
||||
// NIP-53: Add a-tag for live activity context
|
||||
const draft = await factory.create(ReactionBlueprint, messageEvent, emoji);
|
||||
draft.tags.push(['a', liveActivityATag, relay]);
|
||||
```
|
||||
|
||||
### Available Blueprints
|
||||
|
||||
All blueprints from `applesauce-common/blueprints`:
|
||||
|
||||
- **NoteBlueprint** - Kind 1 short text notes
|
||||
- **NoteReplyBlueprint** - Kind 1 threaded replies (NIP-10)
|
||||
- **ReactionBlueprint** - Kind 7 reactions (NIP-25)
|
||||
- **GroupMessageBlueprint** - Kind 9 group messages (NIP-29)
|
||||
- **DeleteBlueprint** - Kind 5 deletion requests (NIP-09)
|
||||
- **MetadataBlueprint** - Kind 0 profile metadata
|
||||
- **ContactsBlueprint** - Kind 3 contact lists
|
||||
- **ArticleBlueprint** - Kind 30023 long-form articles (NIP-23)
|
||||
- **HighlightBlueprint** - Kind 9802 highlights (NIP-84)
|
||||
- **ZapRequestBlueprint** - Kind 9734 zap requests (NIP-57)
|
||||
- And more - check `node_modules/applesauce-common/dist/blueprints/`
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Always use blueprints** when creating standard event types - they handle NIPs correctly
|
||||
2. **Add custom tags after** blueprint creation for app-specific metadata
|
||||
3. **Don't extract tags manually** - let blueprints handle hashtags, mentions, quotes
|
||||
4. **Use proper emoji format** - blueprints expect `{ shortcode, url }` objects
|
||||
5. **Check blueprint source** - when in doubt, read the blueprint code for exact behavior
|
||||
|
||||
## Operations
|
||||
|
||||
Operations modify existing events.
|
||||
|
||||
```typescript
|
||||
import { addTag, removeTag } from 'applesauce-common/operations';
|
||||
|
||||
// Add a tag to an event
|
||||
const modified = addTag(event, ['t', 'bitcoin']);
|
||||
|
||||
// Remove a tag
|
||||
const updated = removeTag(event, 'client');
|
||||
```
|
||||
|
||||
## Migration from v4
|
||||
|
||||
### Helper Import Changes
|
||||
|
||||
```typescript
|
||||
// ❌ Old (v4)
|
||||
import { getArticleTitle } from 'applesauce-core/helpers';
|
||||
import { getNip10References } from 'applesauce-core/helpers/threading';
|
||||
import { getZapAmount } from 'applesauce-core/helpers/zap';
|
||||
|
||||
// ✅ New (v5)
|
||||
import { getArticleTitle } from 'applesauce-common/helpers/article';
|
||||
import { getNip10References } from 'applesauce-common/helpers/threading';
|
||||
import { getZapAmount } from 'applesauce-common/helpers/zap';
|
||||
```
|
||||
|
||||
### Helpers that stayed in applesauce-core
|
||||
|
||||
These protocol-level helpers remain in `applesauce-core/helpers`:
|
||||
- `getTagValue`, `hasNameValueTag`
|
||||
- `getProfileContent`
|
||||
- `parseCoordinate`, `getEventPointerFromETag`, `getAddressPointerFromATag`
|
||||
- `isFilterEqual`, `matchFilter`, `mergeFilters`
|
||||
- `getSeenRelays`, `mergeRelaySets`
|
||||
- `getInboxes`, `getOutboxes`
|
||||
- `normalizeURL`
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Helper Caching
|
||||
|
||||
All helpers in applesauce-common cache internally using symbols:
|
||||
|
||||
```typescript
|
||||
// ❌ Don't memoize helper calls
|
||||
const title = useMemo(() => getArticleTitle(event), [event]);
|
||||
|
||||
// ✅ Call helpers directly
|
||||
const title = getArticleTitle(event);
|
||||
```
|
||||
|
||||
### Casting vs Helpers
|
||||
|
||||
Use **helpers** when you need specific fields:
|
||||
```typescript
|
||||
const title = getArticleTitle(event);
|
||||
const amount = getZapAmount(event);
|
||||
```
|
||||
|
||||
Use **casts** when you need reactive data or multiple related properties:
|
||||
```typescript
|
||||
const note = castEvent(event, Note, eventStore);
|
||||
const profile$ = note.author.profile$;
|
||||
const replies$ = note.replies$;
|
||||
```
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **applesauce-core** - Protocol-level helpers and event store
|
||||
- **applesauce-signers** - Event signing abstractions
|
||||
- **nostr** - Nostr protocol fundamentals
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,757 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -1,767 +0,0 @@
|
||||
---
|
||||
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
|
||||
@@ -1,162 +0,0 @@
|
||||
# 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).
|
||||
|
||||
@@ -1,449 +1,283 @@
|
||||
---
|
||||
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.
|
||||
description: Use this skill whenever working with the Nostr protocol — event creation, signing, filtering, relay communication, NIP implementations, key encoding (NIP-19), encryption (NIP-04/NIP-44), or nostr-tools library APIs. Activate for any code importing nostr-tools, handling Nostr events, or discussing NIPs.
|
||||
---
|
||||
|
||||
# Nostr Protocol Expert
|
||||
# Nostr Protocol & nostr-tools
|
||||
|
||||
## Purpose
|
||||
Comprehensive reference for the Nostr protocol and the nostr-tools JavaScript library.
|
||||
|
||||
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.
|
||||
## Protocol Fundamentals
|
||||
|
||||
## When to Use
|
||||
### Events
|
||||
|
||||
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:
|
||||
All data in Nostr is an event — a signed JSON object:
|
||||
|
||||
```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>",
|
||||
"id": "<32-byte hex SHA256 of serialized event>",
|
||||
"pubkey": "<32-byte hex public key>",
|
||||
"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>"
|
||||
"kind": "<integer>",
|
||||
"tags": [["<name>", "<value>", "..."]],
|
||||
"content": "<string>",
|
||||
"sig": "<64-byte hex schnorr signature of id>"
|
||||
}
|
||||
```
|
||||
|
||||
### Event Kinds
|
||||
**ID calculation**: `SHA256(JSON.stringify([0, pubkey, created_at, kind, tags, content]))` — compact JSON, no spaces.
|
||||
|
||||
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
|
||||
**Signature**: Schnorr (BIP-340) on secp256k1, signing the 32-byte event ID.
|
||||
|
||||
### Event Kind Ranges
|
||||
|
||||
| Range | Type | Behavior |
|
||||
|-------|------|----------|
|
||||
| 0-999 | Core | Varies per kind |
|
||||
| 1000-9999 | Regular | Immutable, all kept |
|
||||
| 10000-19999 | Replaceable | Latest per pubkey+kind wins |
|
||||
| 20000-29999 | Ephemeral | Not stored, forwarded only |
|
||||
| 30000-39999 | Parameterized Replaceable | Latest per pubkey+kind+d-tag wins |
|
||||
|
||||
Common kinds: `0` metadata, `1` text note, `3` contacts, `5` deletion, `6` repost, `7` reaction, `9` group message (NIP-29), `9735` zap receipt, `10002` relay list, `30023` article.
|
||||
|
||||
See **references/event-kinds.md** for the full list.
|
||||
|
||||
### 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>]
|
||||
```
|
||||
["e", "<event-id>", "<relay-url>", "<marker>"] — event reference
|
||||
["p", "<pubkey>", "<relay-url>"] — profile reference
|
||||
["a", "<kind>:<pubkey>:<d-tag>", "<relay-url>"] — replaceable event ref
|
||||
["d", "<identifier>"] — parameterized replaceable ID
|
||||
["t", "<hashtag>"] — hashtag
|
||||
["r", "<url>"] — web resource / relay
|
||||
```
|
||||
|
||||
**REQ** - Request events (subscription):
|
||||
```json
|
||||
["REQ", <subscription_id>, <filters JSON>, <filters JSON>, ...]
|
||||
```
|
||||
NIP-10 markers for threading: `"root"`, `"reply"`, `"mention"`.
|
||||
|
||||
**CLOSE** - Stop a subscription:
|
||||
```json
|
||||
["CLOSE", <subscription_id>]
|
||||
```
|
||||
### Client-Relay Communication (WebSocket)
|
||||
|
||||
**AUTH** - Respond to auth challenge:
|
||||
```json
|
||||
["AUTH", <signed event kind 22242>]
|
||||
```
|
||||
**Client sends**: `["EVENT", <event>]`, `["REQ", <sub_id>, <filter>, ...]`, `["CLOSE", <sub_id>]`, `["AUTH", <event>]`
|
||||
|
||||
#### From Relay to Client
|
||||
**Relay sends**: `["EVENT", <sub_id>, <event>]`, `["OK", <event_id>, <bool>, <msg>]`, `["EOSE", <sub_id>]`, `["CLOSED", <sub_id>, <msg>]`, `["NOTICE", <msg>]`, `["AUTH", <challenge>]`
|
||||
|
||||
**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:
|
||||
### Filters
|
||||
|
||||
```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>
|
||||
"ids": ["<hex>"],
|
||||
"authors": ["<hex>"],
|
||||
"kinds": [1, 7],
|
||||
"#e": ["<event-id>"],
|
||||
"#p": ["<pubkey>"],
|
||||
"#t": ["<hashtag>"],
|
||||
"since": 1704067200,
|
||||
"until": 1704153600,
|
||||
"limit": 50,
|
||||
"search": "query"
|
||||
}
|
||||
```
|
||||
|
||||
Filtering rules:
|
||||
- Arrays are ORed together
|
||||
- Different fields are ANDed
|
||||
- Tag filters: `#<single-letter>` matches tag values
|
||||
- Prefix matching allowed for `ids` and `authors`
|
||||
- Array fields are OR'd; different fields are AND'd
|
||||
- `ids` and `authors` support prefix matching
|
||||
- Always set reasonable `limit` (50-500)
|
||||
|
||||
## Cryptographic Operations
|
||||
## nostr-tools Library
|
||||
|
||||
### Key Management
|
||||
### Key Management & Encoding (NIP-19)
|
||||
|
||||
- **Private Key**: 32-byte random value, keep secure
|
||||
- **Public Key**: Derived via secp256k1
|
||||
- **Encoding**: Hex (lowercase) or bech32
|
||||
```typescript
|
||||
import { generateSecretKey, getPublicKey } from 'nostr-tools/pure';
|
||||
import { nip19 } from 'nostr-tools';
|
||||
|
||||
### Event Signing (schnorr)
|
||||
const sk = generateSecretKey(); // Uint8Array
|
||||
const pk = getPublicKey(sk); // hex string
|
||||
|
||||
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`
|
||||
// Encode
|
||||
const npub = nip19.npubEncode(pk); // npub1...
|
||||
const nsec = nip19.nsecEncode(sk); // nsec1...
|
||||
const note = nip19.noteEncode(eventId); // note1...
|
||||
|
||||
Serialization format for ID calculation:
|
||||
```json
|
||||
[
|
||||
0,
|
||||
<pubkey>,
|
||||
<created_at>,
|
||||
<kind>,
|
||||
<tags>,
|
||||
<content>
|
||||
]
|
||||
const nprofile = nip19.nprofileEncode({ pubkey: pk, relays: ['wss://...'] });
|
||||
const nevent = nip19.neventEncode({ id, relays, author, kind });
|
||||
const naddr = nip19.naddrEncode({ identifier, pubkey, kind, relays });
|
||||
|
||||
// Decode
|
||||
const { type, data } = nip19.decode(npub); // type: 'npub', data: hex
|
||||
```
|
||||
|
||||
### Event Verification
|
||||
### Creating & Signing Events
|
||||
|
||||
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
|
||||
```typescript
|
||||
import { finalizeEvent, verifyEvent } from 'nostr-tools/pure';
|
||||
|
||||
## Implementation Best Practices
|
||||
const event = finalizeEvent({
|
||||
kind: 1,
|
||||
created_at: Math.floor(Date.now() / 1000),
|
||||
tags: [['t', 'nostr']],
|
||||
content: 'Hello Nostr!'
|
||||
}, secretKey);
|
||||
|
||||
### For Clients
|
||||
const valid = verifyEvent(event); // true/false
|
||||
```
|
||||
|
||||
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
|
||||
### Relay Communication (SimplePool)
|
||||
|
||||
### For Relays
|
||||
```typescript
|
||||
import { SimplePool } from 'nostr-tools/pool';
|
||||
|
||||
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
|
||||
const pool = new SimplePool();
|
||||
const relays = ['wss://relay.damus.io', 'wss://nos.lol'];
|
||||
|
||||
### Security Considerations
|
||||
// Subscribe
|
||||
const sub = pool.subscribeMany(relays, [filter], {
|
||||
onevent(event) { /* handle event */ },
|
||||
oneose() { /* end of stored events */ }
|
||||
});
|
||||
sub.close(); // always close when done
|
||||
|
||||
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
|
||||
// Query (returns Promise)
|
||||
const events = await pool.querySync(relays, filter);
|
||||
const event = await pool.get(relays, { ids: [eventId] });
|
||||
|
||||
// Publish
|
||||
await Promise.allSettled(pool.publish(relays, signedEvent));
|
||||
|
||||
// Cleanup
|
||||
pool.close(relays);
|
||||
```
|
||||
|
||||
### Direct Relay Connection
|
||||
|
||||
```typescript
|
||||
import { Relay } from 'nostr-tools/relay';
|
||||
|
||||
const relay = await Relay.connect('wss://relay.damus.io');
|
||||
|
||||
const sub = relay.subscribe([filter], {
|
||||
onevent(event) { /* ... */ },
|
||||
oneose() { sub.close(); }
|
||||
});
|
||||
|
||||
await relay.publish(signedEvent);
|
||||
relay.close();
|
||||
```
|
||||
|
||||
### Encryption
|
||||
|
||||
```typescript
|
||||
// NIP-44 (preferred)
|
||||
import { nip44 } from 'nostr-tools';
|
||||
|
||||
const conversationKey = nip44.getConversationKey(secretKey, recipientPubkey);
|
||||
const ciphertext = nip44.encrypt('Hello!', conversationKey);
|
||||
const plaintext = nip44.decrypt(ciphertext, conversationKey);
|
||||
|
||||
// NIP-04 (legacy, avoid for new code)
|
||||
import { nip04 } from 'nostr-tools';
|
||||
|
||||
const ct = await nip04.encrypt(secretKey, recipientPubkey, 'Hello!');
|
||||
const pt = await nip04.decrypt(secretKey, senderPubkey, ct);
|
||||
```
|
||||
|
||||
### NIP-05 DNS Identifiers
|
||||
|
||||
```typescript
|
||||
import { nip05 } from 'nostr-tools';
|
||||
|
||||
const profile = await nip05.queryProfile('alice@example.com');
|
||||
// { pubkey: '...', relays: ['wss://...'] }
|
||||
```
|
||||
|
||||
### NIP-10 Thread Parsing
|
||||
|
||||
```typescript
|
||||
import { nip10 } from 'nostr-tools';
|
||||
|
||||
const parsed = nip10.parse(event);
|
||||
// { root, reply, mentions, profiles }
|
||||
```
|
||||
|
||||
## Key NIPs Reference
|
||||
|
||||
| NIP | Topic | Key Points |
|
||||
|-----|-------|------------|
|
||||
| 01 | Basic protocol | Event structure, WebSocket messages, filters |
|
||||
| 02 | Contacts | Kind 3, `p` tags for following list |
|
||||
| 05 | DNS identifiers | `name@domain` via `.well-known/nostr.json` |
|
||||
| 09 | Deletion | Kind 5, `e` tags for events to delete |
|
||||
| 10 | Threading | `e` tag markers: root, reply, mention |
|
||||
| 11 | Relay info | HTTP GET relay URL for NIP-11 document |
|
||||
| 19 | bech32 entities | npub, nsec, note, nprofile, nevent, naddr |
|
||||
| 25 | Reactions | Kind 7, content "+" or emoji |
|
||||
| 42 | Auth | Relay challenges, kind 22242 response |
|
||||
| 44 | Encryption | ChaCha20-Poly1305 AEAD (replaces NIP-04) |
|
||||
| 50 | Search | `search` field in filters |
|
||||
| 57 | Zaps | Kind 9734 request, 9735 receipt |
|
||||
| 65 | Relay list | Kind 10002, read/write relay preferences |
|
||||
|
||||
See **references/nips-overview.md** for comprehensive NIP documentation.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Publishing a Note
|
||||
### Reply with NIP-10 threading
|
||||
|
||||
```javascript
|
||||
const event = {
|
||||
pubkey: userPublicKey,
|
||||
```typescript
|
||||
const reply = finalizeEvent({
|
||||
kind: 1,
|
||||
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]
|
||||
['e', rootEventId, '', 'root'],
|
||||
['e', parentEventId, '', 'reply'],
|
||||
['p', parentAuthorPubkey]
|
||||
],
|
||||
content: "Great post!",
|
||||
// ... other fields
|
||||
content: 'Great post!'
|
||||
}, secretKey);
|
||||
```
|
||||
|
||||
### NIP-65 relay list
|
||||
|
||||
```typescript
|
||||
// Fetch user's relay preferences
|
||||
const [relayList] = await pool.querySync(relays, {
|
||||
kinds: [10002], authors: [pubkey]
|
||||
});
|
||||
|
||||
const readRelays = [], writeRelays = [];
|
||||
for (const [tag, url, mode] of relayList.tags) {
|
||||
if (tag !== 'r') continue;
|
||||
if (!mode || mode === 'read') readRelays.push(url);
|
||||
if (!mode || mode === 'write') writeRelays.push(url);
|
||||
}
|
||||
```
|
||||
|
||||
### Reacting to a Note
|
||||
### Reconnection with backoff
|
||||
|
||||
```javascript
|
||||
const reaction = {
|
||||
kind: 7,
|
||||
tags: [
|
||||
["e", eventId],
|
||||
["p", eventAuthorPubkey]
|
||||
],
|
||||
content: "+", // or emoji
|
||||
// ... other fields
|
||||
}
|
||||
```typescript
|
||||
let delay = 1000;
|
||||
const connect = () => {
|
||||
const ws = new WebSocket(relayUrl);
|
||||
ws.onopen = () => { delay = 1000; resubscribe(); };
|
||||
ws.onclose = () => {
|
||||
setTimeout(connect, delay);
|
||||
delay = Math.min(delay * 2, 30000);
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
## Development Resources
|
||||
## Security Essentials
|
||||
|
||||
### Essential NIPs for Beginners
|
||||
- **Never expose nsec** in code, logs, or network requests
|
||||
- **Always verify signatures** before trusting event data
|
||||
- **Use NIP-44** for encryption (NIP-04 is deprecated)
|
||||
- **Sanitize content** before rendering (XSS prevention)
|
||||
- **Prefer NIP-07** (browser extensions) over handling raw keys
|
||||
|
||||
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
|
||||
See **references/common-mistakes.md** for a comprehensive list of pitfalls.
|
||||
|
||||
## 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
|
||||
|
||||
- **references/nips-overview.md** — Detailed descriptions of all standard NIPs
|
||||
- **references/event-kinds.md** — Complete event kinds reference with examples
|
||||
- **references/common-mistakes.md** — 30 common implementation mistakes and fixes
|
||||
|
||||
@@ -1,119 +0,0 @@
|
||||
# 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.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,878 +0,0 @@
|
||||
# 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)
|
||||
|
||||
@@ -1,291 +0,0 @@
|
||||
# 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)
|
||||
}, [])
|
||||
```
|
||||
|
||||
@@ -1,658 +0,0 @@
|
||||
# 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/
|
||||
|
||||
@@ -1,656 +0,0 @@
|
||||
# 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
|
||||
|
||||
@@ -1,401 +0,0 @@
|
||||
# Skill: Tailwind CSS v4
|
||||
|
||||
This document provides guidance for writing CSS and using Tailwind in Grimoire after the v4 migration.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Import Syntax
|
||||
```css
|
||||
/* v4 - Single import replaces @tailwind directives */
|
||||
@import "tailwindcss";
|
||||
```
|
||||
|
||||
### Defining Theme Variables
|
||||
```css
|
||||
@theme {
|
||||
--color-brand: oklch(0.72 0.11 221.19);
|
||||
--font-display: "Satoshi", sans-serif;
|
||||
--animate-fade: fade 0.3s ease-out;
|
||||
|
||||
@keyframes fade {
|
||||
from { opacity: 0; }
|
||||
to { opacity: 1; }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Utilities
|
||||
```css
|
||||
/* v4 - Use @utility instead of @layer utilities */
|
||||
@utility content-auto {
|
||||
content-visibility: auto;
|
||||
}
|
||||
|
||||
/* With nested selectors */
|
||||
@utility scrollbar-hidden {
|
||||
scrollbar-width: none;
|
||||
-ms-overflow-style: none;
|
||||
|
||||
&::-webkit-scrollbar {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Custom Variants
|
||||
```css
|
||||
/* Simple variant */
|
||||
@custom-variant theme-dark (&:where(.dark, .dark *));
|
||||
|
||||
/* Complex variant */
|
||||
@custom-variant any-hover {
|
||||
@media (any-hover: hover) {
|
||||
&:hover {
|
||||
@slot;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Grimoire Theme System
|
||||
|
||||
Grimoire uses a **two-level CSS variable system** for runtime theming:
|
||||
|
||||
### Level 1: Runtime Variables (set by ThemeProvider)
|
||||
These are HSL values WITHOUT the `hsl()` wrapper:
|
||||
```css
|
||||
:root {
|
||||
--background: 222.2 84% 4.9%;
|
||||
--foreground: 210 40% 98%;
|
||||
--primary: 210 40% 98%;
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
### Level 2: Tailwind Color Mapping (in @theme)
|
||||
These reference the runtime variables with `hsl()`:
|
||||
```css
|
||||
@theme {
|
||||
--color-background: hsl(var(--background));
|
||||
--color-foreground: hsl(var(--foreground));
|
||||
--color-primary: hsl(var(--primary));
|
||||
}
|
||||
```
|
||||
|
||||
### Using Colors in Components
|
||||
|
||||
**In Tailwind classes:**
|
||||
```tsx
|
||||
<div className="bg-background text-foreground border-border">
|
||||
<button className="bg-primary text-primary-foreground">
|
||||
<span className="text-muted-foreground">
|
||||
```
|
||||
|
||||
**In custom CSS with opacity:**
|
||||
```css
|
||||
.my-element {
|
||||
background: hsl(var(--primary) / 0.1);
|
||||
border: 1px solid hsl(var(--border) / 0.5);
|
||||
}
|
||||
```
|
||||
|
||||
### Available Color Tokens
|
||||
|
||||
| Token | Usage |
|
||||
|-------|-------|
|
||||
| `background` / `foreground` | Page background and text |
|
||||
| `card` / `card-foreground` | Card surfaces |
|
||||
| `popover` / `popover-foreground` | Dropdowns, tooltips |
|
||||
| `primary` / `primary-foreground` | Primary buttons, links |
|
||||
| `secondary` / `secondary-foreground` | Secondary actions |
|
||||
| `accent` / `accent-foreground` | Highlights, emphasis |
|
||||
| `muted` / `muted-foreground` | Subdued elements |
|
||||
| `destructive` / `destructive-foreground` | Delete, error actions |
|
||||
| `border` | Borders |
|
||||
| `input` | Form input borders |
|
||||
| `ring` | Focus rings |
|
||||
| `success` / `warning` / `info` | Status indicators |
|
||||
| `zap` | Lightning zap color (gold) |
|
||||
| `live` | Live indicator (red) |
|
||||
| `highlight` | Active user highlight (orange) |
|
||||
| `tooltip` / `tooltip-foreground` | Tooltip background/text |
|
||||
|
||||
---
|
||||
|
||||
## Container Queries (Built-in)
|
||||
|
||||
No plugin needed in v4. Use for component-relative responsiveness:
|
||||
|
||||
```tsx
|
||||
// Parent defines container
|
||||
<div className="@container">
|
||||
// Children respond to container width
|
||||
<div className="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3">
|
||||
{items.map(item => <Card key={item.id} />)}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Container Query Breakpoints
|
||||
| Variant | Width |
|
||||
|---------|-------|
|
||||
| `@xs:` | 20rem (320px) |
|
||||
| `@sm:` | 24rem (384px) |
|
||||
| `@md:` | 28rem (448px) |
|
||||
| `@lg:` | 32rem (512px) |
|
||||
| `@xl:` | 36rem (576px) |
|
||||
| `@2xl:` | 42rem (672px) |
|
||||
|
||||
### Max-width Queries
|
||||
```tsx
|
||||
<div className="@container">
|
||||
<div className="flex-row @max-sm:flex-col">
|
||||
{/* Row on larger containers, column on smaller */}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Named Containers
|
||||
```tsx
|
||||
<div className="@container/sidebar">
|
||||
<nav className="@sm/sidebar:flex-col">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Renamed Utilities (v3 → v4)
|
||||
|
||||
| v3 | v4 | Notes |
|
||||
|----|----| ------|
|
||||
| `shadow-sm` | `shadow-xs` | Smallest shadow |
|
||||
| `shadow` | `shadow-sm` | Default shadow |
|
||||
| `rounded-sm` | `rounded-xs` | Smallest radius |
|
||||
| `rounded` | `rounded-sm` | Default radius |
|
||||
| `blur-sm` | `blur-xs` | Smallest blur |
|
||||
| `blur` | `blur-sm` | Default blur |
|
||||
| `ring` | `ring-3` | Default ring width |
|
||||
|
||||
**Important:** Always use the named size, not bare utilities.
|
||||
|
||||
---
|
||||
|
||||
## CSS Variable Syntax in Classes
|
||||
|
||||
**v4 uses parentheses instead of brackets:**
|
||||
|
||||
```tsx
|
||||
// ❌ v3 syntax (deprecated)
|
||||
<div className="bg-[--my-color]" />
|
||||
<div className="fill-[--icon-color]" />
|
||||
|
||||
// ✅ v4 syntax
|
||||
<div className="bg-(--my-color)" />
|
||||
<div className="fill-(--icon-color)" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Modifier Position
|
||||
|
||||
**v4 moves `!` to the end:**
|
||||
|
||||
```tsx
|
||||
// ❌ v3 syntax
|
||||
<div className="!flex !mt-0" />
|
||||
|
||||
// ✅ v4 syntax
|
||||
<div className="flex! mt-0!" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## New Useful Variants
|
||||
|
||||
### not-* Variant
|
||||
Style when condition is NOT met:
|
||||
```tsx
|
||||
<div className="not-hover:opacity-75">Dims when not hovered</div>
|
||||
<div className="not-first:mt-4">Margin except first child</div>
|
||||
<div className="not-disabled:cursor-pointer">Clickable when enabled</div>
|
||||
```
|
||||
|
||||
### @starting-style for Animations
|
||||
CSS-only enter animations without JS:
|
||||
```tsx
|
||||
<dialog className="
|
||||
transition-all duration-300
|
||||
open:opacity-100 open:scale-100
|
||||
starting:open:opacity-0 starting:open:scale-95
|
||||
">
|
||||
```
|
||||
|
||||
### inert Variant
|
||||
Style non-interactive elements:
|
||||
```tsx
|
||||
<div className="inert:opacity-50 inert:pointer-events-none">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3D Transforms
|
||||
|
||||
```tsx
|
||||
<div className="perspective-distant">
|
||||
<div className="rotate-x-12 rotate-y-6 transform-3d hover:rotate-y-12">
|
||||
3D card effect
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Available utilities:
|
||||
- `rotate-x-*`, `rotate-y-*`, `rotate-z-*`
|
||||
- `translate-z-*`, `scale-z-*`
|
||||
- `perspective-normal` (500px), `perspective-distant` (1200px)
|
||||
- `transform-3d` (enables 3D space)
|
||||
|
||||
---
|
||||
|
||||
## Gradients
|
||||
|
||||
### Linear Gradients
|
||||
```tsx
|
||||
// Angle-based
|
||||
<div className="bg-linear-45 from-red-500 to-blue-500" />
|
||||
|
||||
// Direction-based
|
||||
<div className="bg-linear-to-r from-primary to-accent" />
|
||||
|
||||
// With color interpolation (more vivid colors)
|
||||
<div className="bg-linear-to-r/oklch from-red-500 to-blue-500" />
|
||||
```
|
||||
|
||||
### Radial & Conic
|
||||
```tsx
|
||||
<div className="bg-radial from-white to-transparent" />
|
||||
<div className="bg-conic from-red-500 via-yellow-500 to-red-500" />
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing Custom CSS
|
||||
|
||||
### In @layer base
|
||||
For global resets and element defaults:
|
||||
```css
|
||||
@layer base {
|
||||
* {
|
||||
@apply border-border;
|
||||
}
|
||||
|
||||
body {
|
||||
@apply bg-background text-foreground font-mono;
|
||||
}
|
||||
|
||||
button:focus-visible {
|
||||
outline: 2px solid hsl(var(--ring));
|
||||
outline-offset: 2px;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### With @utility
|
||||
For reusable utility classes:
|
||||
```css
|
||||
@utility text-balance {
|
||||
text-wrap: balance;
|
||||
}
|
||||
|
||||
@utility glass {
|
||||
background: hsl(var(--background) / 0.8);
|
||||
backdrop-filter: blur(8px);
|
||||
}
|
||||
```
|
||||
|
||||
### Plain CSS (non-Tailwind)
|
||||
For third-party component overrides (like Mosaic):
|
||||
```css
|
||||
/* No @layer needed - uses native cascade */
|
||||
.mosaic-window .mosaic-window-toolbar {
|
||||
background: hsl(var(--muted));
|
||||
border-bottom: 1px solid hsl(var(--border));
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO:
|
||||
- Use semantic color tokens (`bg-primary`) not raw colors
|
||||
- Use container queries for component responsiveness
|
||||
- Use `@utility` for custom utilities
|
||||
- Use HSL variable pattern with opacity: `hsl(var(--color) / 0.5)`
|
||||
- Keep custom CSS minimal - prefer Tailwind classes
|
||||
|
||||
### DON'T:
|
||||
- Hardcode colors (`bg-blue-500`) - use theme tokens
|
||||
- Use viewport queries when container queries work better
|
||||
- Use `@layer utilities` (v3 syntax) - use `@utility`
|
||||
- Use bracket syntax for CSS vars (`[--var]`) - use parentheses `(--var)`
|
||||
- Put `!` at the start (`!flex`) - put at end (`flex!`)
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── index.css # Main CSS: @import "tailwindcss", @theme, @utility, custom CSS
|
||||
├── styles/
|
||||
│ └── prism-theme.css # Syntax highlighting (uses CSS variables)
|
||||
├── components/
|
||||
│ └── command-launcher.css # Command palette styles
|
||||
└── lib/themes/
|
||||
├── types.ts # Theme TypeScript types
|
||||
├── apply.ts # Runtime theme application
|
||||
└── builtin/ # Built-in theme definitions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Theme Development
|
||||
|
||||
When creating or modifying themes, edit files in `src/lib/themes/builtin/`:
|
||||
|
||||
```typescript
|
||||
// src/lib/themes/builtin/my-theme.ts
|
||||
import type { Theme } from "../types";
|
||||
|
||||
export const myTheme: Theme = {
|
||||
id: "my-theme",
|
||||
name: "My Theme",
|
||||
colors: {
|
||||
background: "220 20% 10%", // HSL without wrapper
|
||||
foreground: "220 10% 90%",
|
||||
// ... all required colors
|
||||
},
|
||||
syntax: { /* ... */ },
|
||||
scrollbar: { /* ... */ },
|
||||
gradient: { /* ... */ },
|
||||
};
|
||||
```
|
||||
|
||||
Register in `src/lib/themes/builtin/index.ts`.
|
||||
|
||||
---
|
||||
|
||||
## Quick Debugging
|
||||
|
||||
Check what CSS variables are set:
|
||||
```javascript
|
||||
// In browser console
|
||||
getComputedStyle(document.documentElement).getPropertyValue('--background')
|
||||
```
|
||||
|
||||
List all theme variables:
|
||||
```javascript
|
||||
import { getThemeVariables } from '@/lib/themes/apply';
|
||||
console.log(getThemeVariables());
|
||||
```
|
||||
Reference in New Issue
Block a user