/marketplace-nostr

Primary LanguageTypeScript

MKStack - Nostr Client Application

A modern Nostr client application built with React 18.x, TailwindCSS 3.x, Vite, shadcn/ui, and Nostrify.

Features

  • 🚀 Built with React 18 and TypeScript for type-safe development
  • 💨 Fast development with Vite
  • 🎨 Styled with TailwindCSS 3.x and shadcn/ui components
  • 🔐 Nostr protocol integration with Nostrify
  • 📱 Responsive design
  • 🔄 Real-time data with TanStack Query
  • 🎯 Client-side routing with React Router
  • 🔌 Extensible architecture with custom hooks

Prerequisites

Before you begin, ensure you have the following installed:

  • Node.js (v16 or higher)
  • npm (comes with Node.js)
  • Git

Getting Started

1. Clone the Repository

git clone <your-repository-url>
cd marketplace

2. Install Dependencies

npm install

3. Start Development Server

npm run dev

The application will be available at http://localhost:5173 (or the port shown in your terminal).

Available Scripts

Development

# Start development server
npm run dev

Testing

# Run all tests (TypeScript check, ESLint, Vitest, and build)
npm test

Building

# Build for production
npm run build

This command will:

  • Install dependencies
  • Build the application
  • Create a 404.html file for client-side routing support

Deployment

# Deploy to Surge.sh (quick deployment)
npm run deploy

This will build the application and deploy it to Surge.sh.

Deployment Options

Option 1: Surge.sh (Quick Deployment)

The project includes a built-in deploy script for Surge.sh:

npm run deploy

Follow the prompts to choose a domain name or use the suggested one.

Option 2: Vercel

  1. Install Vercel CLI:

    npm install -g vercel

  2. Deploy:

    vercel

  3. Follow the prompts to configure your deployment.

Option 3: Netlify

  1. Build the project:

    npm run build

  2. Deploy using Netlify CLI:

    npm install -g netlify-cli
netlify deploy --dir=dist

  3. For production deployment:

    netlify deploy --dir=dist --prod

Option 4: GitHub Pages

  1. Install gh-pages:

    npm install --save-dev gh-pages

  2. Add to package.json scripts:

    "predeploy": "npm run build",
"gh-deploy": "gh-pages -d dist"

  3. Deploy:

    npm run gh-deploy

Option 5: Self-Hosting

  1. Build the project:

    npm run build

  2. The dist folder contains all static files ready to be served by any web server (Nginx, Apache, etc.).

  3. Example Nginx configuration:

    server {
    listen 80;
    server_name your-domain.com;
    root /path/to/your/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Environment Variables

If you need to configure environment variables:

  1. Create a .env file in the root directory
  2. Add your environment variables prefixed with VITE_: 
    VITE_APP_NAME=My Nostr App
VITE_PUBLIC_RELAY_URL=wss://relay.example.com
  3. Access them in your code: 
    const appName = import.meta.env.VITE_APP_NAME;

Project Structure

marketplace/
├── public/              # Static assets
├── src/
│   ├── components/      # React components
│   │   ├── ui/         # shadcn/ui components
│   │   └── ...         # Custom components
│   ├── hooks/          # Custom React hooks
│   ├── lib/            # Utility functions
│   ├── pages/          # Page components
│   └── App.tsx         # Main app component
├── index.html          # Entry HTML file
├── package.json        # Dependencies and scripts
├── tsconfig.json       # TypeScript configuration
├── vite.config.ts      # Vite configuration
└── README.md          # This file

Key Features & Usage

Nostr Integration

The application includes custom hooks for Nostr protocol integration:

  • useNostr() - Access Nostr query and event publishing methods
  • useAuthor() - Fetch user profile metadata
  • useNostrPublish() - Publish events to the Nostr network
  • useCurrentUser() - Get current logged-in user information
  • useUploadFile() - Upload files with NIP-94 compatibility

Authentication

Use the built-in LoginArea component for Nostr authentication:

import { LoginArea } from "@/components/auth/LoginArea";

function MyComponent() {
  return <LoginArea />;
}

UI Components

The project uses shadcn/ui components. Available components include:

  • Accordion, Alert, Avatar, Badge, Button, Card, Dialog, and many more
  • All components are customizable with Tailwind CSS

Development Tips

  1. Path Aliases: Use @/ prefix for imports (e.g., @/components/ui/button)
  2. Type Safety: The project uses TypeScript - ensure all code is properly typed
  3. Testing: Always run npm test before committing changes
  4. Component Library: Check /src/components/ui for available UI components
  5. Nostr Events: Use the custom hooks for all Nostr interactions

Troubleshooting

Common Issues

  1. Port already in use: If port 5173 is busy, Vite will use a different port. Check the terminal output.

  2. Build errors: Run npm test to identify TypeScript or linting issues.

  3. Nostr connection issues: Ensure you're connected to the internet and the relays are accessible.

Getting Help

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is open source and available under the MIT License.

Acknowledgments