Documentation

FAQ

Frequently asked questions about ShipSecure boilerplate.

General Questions

What is ShipSecure?

ShipSecure is a security-first SaaS boilerplate built with Next.js 16. It provides a solid foundation for building secure web applications with authentication, billing, and essential security features pre-configured and tested.

Who is ShipSecure for?

ShipSecure is designed for:

  • Indie hackers building their first SaaS
  • Developers who want security best practices out of the box
  • Startups that need to ship fast without compromising security
  • Agencies building MVPs for clients

What's included?

  • Next.js 16 with App Router
  • Authentication (GitHub & Google OAuth)
  • Database (PostgreSQL + Prisma)
  • Security headers & rate limiting
  • Gumroad payments + GitHub delivery
  • Landing page with customizable config
  • Test suite (Vitest + Playwright)
  • Documentation

Is this open source?

ShipSecure is a paid boilerplate that you can customize freely after purchase. You get full source code access and can modify it however you like for your projects.

Installation & Setup

What are the requirements?

  • Node.js 18+ (check with node -v)
  • PostgreSQL database (local or cloud: Supabase, Neon, Railway)
  • Git (for cloning the repository)

I'm getting "Module not found" errors

Run these commands to reset your dependencies:

rm -rf node_modules package-lock.json
npm install
npx prisma generate

How do I fix database connection errors?

  1. Check your DATABASE_URL format:

    # Should be: postgresql://user:password@host:port/database
postgresql://postgres:mypassword@localhost:5432/mydb

  2. If using a cloud database:

    • Check if it's paused (free tiers often pause after inactivity)
    • Verify the connection string was copied correctly
    • Ensure SSL is configured if required

  3. If using local PostgreSQL:

    # Check if PostgreSQL is running
pg_isready

See Installation Guide for detailed troubleshooting.

Port 3000 is already in use

Run on a different port:

PORT=3001 npm run dev

Authentication

How do I set up OAuth?

  1. Create OAuth apps on GitHub and/or Google Cloud Console
  2. Add credentials to .env.local
  3. Set callback URLs to http://localhost:3000/api/auth/callback/{provider}

See Authentication Guide for step-by-step instructions.

OAuth returns "Invalid credentials" error

Check these:

  1. Client ID and Secret are correct in .env.local
  2. Callback URL matches exactly (including http vs https)
  3. AUTH_SECRET is set (generate with npx auth secret)

Sessions aren't persisting

  1. Make sure DATABASE_URL is configured
  2. Run npx prisma db push to create database tables
  3. Check if cookies are being blocked by your browser

Can I add other OAuth providers?

Yes! Auth.js supports many providers. Add them in src/lib/auth.ts:

import Discord from "next-auth/providers/discord";

providers: [
  GitHub({ ... }),
  Google({ ... }),
  Discord({
    clientId: process.env.DISCORD_CLIENT_ID,
    clientSecret: process.env.DISCORD_CLIENT_SECRET,
  }),
],

Billing & Payments

Why Gumroad + GitHub Invite?

ShipSecure uses the same delivery model as popular boilerplates:

  1. Customer purchases on Gumroad (provides GitHub username)
  2. You invite them to your private repository
  3. Customer accepts invite and clones the code

This approach is:

  • Simple: No complex license verification code needed
  • Secure: GitHub handles access control
  • Proven: A reliable and industry-standard delivery method

How do I deliver the code to customers?

  1. Set up a custom field in Gumroad for "GitHub Username" (required)
  2. When someone purchases, you receive their GitHub username
  3. Add them as a collaborator to your private repository
  4. Customer accepts the invite and can clone the code

See Billing & Payments for detailed setup instructions.

Can I use Stripe instead?

For subscriptions (monthly/yearly), yes! The database schema includes fields for Stripe:

model User {
  // ...
  customerId    String?   // Stripe Customer ID
  subscriptionId String?  // Stripe Subscription ID
}

Stripe integration is on our roadmap - see Roadmap.

Database

Which databases are supported?

ShipSecure uses PostgreSQL via Prisma. Recommended cloud options:

  • Supabase - Free tier, managed PostgreSQL
  • Neon - Serverless PostgreSQL, free tier
  • Railway - Simple setup, free tier
  • PlanetScale - MySQL (requires schema changes)

How do I add new database models?

  1. Edit prisma/schema.prisma
  2. Run npx prisma db push (development)
  3. Run npx prisma generate

See Database & Prisma for examples.

Should I use db push or migrate?

  • npx prisma db push: Quick development, no migration history
  • npx prisma migrate dev: Production, team projects, version control

For production deployments, always use npx prisma migrate deploy.

How do I view my database?

npx prisma studio

Opens a visual database browser at http://localhost:5555.

Security

What security features are included?

  • Security Headers: CSP, HSTS, X-Frame-Options, etc.
  • Rate Limiting: API protection (60 req/min, 20 for auth)
  • Input Validation: Zod schemas for all inputs
  • CSRF Protection: Built into Auth.js
  • SQL Injection Prevention: Prisma ORM

All security features are tested with TDD. See Security Features.

Do I need to configure security headers?

No! Security headers are automatically applied to all responses via middleware. You can customize them in src/lib/security/headers.ts if needed.

How does rate limiting work?

  • Uses Upstash Redis in production (required for serverless)
  • Falls back to in-memory storage in development
  • Configure limits in src/middleware.ts

Is ShipSecure PCI/SOC2/HIPAA compliant?

ShipSecure provides security best practices, but compliance requires additional measures specific to your use case:

  • PCI: Don't store card data - use Stripe/Gumroad
  • SOC2: Requires audit procedures and documentation
  • HIPAA: Requires BAA agreements and specific configurations

Deployment

Where can I deploy ShipSecure?

Any platform that supports Next.js:

  • Vercel (recommended) - Best Next.js support
  • Netlify - netlify.toml included
  • Railway - Easy database setup
  • Fly.io, Render, DigitalOcean, etc.

See Deployment Guide.

What environment variables do I need in production?

Required:

DATABASE_URL=postgresql://...
AUTH_SECRET=your-production-secret
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Recommended:

UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...
NEXT_PUBLIC_APP_URL=https://your-domain.com
# RESEND_API_KEY=... (if using email features)

Do I need to update OAuth callback URLs?

Yes! After deploying, update callback URLs in your OAuth provider settings:

  • GitHub: https://your-domain.com/api/auth/callback/github
  • Google: https://your-domain.com/api/auth/callback/google

Customization

How do I change the app name and branding?

Edit src/config/site.ts:

export const siteConfig = {
  name: "YourAppName",
  title: "YourAppName - Your Tagline",
  description: "Your app description",
  // ...
};

See Customization Guide.

How do I customize the landing page?

Edit src/config/marketing.ts to change:

  • Hero section text
  • Features list
  • Pricing plans

How do I change colors?

Edit src/app/globals.css:

:root {
  --primary: 142 71% 45%; /* Your primary color (HSL) */
  --secondary: 217 33% 17%;
}

Testing

What testing tools are included?

  • Vitest - Unit and integration tests
  • Playwright - End-to-end tests
  • React Testing Library - Component tests

How do I run tests?

# Unit tests
npm test

# E2E tests
npm run test:e2e

# Watch mode
npm run test:watch

See Testing Guide.

Are there example tests?

Yes! Check src/lib/security/__tests__/ for examples of:

  • Security headers tests
  • Rate limiting tests
  • Input validation tests

Troubleshooting

Build fails with TypeScript errors

# Check for type errors
npm run type-check

# Or
npx tsc --noEmit

ESLint errors blocking development

# Fix auto-fixable issues
npm run lint -- --fix

Prisma Client not found

npx prisma generate

"Invalid token" or CSRF errors

  1. Clear browser cookies
  2. Sign out and sign back in
  3. Verify AUTH_SECRET hasn't changed

Getting "Too Many Requests" error

Rate limit is working! Wait 1 minute or:

  1. Increase limits in src/middleware.ts for development
  2. Configure Upstash Redis for production

Updates & Support

How do I get updates?

Check the GitHub repository for new releases. You can pull updates manually:

git remote add upstream https://github.com/hasankemaldemirci/shipsecure.git
git fetch upstream
git merge upstream/main

Note: Resolve conflicts carefully to keep your customizations.

Where can I get help?

  • Documentation: You're reading it!
  • GitHub Issues: Report bugs or request features
  • Email: support@shipsecure.dev

Can I use ShipSecure for multiple projects?

Your purchase includes a commercial license for unlimited projects. Build as many products as you want!

Still Have Questions?

If your question isn't answered here:

  1. Check the specific documentation pages
  2. Search the GitHub repository for similar issues
  3. Contact support at support@shipsecure.dev

Happy building!