Skip to main content

GetShipKit Documentation

Everything you need to know to build, deploy, and scale your SaaS application.

Getting Started

GetShipKit provides a production-ready foundation for your SaaS project with built-in authentication, payments, and database integration. Our enterprise-grade starter kit helps developers launch modern SaaS applications in days instead of months by eliminating boilerplate setup and infrastructure challenges.

Prerequisites

  • Node.js (v18+) and a package manager (npm, yarn, or pnpm)
  • Git for version control and a modern code editor (VSCode recommended with TypeScript extensions)
  • Service accounts from our technology partners:
    • Supabase account for PostgreSQL database
    • Clerk account for authentication
    • Polar.sh account for payment processing
    • Vercel account for deployment (optional: any Node-capable platform works)

What's Included

  • Authentication & User Management: Secure authentication with social logins, multi-factor authentication, and complete user profile management via Clerk
  • Database & Backend: Supabase PostgreSQL with pre-configured schema, row-level security, and optimized indexes
  • Billing Solutions: Subscription plans, one-time payments, and usage-based billing via Polar.sh with webhooks integration
  • Modern UI Components: Responsive dashboard with dark/light modes, accessibility compliance, and Tailwind CSS styling
  • DevOps Ready: Optimized for CI/CD pipelines with containerization support

Installation

Follow these steps to get your SaaS application up and running quickly. The entire process takes approximately 3 minutes.

Quick Setup ~3 minutes

  1. Clone the repository and navigate to the project directory:
    terminal
    git clone https://github.com/yourusername/getshipkit.git my-saas-app
    cd my-saas-app
  2. Install dependencies:
    terminal
    npm install
  3. Set up your environment variables:
    terminal
    cp .env.example .env.local
  4. Start the development server:
    terminal
    npm run dev

Your application will be running at http://localhost:3000

All API routes are available at /api/*

Troubleshooting Tips

  • If you encounter dependency issues, try using npm clean-install
  • Make sure all required environment variables are set in your .env.local file
  • Check port availability if the server fails to start

Authentication

GetShipKit leverages Clerk for full-stack authentication with social logins, JWT management, and secure session handling. This drop-in solution handles user sign-up, sign-in, profile management, and authorization.

Environment Configuration

Add your Clerk API keys to your .env.local file:

.env.local
# .env.local
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_****
CLERK_SECRET_KEY=sk_test_****

Route Protection

Configure route protection via middleware.ts:

middleware.ts
1
2
3
4
5
import { authMiddleware } from "@clerk/nextjs";

export default authMiddleware({
  publicRoutes: ["/"],
});

Authentication Features

Social login providers (Google, GitHub, etc.)
Multi-factor authentication
JWT and session management
User profile management
Email verification
Role-based access control

Pro Tip

Use the useAuth() hook from Clerk to access the current user's session information across your application.

Database Setup

Supabase PostgreSQL powers the database layer with robust relational data management, real-time subscriptions, and built-in Row Level Security (RLS) policies for granular access control.

Environment Configuration

Add your Supabase credentials to your .env.local file:

.env.local
NEXT_PUBLIC_SUPABASE_URL=https://[project].supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=anon-key
SUPABASE_SERVICE_ROLE_KEY=service-key

Schema Setup

Run schema_setup.sql in the Supabase SQL editor to create:

  • User profiles with Clerk auth bindings
  • Organizations for multi-tenant support
  • Subscription records linked to Polar
  • Analytics-ready event logging

Security Features

  • Row Level Security (RLS) policies
  • Role-based access control
  • Fine-grained permissions
  • JWT validation

Real-time Features

  • Real-time database subscriptions
  • Broadcast channels
  • Presence indicators
  • Change data capture

Row Level Security in Action

Supabase uses PostgreSQL Row Level Security to ensure users can only access their own data. The schema creates appropriate policies that restrict data access at the database level.

schema_setup.sql
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
-- Create tables
CREATE TABLE IF NOT EXISTS profiles (
  id UUID PRIMARY KEY REFERENCES auth.users(id) ON DELETE CASCADE,
  email TEXT UNIQUE NOT NULL,
  full_name TEXT,
  avatar_url TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() NOT NULL
);

-- Row Level Security Policies
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- Policy: Users can read their own profile
CREATE POLICY "Users can read own profile"
  ON profiles
  FOR SELECT
  USING (auth.uid() = id);

-- Policy: Users can update their own profile
CREATE POLICY "Users can update own profile"
  ON profiles
  FOR UPDATE
  USING (auth.uid() = id);

Pro Tip

Use the Supabase Admin UI to manage your database visually and create additional tables or RLS policies.

Payment Integration

Subscriptions and one-time payments are handled via Polar.sh, a modern payment platform that supports multiple pricing models, global payment methods, and automated subscription lifecycle management.

Configuration Steps

  1. Environment Setup

    Add Polar.sh credentials to your .env.local file:

    .env.local
    # Set to either "sandbox" or "production"
    POLAR_MODE=sandbox
    
    # Polar Payments
    POLAR_ACCESS_TOKEN=polar_oat_*********************
    POLAR_WEBHOOK_SECRET=************************
    POLAR_SUCCESS_URL=http://localhost:3000/dashboard/billing?success=true
    
    # Payment Model Configuration (options: 'subscription' or 'onetime')
    # This is used to determine which payment model to use for the checkout process
    NEXT_PUBLIC_PAYMENT_MODEL=onetime
    
    # Product IDs with display names (ID:NAME format)
    NEXT_PUBLIC_PRODUCTS={
      "starter_monthly": "b62c857d-****:Basic",
      "starter_annual": "96503da7-****:Basic",
      "pro_monthly": "20b937bc-****:Premium",
      "pro_annual": "0af3136d-****:Premium",
      "enterprise_monthly": "4b25a4af-****:Ultimate",
      "enterprise_annual": "f74696b1-****:Ultimate",
      "one_time": "e7a07f01-****:Forever Access"
    }
  2. Implement Checkout Flow

    Use the provided usePolar hook to create checkout sessions:

    checkout.ts
    1
    2
    3
    4
    5
    6
    7
    8
    9
    const { createCheckout } = usePolar();
    const url = await createCheckout({ 
      productId, 
      successUrl, 
      cancelUrl 
    });
    
    // Redirect to checkout
    window.location.href = url;
  3. Handle Webhooks

    Create an API route to process webhook events from Polar.sh when subscription statuses change:

    Common Event Types:
    • subscription.created
    • subscription.updated
    • subscription.canceled
    • payment.succeeded
    • payment.failed
    Webhook Security:
    • Verify webhook signatures
    • Store POLAR_WEBHOOK_SECRET in environment
    • Use HTTPS for all webhook endpoints
    • Implement idempotency for duplicate events

Pricing Models

  • Subscription-based recurring billing
  • Usage-based metered billing
  • One-time purchases
  • Tiered pricing structures
  • Free trials with automatic conversion
  • Custom discount codes

Global Coverage

  • Support for 135+ currencies
  • Automatic tax calculation
  • Country-specific compliance handling
  • Multiple payment methods
  • Localized checkout experiences
  • Compliant invoicing

Testing Payments

Use Polar's sandbox mode with test card 4242 4242 4242 4242 (expiry: any future date, CVC: any 3 digits) to test the payment flow without processing real payments.

Deployment

GetShipKit is designed to be deployed on any modern hosting platform. We recommend Vercel, Netlify, or any Node.js-capable platform.

Vercel Deployment

  1. Push your repository to GitHub/GitLab/Bitbucket
  2. Import your repository in Vercel
  3. Configure environment variables in Vercel dashboard
  4. Deploy with a single click

Key Benefits:

  • • Automatic preview deployments for PRs
  • • Edge functions for API routes
  • • Seamless CI/CD integration

Manual Deployment

  1. Configure environment variables in your .env.local
  2. Run database migrations: npx supabase db push
  3. Set up webhooks in Clerk and Polar
  4. Build the application: npm run build
  5. Start the production server: npm start

Docker Deployment

GetShipKit includes Docker support for containerized deployments:

terminal
# Build the Docker image
docker build -t getshipkit .

# Run the container
docker run -p 3000:3000 getshipkit

Environment Variables

Pass environment variables to Docker using --env-file or -e flags for secure configuration.

Container Orchestration

Deploy with Kubernetes or Docker Swarm for high-availability and scalability in production.

CI/CD Integration

Use GitHub Actions, GitLab CI, or other CI/CD tools for automated builds and deployments.

Production Checklist

  • Configure proper SSL/TLS for all domains
  • Set up monitoring and error tracking
  • Implement proper logging
  • Set up automated backups for your database
  • Test the authentication flow in production
  • Verify webhook endpoints are correctly configured

Design Guidelines

GetShipKit follows Cursor's premium design rule-sets ensuring accessibility and consistency. The project includes Cursor rules files that help create a perfect UI and UX when working in the Cursor app.

Design Principles

  • Consistent visual hierarchy & spacing - Carefully crafted type scales and spacing system
  • WCAG-compliant colors & keyboard navigation - AA-level contrast and fully accessible interactions
  • Responsive across breakpoints - Mobile-first design with seamless desktop adaptations
  • Cursor rules integration - Pre-configured design rules in the Cursor app

Cursor Rules Files

GetShipKit includes custom Cursor rules files that provide intelligent design suggestions and enforce consistency while you code:

  • Component structure recommendations
  • Design pattern consistency checks
  • Accessibility compliance validators
  • Real-time design system feedback

Using the Rules

The Cursor app automatically loads these rules when working with GetShipKit files, providing:

  • Context-aware UI/UX suggestions
  • Component library integration
  • Design system auto-completion
  • Visual consistency validation

Pro Tip

For the best UI development experience, install the Cursor app and open the project to automatically load all design rule-sets and get real-time feedback as you build components.

Specialized Prompts

The repository includes legal-page-prompts.md with AI prompts to generate legal pages such as Terms of Service and Privacy Policy.

Always have any generated legal text reviewed by a qualified professional.