Thank You for Your Purchase! 🙏

We're thrilled that you've chosen Nomad Store for your digital products ecommerce platform. This comprehensive documentation will help you get started quickly and make the most of all the features we've built for you.

Introduction

Nomad Store is a modern, full-featured ecommerce platform built specifically for selling digital products. It's designed to handle software licenses, digital downloads, courses, templates, and other digital assets with ease.

Built with cutting-edge technologies, Nomad Store provides a complete solution for digital product sales, including payment processing, user management, order tracking, and much more.

Requirements

Before you begin, ensure you have the following installed on your system:

System Requirements

• Node.js >= 18.17.0
• pnpm 8 or higher
• Supabase Account (free tier works)

Optional but Recommended

• VS Code or your preferred code editor

Installation

Follow these steps to get Nomad Store up and running on your local machine:

Step 1: Extract the Project Files

You should have received a folder containing all the project files. Extract it to your desired location if it's compressed (ZIP, RAR, etc.).

# Navigate to the project folder
cd path/to/NOMADSTORE

Or simply open the folder in your terminal/command prompt.

Step 2: Install Dependencies

Install all required packages using pnpm:

pnpm install

npm install -g pnpm

Step 3: Set Up Environment Variables

Copy the example environment file and configure it:

cp .env.example .env.local

Then edit .env.local and add your Supabase credentials (see Configuration section below).

Step 4: Set Up Supabase

1. Create a new project at database.new
2. Get your project URL and API keys from Settings → API
3. Add them to your .env.local file (see Configuration section below)

Step 5: Run the Development Server

pnpm dev

Open http://localhost:3000 in your browser.

Configuration

Configure your environment variables and application settings.

Environment Variables

Create a .env.local file in the root directory with the following variables:

# Supabase Configuration
NEXT_PUBLIC_SUPABASE_URL=your-project-url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key

# Service Role Key (for admin operations only - NEVER expose to client)
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key_here

Where to Find Supabase Credentials

1. Go to your Supabase Dashboard
2. Select your project
3. Navigate to Settings → API
4. Copy the following:
   • Project URL → NEXT_PUBLIC_SUPABASE_URL
   • anon public key → NEXT_PUBLIC_SUPABASE_ANON_KEY
   • service_role key (secret) → SUPABASE_SERVICE_ROLE_KEY

Optional Environment Variables

Configuring GitHub OAuth Login

To enable GitHub login/signup, you need to configure GitHub OAuth in Supabase. All settings are managed in the Supabase dashboard.

Step 1: Create a GitHub OAuth App

1. Go to GitHub and navigate to Settings → Developer settings → OAuth Apps
   • For personal accounts: https://github.com/settings/developers
   • For organizations: https://github.com/organizations/YOUR_ORG/settings/developers
2. Click New OAuth App
3. Fill in the application details:
   • Application name: Nomad Store (or your preferred name)
   • Homepage URL: Your site URL (e.g., https://your-domain.com or http://localhost:3000 for local development)
   • Authorization callback URL:
     • For production: https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback
     • Replace YOUR_PROJECT_REF with your Supabase project reference ID (found in Supabase Dashboard → Settings → General)
4. Click Register application
5. Copy the Client ID and generate a Client Secret:
   • Click Generate a new client secret
   • Save the Client Secret immediately (you won't be able to see it again)

Step 2: Configure GitHub Provider in Supabase

1. Go to your Supabase Dashboard
2. Select your project
3. Navigate to Authentication → Providers in the left sidebar
4. Find GitHub in the list of providers and click on it
5. Enable GitHub provider by toggling the Enable GitHub provider switch
6. Enter your GitHub OAuth credentials:
   • Client ID (for OAuth App): Paste your GitHub Client ID
   • Client Secret (for OAuth App): Paste your GitHub Client Secret
7. Click Save

Step 3: Configure Redirect URLs in Supabase

1. In Supabase Dashboard, go to Authentication → URL Configuration
2. Add your site URLs to the Redirect URLs list:
   • For local development: http://localhost:3000/api/auth/callback
   • For production: https://your-domain.com/api/auth/callback
3. Set your Site URL:
   • Development: http://localhost:3000
   • Production: https://your-domain.com
4. Click Save

Step 4: Test GitHub Login

1. Start your development server: pnpm dev
2. Navigate to http://localhost:3000/login
3. Click Sign in with GitHub or Sign up with GitHub
4. You should be redirected to GitHub to authorize the application
5. After authorization, you should be redirected back and logged in

Troubleshooting GitHub OAuth

Error: "redirect_uri_mismatch"

• Verify that your GitHub OAuth App callback URL is: https://YOUR_PROJECT_REF.supabase.co/auth/v1/callback
• Check that your Supabase project reference ID is correct (found in Settings → General)
• Make sure there are no trailing slashes or typos

Error: "Invalid client credentials"

• Verify that you've copied the correct Client ID from GitHub
• Generate a new Client Secret in GitHub if needed
• Update the credentials in Supabase Authentication → Providers → GitHub

Available Commands

All commands use pnpm as the package manager.

Development Commands

Testing Commands

Build & Analysis

Project Structure

Understanding the project structure will help you navigate and customize the codebase.

NOMADSTORE/
├── src/
│   ├── app/                    # Next.js App Router pages
│   │   ├── admin/              # Admin dashboard pages
│   │   ├── api/                # API routes
│   │   ├── dashboard/          # User dashboard
│   │   ├── products/           # Product pages
│   │   └── ...
│   ├── components/             # React components
│   │   ├── admin/              # Admin-specific components
│   │   ├── ui/                 # shadcn/ui components
│   │   └── ...
│   ├── utils/                  # Utility functions
│   ├── hooks/                  # Custom React hooks
│   └── providers/              # Context providers
├── supabase/
│   ├── migrations/             # Database migrations
│   ├── init_database.sql       # Complete database schema
│   └── scripts/                # Supabase scripts
├── public/                     # Static assets
├── scripts/                     # Build and utility scripts
├── .env.example                # Environment variables template
├── package.json                # Dependencies and scripts
└── next.config.js              # Next.js configuration

Key Directories

• src/app/ - All pages and API routes using Next.js App Router
• src/components/ - Reusable React components
• src/utils/ - Helper functions and utilities
• supabase/migrations/ - Database migration files
• public/ - Static files (images, fonts, etc.)

Database Setup

Setting up the database and creating your admin account.

Setting Up the Database

To set up your database, you need to run the SQL initialization script in Supabase:

1. Open the file supabase/init_database.sql in your project folder
2. Select all the content (Ctrl+A or Cmd+A)
3. Copy the entire content (Ctrl+C or Cmd+C)
4. Go to your Supabase Dashboard
5. Navigate to SQL Editor in the left sidebar
6. Click on New Query or open the SQL Editor
7. Paste the entire content you copied (Ctrl+V or Cmd+V)
8. Click the Run button (or press Ctrl+Enter / Cmd+Enter)
9. Wait for the script to complete - this may take a few minutes

Creating Your Admin Account

After setting up the database, you need to promote your user account to admin:

1. Sign up for an account on your site (or use GitHub OAuth)
2. Go to your Supabase Dashboard → SQL Editor
3. Run this SQL query (replace your-email@example.com with your actual email address):

UPDATE public.user_profiles
SET role = 'admin', updated_at = NOW()
WHERE id = (
  SELECT id FROM auth.users WHERE email = 'your-email@example.com'
);

Click Run to execute the query.

Verifying Admin Access

1. Log out from your account
2. Log back in (important for session refresh)
3. Navigate to /admin - you should see the admin dashboard

Features Overview

Nomad Store comes with a comprehensive set of features out of the box.

Core Features

• Product Management - Create, edit, and manage digital products
• Category System - Organize products with categories and custom icons
• Order Management - Track orders, payments, and customer information
• User Authentication - Email/password and GitHub OAuth
• Role-Based Access - Admin and buyer roles with different permissions
• Payment Processing - Stripe and PayPal integration
• Digital Downloads - Secure file delivery system
• Email Notifications - Automated emails for orders, tickets, etc.
• Review System - Product reviews and ratings
• Rewards Program - Points, gifts, and referral system
• Support Tickets - Customer support ticket system
• Promo Codes - Discount codes and coupons
• 2FA Security - Two-factor authentication for enhanced security

Admin Dashboard

The admin dashboard provides complete control over your store.

Accessing the Dashboard

Navigate to /admin after logging in as an admin user.

Dashboard Sections

• Overview - Store statistics and recent orders
• Store - Product and category management
• Orders - View and manage all orders
• Users - User management (disabled in demo mode)
• Reviews - Manage product reviews
• Rewards - Configure rewards program
• Promo Codes - Create and manage discount codes
• Referrals - Referral program management
• Tickets - Customer support tickets
• System Settings - Configure system-wide settings
• Email Templates - Customize email templates
• Features - Enable/disable features

Payment Gateways

Nomad Store supports multiple payment gateways for flexible payment processing.

Supported Gateways

• Stripe - Credit cards, Apple Pay, Google Pay
• PayPal - PayPal payments and subscriptions
• HoodPay - Custom payment gateway plugin

Configuring Payment Gateways

Configure payment gateways from the admin dashboard:

1. Go to Admin → System → Payment Gateway
2. Enter your API keys and credentials
3. Test the connection
4. Enable the gateway

Email System

Nomad Store includes a comprehensive email notification system.

Email Templates

Manage email templates from Admin → Email Templates:

• Welcome emails
• Order confirmations
• New order notifications
• Ticket notifications

SMTP Configuration

Configure SMTP settings from Admin → System → SMTP Settings:

• SMTP host and port
• Authentication credentials
• From email and name

Deployment

Deploy your Nomad Store to production.

Vercel Deployment (Recommended)

1. Upload your project folder to a Git repository (GitHub, GitLab, etc.) if you want to use Vercel's Git integration, or use Vercel CLI
2. Import your project in Vercel (via Git or CLI)
3. Add environment variables in Vercel dashboard
4. Deploy!

Environment Variables for Production

Make sure to set these in your deployment platform:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• NEXT_PUBLIC_SITE_URL (your production URL)

Pre-Deployment Checklist

• ✅ All migrations applied to production database
• ✅ Environment variables configured
• ✅ Payment gateway keys set (production keys)
• ✅ SMTP settings configured
• ✅ Admin account created
• ✅ Custom domain configured (if applicable)
• ✅ SSL certificate active

Troubleshooting

Common issues and their solutions.

Database Connection Issues

Problem: Cannot connect to Supabase

Solution:

• Verify your .env.local has correct Supabase credentials
• Check that your Supabase project is active
• Ensure your IP is not blocked in Supabase dashboard

Migration Errors

Problem: Database setup fails

Solution:

• Check that you've copied the entire content of supabase/init_database.sql into the Supabase SQL Editor
• Verify that your Supabase project is active and accessible
• Check the Supabase SQL Editor logs for any error messages

Admin Access Denied

Problem: Cannot access admin panel after promoting

Solution:

• Clear browser cache and cookies
• Log out and log back in
• Check the debug page: /debug-admin
• Verify role in database: SELECT role FROM user_profiles WHERE id = 'your-user-id'

Build Errors

Problem: Build fails with TypeScript errors

Solution:

• Run pnpm type-check to see all errors
• Ensure all dependencies are installed: pnpm install
• Clear Next.js cache: rm -rf .next

Payment Gateway Issues

Problem: Payments not processing

Solution:

• Verify API keys are correct
• Check you're using test keys in development
• Review payment gateway logs in admin dashboard
• Test with test card numbers (Stripe) or sandbox account (PayPal)

Roadmap

This roadmap outlines potential future features and enhancements for Nomad Store. These features are subject to change based on user feedback and development priorities.

T4 2025 | T1 2026

• • Multi-language support (i18n)
• • Multi-currency support
• • Recurring subscriptions
• • Advanced coupon system
• • Integration with more payment gateways
• • Public REST API
• • Customizable webhooks
• • Advanced analytics
• • Data export
• • Maintenance mode
• • Advanced tagging system
• • Improved search
• • Advanced product filters
• • Wishlist/Favorites
• • Product comparison
• • Product comments system
• • Integrated blog
• • Customizable pages
• • Marketing integration (email campaigns)
• • Detailed financial reports
• • Accounting integration

Need Help? We're Here for You

If you have any questions, need assistance, or want to connect with other users, join our Discord community!