# Project Overview
This project is a Nostr client application built with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify.
## Technology Stack
- **React 18.x**: Stable version of React with hooks, concurrent rendering, and improved performance
- **TailwindCSS 3.x**: Utility-first CSS framework for styling
- **Vite**: Fast build tool and development server
- **shadcn/ui**: Unstyled, accessible UI components built with Radix UI and Tailwind
- **Nostrify**: Nostr protocol framework for Deno and web
- **React Router**: For client-side routing
- **TanStack Query**: For data fetching, caching, and state management
- **TypeScript**: For type-safe JavaScript development
## Project Structure
- `/src/components/`: UI components including NostrProvider for Nostr integration
- `/src/hooks/`: Custom hooks including `useNostr` and `useNostrQuery`
- `/src/pages/`: Page components used by React Router
- `/src/lib/`: Utility functions and shared logic
- `/public/`: Static assets
## UI Components
The project uses shadcn/ui components located in `@/components/ui`. These are unstyled, accessible components built with Radix UI and styled with Tailwind CSS. Available components include:
- **Accordion**: Vertically collapsing content panels
- **Alert**: Displays important messages to users
- **AlertDialog**: Modal dialog for critical actions requiring confirmation
- **AspectRatio**: Maintains consistent width-to-height ratio
- **Avatar**: User profile pictures with fallback support
- **Badge**: Small status descriptors for UI elements
- **Breadcrumb**: Navigation aid showing current location in hierarchy
- **Button**: Customizable button with multiple variants and sizes
- **Calendar**: Date picker component
- **Card**: Container with header, content, and footer sections
- **Carousel**: Slideshow for cycling through elements
- **Chart**: Data visualization component
- **Checkbox**: Selectable input element
- **Collapsible**: Toggle for showing/hiding content
- **Command**: Command palette for keyboard-first interfaces
- **ContextMenu**: Right-click menu component
- **Dialog**: Modal window overlay
- **Drawer**: Side-sliding panel
- **DropdownMenu**: Menu that appears from a trigger element
- **Form**: Form validation and submission handling
- **HoverCard**: Card that appears when hovering over an element
- **InputOTP**: One-time password input field
- **Input**: Text input field
- **Label**: Accessible form labels
- **Menubar**: Horizontal menu with dropdowns
- **NavigationMenu**: Accessible navigation component
- **Pagination**: Controls for navigating between pages
- **Popover**: Floating content triggered by a button
- **Progress**: Progress indicator
- **RadioGroup**: Group of radio inputs
- **Resizable**: Resizable panels and interfaces
- **ScrollArea**: Scrollable container with custom scrollbars
- **Select**: Dropdown selection component
- **Separator**: Visual divider between content
- **Sheet**: Side-anchored dialog component
- **Sidebar**: Navigation sidebar component
- **Skeleton**: Loading placeholder
- **Slider**: Input for selecting a value from a range
- **Sonner**: Toast notification manager
- **Switch**: Toggle switch control
- **Table**: Data table with headers and rows
- **Tabs**: Tabbed interface component
- **Textarea**: Multi-line text input
- **Toast**: Toast notification component
- **ToggleGroup**: Group of toggle buttons
- **Toggle**: Two-state button
- **Tooltip**: Informational text that appears on hover
These components follow a consistent pattern using React's `forwardRef` and use the `cn()` utility for class name merging. Many are built on Radix UI primitives for accessibility and customized with Tailwind CSS.
## Nostr Protocol Integration
This project comes with custom hooks for querying and publishing events on the Nostr network.
### The `useNostr` Hook
The `useNostr` hook returns an object containing a `nostr` property, with `.query()` and `.event()` methods for querying and publishing Nostr events respectively.
```typescript
import { useNostr } from '@nostrify/react';
function useCustomHook() {
const { nostr } = useNostr();
// ...
}
```
### Query Nostr Data with `useNostr` and Tanstack Query
When querying Nostr, the best practice is to create custom hooks that combine `useNostr` and `useQuery` to get the required data.
```typescript
import { useNostr } from '@nostrify/react';
import { useQuery } from '@tanstack/query';
function usePosts() {
const { nostr } = useNostr();
return useQuery({
queryKey: ['posts'],
queryFn: async (c) => {
const signal = AbortSignal.any([c.signal, AbortSignal.timeout(1500)]);
const events = await nostr.query([{ kinds: [1], limit: 20 }], { signal });
return events; // these events could be transformed into another format
},
});
}
```
The data may be transformed into a more appropriate format if needed, and multiple calls to `nostr.query()` may be made in a single queryFn.
### The `useAuthor` Hook
To display profile data for a user by their Nostr pubkey (such as an event author), use the `useAuthor` hook.
```tsx
import { NostrEvent, NostrMetadata } from '@nostrify/nostrify';
import { useAuthor } from '@/hooks/useAuthor';
function Post({ event }: { event: NostrEvent }) {
const author = useAuthor(event.pubkey);
const metadata: NostrMetadata | undefined = author.data?.metadata;
const displayName = metadata?.name || event.pubkey.slice(0, 8);
const profileImage = metadata?.picture;
// ...render elements with this data
}
```
#### `NostrMetadata` type
```ts
/** Kind 0 metadata. */
interface NostrMetadata {
/** A short description of the user. */
about?: string;
/** A URL to a wide (~1024x768) picture to be optionally displayed in the background of a profile screen. */
banner?: string;
/** A boolean to clarify that the content is entirely or partially the result of automation, such as with chatbots or newsfeeds. */
bot?: boolean;
/** An alternative, bigger name with richer characters than `name`. `name` should always be set regardless of the presence of `display_name` in the metadata. */
display_name?: string;
/** A bech32 lightning address according to NIP-57 and LNURL specifications. */
lud06?: string;
/** An email-like lightning address according to NIP-57 and LNURL specifications. */
lud16?: string;
/** A short name to be displayed for the user. */
name?: string;
/** An email-like Nostr address according to NIP-05. */
nip05?: string;
/** A URL to the user's avatar. */
picture?: string;
/** A web URL related in any way to the event author. */
website?: string;
}
```
### The `useNostrPublish` Hook
To publish events, use the `useNostrPublish` hook in this project.
```tsx
import { useState } from 'react';
import { useCurrentUser } from "@/hooks/useCurrentUser";
import { useNostrPublish } from '@/hooks/useNostrPublish';
export function MyComponent() {
const [ data, setData] = useState
>({});
const { user } = useCurrentUser();
const { mutate: createEvent } = useNostrPublish();
const handleSubmit = () => {
createEvent({ kind: 1, content: data.content });
};
if (!user) {
return You must be logged in to use this form.;
}
return (
);
}
```
The `useCurrentUser` hook should be used to ensure that the user is logged in before they are able to publish Nostr events.
### Nostr Login
To enable login with Nostr, simply use the `LoginArea` component already included in this project.
```tsx
import { LoginArea } from "@/components/auth/LoginArea";
function MyComponent() {
return (
{/* other components ... */}
);
}
```
The `LoginArea` component displays a "Log in" button when the user is logged out, and changes to an account switcher once the user is logged in. It handles all the login-related UI and interactions internally, including displaying login dialogs and switching between accounts.
## `npub`, `naddr`, and other Nostr addresses
Nostr defines a set identifiers in NIP-19. Their prefixes:
- `npub`: public keys
- `nsec`: private keys
- `note`: note ids
- `nprofile`: a nostr profile
- `nevent`: a nostr event
- `naddr`: a nostr replaceable event coordinate
- `nrelay`: a nostr relay (deprecated)
NIP-19 identifiers include a prefix, the number "1", then a base32-encoded data string.
### Use in Filters
The base Nostr protocol uses hex string identifiers for filtering by event IDs, pubkeys, and signatures. Nostr filters only accept hex strings.
```ts
// ❌ Wrong: naddr is not decoded
const events = await nostr.query(
[{ ids: [naddr] }],
{ signal }
);
```
Corrected example:
```ts
// Import nip19 from nostr-tools
import { nip19 } from 'nostr-tools';
// Decode a NIP-19 identifier
const decoded = nip19.decode(value);
// Optional: guard certain types
if (decoded.type !== 'naddr') {
throw new Error('Invalid stack ID');
}
// Get the addr object
const naddr = decoded.data;
// ✅ Correct: naddr is expanded into the correct filter
const events = await nostr.query(
[{
kinds: [naddr.kind],
authors: [naddr.pubkey],
'#d': [naddr.identifier],
}],
{ signal }
);
```
## Development Practices
- Uses React Query for data fetching and caching
- Follows shadcn/ui component patterns
- Implements Path Aliases with `@/` prefix for cleaner imports
- Uses Vite for fast development and production builds
- Component-based architecture with React hooks
- Default connection to multiple Nostr relays for network redundancy
## Build & Deployment
- Build for production: `npm run build`
- Development build: `npm run build:dev`
## Testing Your Changes
Whenever you modify code, you should test your changes after you're finished by running:
```bash
npm run ci
```
This command will typecheck the code and attempt to build it.
Your task is not considered finished until this test passes without errors.
@ Derek Ross
2025-05-15 15:03:02# Project Overview This project is a Nostr client application built with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify. ## Technology Stack - **React 18.x**: Stable version of React with hooks, concurrent rendering, and improved performance - **TailwindCSS 3.x**: Utility-first CSS framework for styling - **Vite**: Fast build tool and development server - **shadcn/ui**: Unstyled, accessible UI components built with Radix UI and Tailwind - **Nostrify**: Nostr protocol framework for Deno and web - **React Router**: For client-side routing - **TanStack Query**: For data fetching, caching, and state management - **TypeScript**: For type-safe JavaScript development ## Project Structure - `/src/components/`: UI components including NostrProvider for Nostr integration - `/src/hooks/`: Custom hooks including `useNostr` and `useNostrQuery` - `/src/pages/`: Page components used by React Router - `/src/lib/`: Utility functions and shared logic - `/public/`: Static assets ## UI Components The project uses shadcn/ui components located in `@/components/ui`. These are unstyled, accessible components built with Radix UI and styled with Tailwind CSS. Available components include: - **Accordion**: Vertically collapsing content panels - **Alert**: Displays important messages to users - **AlertDialog**: Modal dialog for critical actions requiring confirmation - **AspectRatio**: Maintains consistent width-to-height ratio - **Avatar**: User profile pictures with fallback support - **Badge**: Small status descriptors for UI elements - **Breadcrumb**: Navigation aid showing current location in hierarchy - **Button**: Customizable button with multiple variants and sizes - **Calendar**: Date picker component - **Card**: Container with header, content, and footer sections - **Carousel**: Slideshow for cycling through elements - **Chart**: Data visualization component - **Checkbox**: Selectable input element - **Collapsible**: Toggle for showing/hiding content - **Command**: Command palette for keyboard-first interfaces - **ContextMenu**: Right-click menu component - **Dialog**: Modal window overlay - **Drawer**: Side-sliding panel - **DropdownMenu**: Menu that appears from a trigger element - **Form**: Form validation and submission handling - **HoverCard**: Card that appears when hovering over an element - **InputOTP**: One-time password input field - **Input**: Text input field - **Label**: Accessible form labels - **Menubar**: Horizontal menu with dropdowns - **NavigationMenu**: Accessible navigation component - **Pagination**: Controls for navigating between pages - **Popover**: Floating content triggered by a button - **Progress**: Progress indicator - **RadioGroup**: Group of radio inputs - **Resizable**: Resizable panels and interfaces - **ScrollArea**: Scrollable container with custom scrollbars - **Select**: Dropdown selection component - **Separator**: Visual divider between content - **Sheet**: Side-anchored dialog component - **Sidebar**: Navigation sidebar component - **Skeleton**: Loading placeholder - **Slider**: Input for selecting a value from a range - **Sonner**: Toast notification manager - **Switch**: Toggle switch control - **Table**: Data table with headers and rows - **Tabs**: Tabbed interface component - **Textarea**: Multi-line text input - **Toast**: Toast notification component - **ToggleGroup**: Group of toggle buttons - **Toggle**: Two-state button - **Tooltip**: Informational text that appears on hover These components follow a consistent pattern using React's `forwardRef` and use the `cn()` utility for class name merging. Many are built on Radix UI primitives for accessibility and customized with Tailwind CSS. ## Nostr Protocol Integration This project comes with custom hooks for querying and publishing events on the Nostr network. ### The `useNostr` Hook The `useNostr` hook returns an object containing a `nostr` property, with `.query()` and `.event()` methods for querying and publishing Nostr events respectively. ```typescript import { useNostr } from '@nostrify/react'; function useCustomHook() { const { nostr } = useNostr(); // ... } ``` ### Query Nostr Data with `useNostr` and Tanstack Query When querying Nostr, the best practice is to create custom hooks that combine `useNostr` and `useQuery` to get the required data. ```typescript import { useNostr } from '@nostrify/react'; import { useQuery } from '@tanstack/query'; function usePosts() { const { nostr } = useNostr(); return useQuery({ queryKey: ['posts'], queryFn: async (c) => { const signal = AbortSignal.any([c.signal, AbortSignal.timeout(1500)]); const events = await nostr.query([{ kinds: [1], limit: 20 }], { signal }); return events; // these events could be transformed into another format }, }); } ``` The data may be transformed into a more appropriate format if needed, and multiple calls to `nostr.query()` may be made in a single queryFn. ### The `useAuthor` Hook To display profile data for a user by their Nostr pubkey (such as an event author), use the `useAuthor` hook. ```tsx import { NostrEvent, NostrMetadata } from '@nostrify/nostrify'; import { useAuthor } from '@/hooks/useAuthor'; function Post({ event }: { event: NostrEvent }) { const author = useAuthor(event.pubkey); const metadata: NostrMetadata | undefined = author.data?.metadata; const displayName = metadata?.name || event.pubkey.slice(0, 8); const profileImage = metadata?.picture; // ...render elements with this data } ``` #### `NostrMetadata` type ```ts /** Kind 0 metadata. */ interface NostrMetadata { /** A short description of the user. */ about?: string; /** A URL to a wide (~1024x768) picture to be optionally displayed in the background of a profile screen. */ banner?: string; /** A boolean to clarify that the content is entirely or partially the result of automation, such as with chatbots or newsfeeds. */ bot?: boolean; /** An alternative, bigger name with richer characters than `name`. `name` should always be set regardless of the presence of `display_name` in the metadata. */ display_name?: string; /** A bech32 lightning address according to NIP-57 and LNURL specifications. */ lud06?: string; /** An email-like lightning address according to NIP-57 and LNURL specifications. */ lud16?: string; /** A short name to be displayed for the user. */ name?: string; /** An email-like Nostr address according to NIP-05. */ nip05?: string; /** A URL to the user's avatar. */ picture?: string; /** A web URL related in any way to the event author. */ website?: string; } ``` ### The `useNostrPublish` Hook To publish events, use the `useNostrPublish` hook in this project. ```tsx import { useState } from 'react'; import { useCurrentUser } from "@/hooks/useCurrentUser"; import { useNostrPublish } from '@/hooks/useNostrPublish'; export function MyComponent() { const [ data, setData] = useState{/* other components ... */}); } ``` The `LoginArea` component displays a "Log in" button when the user is logged out, and changes to an account switcher once the user is logged in. It handles all the login-related UI and interactions internally, including displaying login dialogs and switching between accounts. ## `npub`, `naddr`, and other Nostr addresses Nostr defines a set identifiers in NIP-19. Their prefixes: - `npub`: public keys - `nsec`: private keys - `note`: note ids - `nprofile`: a nostr profile - `nevent`: a nostr event - `naddr`: a nostr replaceable event coordinate - `nrelay`: a nostr relay (deprecated) NIP-19 identifiers include a prefix, the number "1", then a base32-encoded data string. ### Use in Filters The base Nostr protocol uses hex string identifiers for filtering by event IDs, pubkeys, and signatures. Nostr filters only accept hex strings. ```ts // ❌ Wrong: naddr is not decoded const events = await nostr.query( [{ ids: [naddr] }], { signal } ); ``` Corrected example: ```ts // Import nip19 from nostr-tools import { nip19 } from 'nostr-tools'; // Decode a NIP-19 identifier const decoded = nip19.decode(value); // Optional: guard certain types if (decoded.type !== 'naddr') { throw new Error('Invalid stack ID'); } // Get the addr object const naddr = decoded.data; // ✅ Correct: naddr is expanded into the correct filter const events = await nostr.query( [{ kinds: [naddr.kind], authors: [naddr.pubkey], '#d': [naddr.identifier], }], { signal } ); ``` ## Development Practices - Uses React Query for data fetching and caching - Follows shadcn/ui component patterns - Implements Path Aliases with `@/` prefix for cleaner imports - Uses Vite for fast development and production builds - Component-based architecture with React hooks - Default connection to multiple Nostr relays for network redundancy ## Build & Deployment - Build for production: `npm run build` - Development build: `npm run build:dev` ## Testing Your Changes Whenever you modify code, you should test your changes after you're finished by running: ```bash npm run ci ``` This command will typecheck the code and attempt to build it. Your task is not considered finished until this test passes without errors.