highperfocused/lumina
1
0
Fork 0
mirror of https://github.com/lumina-rocks/lumina.git synced 2026-04-23 13:29:13 +02:00
Code Issues Packages Projects Releases Wiki Activity

update README to reflect rebranding from MKStack to LUMINA and enhance feature descriptions

Browse Source
This commit is contained in:
highperfocused
2025-11-21 23:41:26 +01:00
parent 5fb9183c42
commit 2dda3075c7
1 changed files with 175 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
README.md
View File

@@ -1,144 +1,120 @@
# MKStack
# LUMINA
**The Complete Framework for Building Nostr Clients with AI**
**An Image-First Nostr Client**
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.
LUMINA is a beautiful, Instagram-inspired Nostr client built with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify. Experience the decentralized web through stunning visuals - share, discover, and interact with kind-20 image-first notes on the Nostr protocol.
## 🚀 Quick Start
## 🌟 About LUMINA
Build your Nostr app in 3 simple steps:
LUMINA brings the visual social experience to Nostr with a focus on kind-20 events - notes where images take center stage. Built for creators and visual storytellers, LUMINA combines the familiar Instagram-like interface with the power of decentralized, censorship-resistant social networking.
### 1. Install & Create
```bash
npm install -g @getstacks/stacks
stacks mkstack
```
**Visit**: [LUMINA.rocks](https://lumina.rocks)
### 2. Build with AI
```bash
stacks agent
# Tell Dork AI what you want: "Build a group chat application"
```
## ✨ Features
### 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
- **📸 Image-First Experience**: Built specifically for kind-20 notes with beautiful image galleries
- **🎨 Instagram-Like Interface**: Familiar, intuitive design for visual content
- **⚡ Lightning Fast**: Optimized performance with Vite and React 18
- **🔐 Decentralized & Private**: Your keys, your data, on the Nostr protocol
- **💰 Lightning Zaps**: Support creators with instant Bitcoin payments
- **🎨 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
- **📱 Fully Responsive**: Perfect experience on mobile, tablet, and desktop
## 🛠 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
- **React 18.x**: Modern UI with hooks and concurrent rendering
- **TailwindCSS 3.x**: Utility-first CSS for beautiful, responsive design
- **Vite**: Lightning-fast build tool and development server
- **shadcn/ui**: 48+ accessible UI components built with Radix UI
- **Nostrify**: Comprehensive Nostr protocol implementation
- **React Router**: Smooth client-side navigation
- **TanStack Query**: Efficient data fetching and caching
- **TypeScript**: Type-safe development
## 🎯 Real-World Examples
## 🎯 What are Kind-20 Notes?
### Built with One Prompt
Kind-20 events are image-first notes on Nostr where the visual content is the primary focus. Unlike traditional text posts with optional images, kind-20 notes are designed to showcase photography, art, and visual storytelling - perfect for creators who want to share their work on a decentralized platform.
Each of these applications was created with just a single prompt to Dork AI:
### Why Kind-20?
- **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/)
- **Image-Centric**: Built specifically for visual content
- **Creator-Friendly**: Perfect for photographers, artists, and visual creators
- **Decentralized**: Your content lives on Nostr relays, not centralized servers
- **Censorship-Resistant**: No platform can take down your work
- **Monetization**: Direct support through Lightning zaps
## 🔧 Core Features
### Image Gallery & Feed
- Beautiful image-first feed for kind-20 notes
- Instagram-like grid and list views
- Infinite scroll for seamless browsing
- Optimized image loading and caching
- Full-screen image viewer
### Social Interactions
- Like/react to images (NIP-25)
- Comment on posts with threaded discussions
- Share and repost visual content
- Follow your favorite creators
- User profiles with image galleries
### Content Creation
- Upload and publish kind-20 image notes
- Edit captions and metadata
- Add hashtags for discoverability
- Multiple image support
- File upload via Blossom servers (NIP-94)
### 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 login with browser extensions (NIP-07)
- Multi-account support with account switching
- Edit profile with avatar and bio
- Secure key 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)
### Payments & Zaps
- Lightning zaps to support creators (NIP-57)
- Wallet Connect integration (NIP-47)
- WebLN support for instant payments
- View zap receipts and amounts
### 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
### Technical Features
- Efficient relay management (NIP-65)
- Real-time event subscriptions
- Responsive design with mobile support
- Event validation and filtering
- Light/dark theme support
- Fully responsive mobile design
- TypeScript for type safety
## 🤖 AI Development with Dork
## 🚀 Getting Started
MKStack includes Dork, a built-in AI agent that understands your codebase and Nostr protocols:
### Prerequisites
### Supported AI Providers
- Node.js 18+ installed
- A Nostr browser extension like [Alby](https://getalby.com/) or [nos2x](https://github.com/fiatjaf/nos2x)
Configure your AI provider with `stacks configure`:
### Installation
- **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"
# Clone the repository
git clone https://github.com/lumina-rocks/lumina.git
cd lumina
# Install dependencies
npm install
# Start development server
npm run dev
```
### Building for Production
```bash
# Build the application
npm run build
# Preview the production build
npm run preview
```
## 📁 Project Structure
@@ -147,92 +123,125 @@ Example prompts:
src/
├── components/ # UI components
│ ├── ui/ # shadcn/ui components (48+ available)
│ ├── auth/ # Authentication components
│ └── comments/ # Comment system components
│ ├── auth/ # Login, signup, account switching
│ ├── comments/ # Comment system for posts
│ └── dm/ # Direct messaging components
├── hooks/ # Custom React hooks
│ ├── useNostr # Core Nostr integration
│ ├── useAuthor # User profile data
│ ├── useNostr # Core Nostr protocol integration
│ ├── useAuthor # Fetch user profiles
│ ├── useCurrentUser # Authentication state
│ ├── useNostrPublish # Event publishing
│ ├── useUploadFile # File uploads
│ ├── useNostrPublish # Publish kind-20 and other events
│ ├── useUploadFile # Upload images via Blossom
│ └── useZaps # Lightning payments
├── pages/ # Page components
├── pages/ # Page components (feed, profile, etc.)
├── lib/ # Utility functions
├── contexts/ # React context providers
└── test/ # Testing utilities
└── docs/ # Documentation for features and NIPs
```
## 🎨 UI Components
## 🎨 Design Philosophy
MKStack includes 48+ shadcn/ui components:
LUMINA combines the familiar Instagram experience with Nostr's decentralized principles:
**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
- **Visual First**: Images are the hero, with clean layouts that showcase content
- **Intuitive Navigation**: Familiar patterns for browsing, posting, and interacting
- **Beautiful Themes**: Carefully crafted light and dark modes
- **Responsive Design**: Perfect experience on any device
- **Accessible**: Built with Radix UI primitives for WCAG 2.1 AA compliance
### UI Components
Powered by 48+ shadcn/ui components for a polished, professional interface:
**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
## 🔐 Privacy & Security
- **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
- **Your Keys, Your Data**: Keys never leave your device
- **NIP-07 Security**: Browser extension signing keeps keys safe
- **End-to-End Encryption**: Private messages use NIP-44 encryption
- **No Tracking**: No analytics, no cookies, no surveillance
- **Decentralized Storage**: Content lives on Nostr relays, not our servers
## 📱 Responsive Design
## 🌐 Nostr Protocol
- Mobile-first approach with Tailwind breakpoints
- `useIsMobile` hook for responsive behavior
- Touch-friendly interactions
- Optimized for all screen sizes
LUMINA is built on the Nostr protocol - a simple, open protocol for decentralized social networking:
## 🧪 Testing
- **Censorship-Resistant**: No single point of control
- **Portable Identity**: Your identity works across all Nostr apps
- **Lightning-Native**: Built-in Bitcoin payments via Lightning Network
- **Open Source**: Transparent, auditable code
- **Interoperable**: Content visible in other Nostr clients
- 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)
Learn more: [nostr.com](https://nostr.com)
## 🚀 Deployment
## 🧪 Development
Built-in deployment to NostrDeploy.com:
### Testing
```bash
npm run deploy
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
```
Your app goes live instantly with:
- Automatic builds
- CDN distribution
- HTTPS support
- Custom domains available
Built with Vitest, React Testing Library, and comprehensive test coverage.
## 📚 Documentation
### Code Quality
For detailed documentation on building Nostr applications with MKStack:
```bash
# Type checking
npx tsc --noEmit
- [Tutorial](https://soapbox.pub/blog/mkstack-tutorial)
- [Nostr Protocol Documentation](https://nostr.com)
- [shadcn/ui Components](https://ui.shadcn.com)
# Linting
npm run lint
```
## 🤝 Contributing
MKStack is open source and welcomes contributions. The framework is designed to be:
LUMINA is open source and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, we'd love your help.
- **Extensible**: Easy to add new NIPs and features
- **Maintainable**: Clean architecture with TypeScript
- **Testable**: Comprehensive testing setup included
- **Documented**: Clear patterns and examples
### Ways to Contribute
- **Report Bugs**: Open an issue with details and steps to reproduce
- **Suggest Features**: Share your ideas for making LUMINA better
- **Submit Pull Requests**: Fix bugs, add features, or improve code
- **Improve Documentation**: Help others understand and use LUMINA
- **Share Feedback**: Tell us what you love and what could be better
### Development Guidelines
- Follow TypeScript best practices
- Write tests for new features
- Follow existing code patterns
- Keep commits focused and descriptive
## 📚 Resources
- **Nostr Protocol**: [nostr.com](https://nostr.com)
- **NIP Repository**: [github.com/nostr-protocol/nips](https://github.com/nostr-protocol/nips)
- **shadcn/ui**: [ui.shadcn.com](https://ui.shadcn.com)
- **Nostrify**: [nostrify.dev](https://nostrify.dev)
## 📄 License
Open source - build amazing Nostr applications and help grow the decentralized web!
MIT License - see LICENSE file for details.
## 🙏 Acknowledgments
Built with [MKStack](https://soapbox.pub/mkstack) - the complete framework for building Nostr clients with AI.
Special thanks to the Nostr community for building an open, decentralized future for social networking.
---
**"Vibed with MKStack"** - [Learn more about MKStack](https://soapbox.pub/mkstack)
**Experience visual storytelling on the decentralized web.**
*Build your Nostr app in minutes, not months. Start with AI, deploy instantly.*
Visit [LUMINA.rocks](https://lumina.rocks) | Follow updates on Nostr