Skip to main content

Local Development Guide — PhotoSwipe Pro

The "Backend Not Configured" Error​

If you see this error when clicking "Buy Now":

Setup Required: Demo mode: Backend not configured

This is expected in local development. Here's why and how to fix it:

Why This Happens​

The checkout flow requires:

  1. LemonSqueezy store (payment processor)
  2. Backend API (to proxy requests securely)
  3. Environment variables (API keys, store IDs)

None of these exist in a fresh clone. You have 3 options:

Option 1: Mock Mode (Quick Demo)​

Use this to: See the UI without setting up payments

The checkout page already shows pricing and UI. The error message is informative and links to setup docs. No changes needed for demo purposes.

What works:

  • ✅ Browse /checkout page
  • ✅ See pricing tiers
  • ✅ View UI/UX
  • ✅ Test navigation

What doesn't work:

  • ❌ Actually purchasing
  • ❌ Receiving license keys

Option 2: Local Backend (Full Development)​

Use this to: Test complete purchase flow locally

Step 1: Set up LemonSqueezy Test Mode​

  1. Create LemonSqueezy account (free): https://lemonsqueezy.com
  2. Go to Settings → API → Create API key
  3. Create test products (Site, Agency)
  4. Get test variant IDs

Step 2: Configure Environment​

Create server/.env:

# LemonSqueezy Test Credentials
LEMON_SQUEEZY_API_KEY=test_your_key_here
LEMON_SQUEEZY_STORE_ID=12345
LEMON_SQUEEZY_VARIANT_ID_SITE=67890
LEMON_SQUEEZY_VARIANT_ID_AGENCY=67891
LEMON_SQUEEZY_PRODUCT_ID=your_product_id

# Local development
NODE_ENV=development
PORT=3001
ALLOWED_ORIGINS=http://localhost:3000

Step 3: Install and Start Backend​

# Install dependencies
cd server
npm install

# Start backend
npm run dev

Backend runs on http://localhost:3001

Step 4: Configure Frontend Proxy​

Add to demo-docs-website/docusaurus.config.js:

module.exports = {
  // ... existing config
  
  // Add proxy for local development
  webpack: {
    configure: (config) => {
      config.devServer = {
        ...config.devServer,
        proxy: {
          '/api': {
            target: 'http://localhost:3001',
            changeOrigin: true,
          },
        },
      };
      return config;
    },
  },
};

Step 5: Start Docs Site​

cd demo-docs-website
npm install
npm start

Site runs on http://localhost:3000

Step 6: Enable API Mode​

Update demo-docs-website/src/pages/checkout.mdx:

- <CheckoutHandler>
+ <CheckoutHandler mode="api">
    <PricingTable ctaText="Buy Now" highlightPopular />
  </CheckoutHandler>

Step 7: Test​

  1. Visit http://localhost:3000/checkout
  2. Click "Buy Now"
  3. Should redirect to LemonSqueezy test checkout
  4. Use test card: 4242 4242 4242 4242
  5. Complete purchase
  6. Verify email with license key

Option 3: Production Deployment​

Use this to: Accept real payments

Follow the complete Deployment Guide:

  1. Set up production LemonSqueezy store
  2. Deploy backend to Vercel/Railway/Fly.io
  3. Set production environment variables
  4. Deploy docs site
  5. Update DNS
  6. Test with real purchase

Estimated time: 2-4 hours

Troubleshooting​

"Failed to create checkout session"​

Cause: Backend can't reach LemonSqueezy API

Fix:

  1. Check backend logs: npm run dev (see errors)
  2. Verify API key: curl https://api.lemonsqueezy.com/v1/stores -H "Authorization: Bearer YOUR_KEY"
  3. Check variant IDs exist in your LS store

"Network error" / "fetch failed"​

Cause: Frontend can't reach backend

Fix:

  1. Verify backend is running: curl http://localhost:3001/health
  2. Check proxy configuration in docusaurus.config.js
  3. Check CORS headers in server/index.js

"No checkout URL returned"​

Cause: LemonSqueezy API returned success but no URL

Fix:

  1. Check backend response: Add console.log(data) in server/payment/router.js
  2. Verify variant ID is correct for your store
  3. Check store is in "test mode" for development

Environment Variables Reference​

Required for Checkout​

LEMON_SQUEEZY_API_KEY=     # From LS Settings → API
LEMON_SQUEEZY_STORE_ID=    # From LS dashboard URL
LEMON_SQUEEZY_VARIANT_ID_SITE=   # From product variant
LEMON_SQUEEZY_VARIANT_ID_AGENCY= # From product variant

Optional​

LEMON_SQUEEZY_PRODUCT_ID=  # For license validation
PORT=3001                  # Backend port (default: 3001)
ALLOWED_ORIGINS=*          # CORS origins (use specific domains in production)
NODE_ENV=development       # Environment mode

Quick Start Commands​

Full stack (backend + frontend):

# Terminal 1: Backend
cd server
npm install
npm run dev

# Terminal 2: Frontend
cd demo-docs-website
npm install
npm start

Backend only (test API):

cd server
npm install
npm run dev

# Test endpoints
curl http://localhost:3001/health
curl http://localhost:3001/api/payment/health
curl -X POST http://localhost:3001/api/payment/checkout \
  -H "Content-Type: application/json" \
  -d '{"productId":"site"}'

Next Steps​

  1. For demo/development: Leave as-is (error message is informative)
  2. For local testing: Follow Option 2 (Local Backend)
  3. For production: Follow Deployment Guide

Still Stuck?​

Check:

Or create an issue on GitHub.