From 33614b1dddcc5aaad9eddaaf5c2b2e70bb140c8b Mon Sep 17 00:00:00 2001 From: Alex Gleason Date: Mon, 8 Sep 2025 12:15:01 -0500 Subject: [PATCH] Add improved README --- README.md | 237 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 236 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 24402b9..e7e5690 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,238 @@ # MKStack -Template for building Nostr client application with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify. \ No newline at end of file +**The Complete Framework for Building Nostr Clients with AI** + +MKStack is an AI-powered framework for building Nostr applications with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify. Build powerful Nostr applications with AI-first development - from social feeds to private messaging, MKStack provides everything you need to create decentralized apps on the Nostr protocol. + +## ๐Ÿš€ Quick Start + +Build your Nostr app in 3 simple steps: + +### 1. Install & Create +```bash +npm install -g @getstacks/stacks +stacks mkstack +``` + +### 2. Build with AI +```bash +stacks agent +# Tell Dork AI what you want: "Build a group chat application" +``` + +### 3. Deploy Instantly +```bash +npm run deploy +# โœ… App deployed to NostrDeploy.com! +``` + +## โœจ What Makes MKStack Special + +- **๐Ÿค– AI-First Development**: Build complete Nostr apps with just one prompt using Dork AI agent +- **โšก 8 Minutes Average**: From idea to deployed application in minutes, not months +- **๐Ÿ”— 50+ NIPs Supported**: Comprehensive Nostr protocol implementation +- **๐ŸŽจ Beautiful UI**: 48+ shadcn/ui components with light/dark theme support +- **๐Ÿ” Built-in Security**: NIP-07 browser signing, NIP-44 encryption, event validation +- **๐Ÿ’ฐ Payments Ready**: Lightning zaps (NIP-57), Cashu wallets (NIP-60), Wallet Connect (NIP-47) +- **๐Ÿ“ฑ Production Ready**: TypeScript, testing, deployment, and responsive design included + +## ๐Ÿ›  Technology Stack + +- **React 18.x**: Stable version 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**: 48+ unstyled, accessible UI components built with Radix UI +- **Nostrify**: Nostr protocol framework for Deno and web +- **React Router**: Client-side routing with BrowserRouter +- **TanStack Query**: Data fetching, caching, and state management +- **TypeScript**: Type-safe JavaScript development + +## ๐ŸŽฏ Real-World Examples + +### Built with One Prompt + +Each of these applications was created with just a single prompt to Dork AI: + +- **Group Chat Application**: `"Build me a group chat application"` + - [Live Demo](https://groupchat-74z9j26wq-mks-projects-1f1254c4.vercel.app/) + +- **Decentralized Goodreads**: `"Build a decentralized goodreads alternative. Use OpenLibrary API for book data."` + - [Live Demo](https://bookstr123-87phkwjcy-mks-projects-1f1254c4.vercel.app/) + +- **Chess Game**: `"Build a chess game with NIP 64"` + - [Live Demo](https://chess-l0d7ms7m3-mks-projects-1f1254c4.vercel.app/chess) + +### Production Apps + +Real Nostr applications built using MKStack: + +- **[Chorus](https://chorus.community/)**: Facebook-style groups on Nostr with built-in eCash wallet +- **[Blobbi](https://www.blobbi.pet/)**: Digital pet companions that live forever on the decentralized web +- **[Treasures](https://treasures.to/)**: Decentralized geocaching adventure powered by Nostr + +[Browse more apps made with MKStack โ†’](https://nostrhub.io/apps/t/mkstack/) + +## ๐Ÿ”ง Core Features + +### Authentication & Users +- `LoginArea` component with account switching +- `useCurrentUser` hook for authentication state +- `useAuthor` hook for fetching user profiles +- NIP-07 browser signing support +- Multi-account management + +### Nostr Protocol Support +- **Social Features**: User profiles (NIP-01), follow lists (NIP-02), reactions (NIP-25), reposts (NIP-18) +- **Messaging**: Private DMs (NIP-17), public chat (NIP-28), group chat (NIP-29), encryption (NIP-44) +- **Payments**: Lightning zaps (NIP-57), Cashu wallets (NIP-60), Nutzaps (NIP-61), Wallet Connect (NIP-47) +- **Content**: Long-form articles (NIP-23), file metadata (NIP-94), live events (NIP-53), calendars (NIP-52) + +### Data Management +- `useNostr` hook for querying and publishing +- `useNostrPublish` hook with automatic client tagging +- Event validation and filtering +- Infinite scroll with TanStack Query +- Multi-relay support + +### UI Components +- 48+ shadcn/ui components (buttons, forms, dialogs, etc.) +- `NoteContent` component for rich text rendering +- `EditProfileForm` for profile management +- `RelaySelector` for relay switching +- `CommentsSection` for threaded discussions +- Light/dark theme system + +### Media & Files +- `useUploadFile` hook with Blossom server integration +- NIP-94 compatible file metadata +- Image and video support +- File attachment to events + +### Advanced Features +- NIP-19 identifier routing (`npub1`, `note1`, `nevent1`, `naddr1`) +- Cryptographic operations (encryption/decryption) +- Lightning payments and zaps +- Real-time event subscriptions +- Responsive design with mobile support + +## ๐Ÿค– AI Development with Dork + +MKStack includes Dork, a built-in AI agent that understands your codebase and Nostr protocols: + +### Supported AI Providers + +Configure your AI provider with `stacks configure`: + +- **OpenRouter** ([openrouter.ai](https://openrouter.ai/)): Enter your API key from settings +- **Routstr** ([routstr.com](https://www.routstr.com/)): Use Cashu tokens for payment +- **PayPerQ** ([ppq.ai](https://ppq.ai/)): OpenAI-compatible API + +### How Dork Works + +- **Context-Aware**: Understands your entire codebase and project structure +- **Nostr Expert**: Built-in knowledge of 50+ NIPs and best practices +- **Instant Implementation**: Makes changes directly to your code following React/TypeScript best practices + +Example prompts: +```bash +"Add user profiles with avatars and bio" +"Implement NIP-17 private messaging" +"Add a dark mode toggle" +"Create a marketplace with NIP-15" +``` + +## ๐Ÿ“ Project Structure + +``` +src/ +โ”œโ”€โ”€ components/ # UI components +โ”‚ โ”œโ”€โ”€ ui/ # shadcn/ui components (48+ available) +โ”‚ โ”œโ”€โ”€ auth/ # Authentication components +โ”‚ โ””โ”€โ”€ comments/ # Comment system components +โ”œโ”€โ”€ hooks/ # Custom React hooks +โ”‚ โ”œโ”€โ”€ useNostr # Core Nostr integration +โ”‚ โ”œโ”€โ”€ useAuthor # User profile data +โ”‚ โ”œโ”€โ”€ useCurrentUser # Authentication state +โ”‚ โ”œโ”€โ”€ useNostrPublish # Event publishing +โ”‚ โ”œโ”€โ”€ useUploadFile # File uploads +โ”‚ โ””โ”€โ”€ useZaps # Lightning payments +โ”œโ”€โ”€ pages/ # Page components +โ”œโ”€โ”€ lib/ # Utility functions +โ”œโ”€โ”€ contexts/ # React context providers +โ””โ”€โ”€ test/ # Testing utilities +``` + +## ๐ŸŽจ UI Components + +MKStack includes 48+ shadcn/ui components: + +**Layout**: Card, Separator, Sheet, Sidebar, ScrollArea, Resizable +**Navigation**: Breadcrumb, NavigationMenu, Menubar, Tabs, Pagination +**Forms**: Button, Input, Textarea, Select, Checkbox, RadioGroup, Switch, Slider +**Feedback**: Alert, AlertDialog, Toast, Progress, Skeleton +**Overlay**: Dialog, Popover, HoverCard, Tooltip, ContextMenu, DropdownMenu +**Data Display**: Table, Avatar, Badge, Calendar, Chart, Carousel +**And many more... + +## ๐Ÿ” Security & Best Practices + +- **Never use `any` type**: Always use proper TypeScript types +- **Event validation**: Filter events through validator functions for custom kinds +- **Efficient queries**: Minimize separate queries to avoid rate limiting +- **Proper error handling**: Graceful handling of invalid NIP-19 identifiers +- **Secure authentication**: Use signer interface, never request private keys directly + +## ๐Ÿ“ฑ Responsive Design + +- Mobile-first approach with Tailwind breakpoints +- `useIsMobile` hook for responsive behavior +- Touch-friendly interactions +- Optimized for all screen sizes + +## ๐Ÿงช Testing + +- Vitest with jsdom environment +- React Testing Library with jest-dom matchers +- `TestApp` component provides all necessary context providers +- Mocked browser APIs (matchMedia, scrollTo, IntersectionObserver, ResizeObserver) + +## ๐Ÿš€ Deployment + +Built-in deployment to NostrDeploy.com: + +```bash +npm run deploy +``` + +Your app goes live instantly with: +- Automatic builds +- CDN distribution +- HTTPS support +- Custom domains available + +## ๐Ÿ“š Documentation + +For detailed documentation on building Nostr applications with MKStack: + +- [Tutorial](https://soapbox.pub/blog/mkstack-tutorial) +- [Nostr Protocol Documentation](https://nostr.com) +- [shadcn/ui Components](https://ui.shadcn.com) + +## ๐Ÿค Contributing + +MKStack is open source and welcomes contributions. The framework is designed to be: + +- **Extensible**: Easy to add new NIPs and features +- **Maintainable**: Clean architecture with TypeScript +- **Testable**: Comprehensive testing setup included +- **Documented**: Clear patterns and examples + +## ๐Ÿ“„ License + +Open source - build amazing Nostr applications and help grow the decentralized web! + +--- + +**"Vibed with MKStack"** - [Learn more about MKStack](https://soapbox.pub/mkstack) + +*Build your Nostr app in minutes, not months. Start with AI, deploy instantly.* \ No newline at end of file