This guide will take you from 0 to successfully running a login-ready, payment-ready SaaS application locally.

If you only want to use ShipNowKit as a Landing Page for now, you can skip the "Database" and "Login Authentication" steps and directly complete "Initialize Project" and "Start Development Server".

1. Prerequisites

• Node.js: Recommended 18+ (Compatible with Next.js 16)
• Package Manager: npm (or pnpm / yarn, examples below use npm)
• Database (Optional but Recommended):
  • For development: SQLite or local PostgreSQL recommended
  • For production: PostgreSQL / MySQL / MongoDB recommended

You can switch database drivers at any time via scripts/switch-database.js, which will be explained later.

2. Initialize Project

2.1 Clone Repository

git clone https://github.com/dante-is-shipping/shipnow-boilerplate.git my-shipnowkit-app
cd my-shipnowkit-app

2.2 Install Dependencies

npm install

After installation, the project structure is roughly as follows (simplified):

shipnow-boilerplate/
├── app/                # Next.js App Router application directory
├── components/         # Component library (Auth / Payment / Dashboard / UI, etc.)
├── config/             # Site & Global Configuration
├── content/            # Fumadocs Documentation & Blog Content
├── db/                 # Prisma Schema & Database Services
├── emailTemplate/      # React Email Templates
├── lib/                # Server Actions, Payment, Auth Core Logic
├── messages/           # i18n Text (English/Chinese)
├── public/             # Static Assets & Logo
├── scripts/            # Database / Template / Payment Related Scripts
└── styles/             # Global Styles

3. Configure Environment Variables

All sensitive configurations in ShipNowKit are managed via environment variables. For local development, .env.local is recommended.

3.1 Create .env.local

cp .env.example .env.local

You can configure minimally based on your needs. It is recommended to focus on these core fields first (replace example values with your own):

# Database
DATABASE_URL=your_database_url

# Better Auth Basic Config
BETTER_AUTH_SECRET=your_secret_key
BETTER_AUTH_URL=http://localhost:3000

# Email (For verification emails / Magic Link, etc.)
AUTH_EMAIL_FROM="ShipNowKit <noreply@localhost>"
RESEND_API_KEY=your_resend_key

# Stripe (If enabling Stripe payment)
STRIPE_SECRET_KEY=your_stripe_key
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

# Paddle (If enabling Paddle payment)
PADDLE_API_KEY=your_paddle_key
PADDLE_WEBHOOK_SECRET=your_paddle_webhook_secret

Minimal Runnable Configuration Suggestion

• Just want to run Login + Dashboard: Configure DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL, and Email related variables.
• Want to experience the full payment loop: Add Stripe or Paddle related keys.

4. Configure Database

ShipNowKit uses Prisma ORM to unify database models and supports multiple database drivers.

4.1 Select Database Type

Execute in the project root (choose one, SQLite or local PostgreSQL recommended for development):

# SQLite (Best for local single-machine development)
npm run db:use:sqlite

# Or PostgreSQL
npm run db:use:postgresql

# Or MySQL
npm run db:use:mysql

# Or MongoDB
npm run db:use:mongodb

These scripts will modify the Prisma configuration according to the selected database type and help you align the provider settings in schema.prisma. Afterwards, please ensure DATABASE_URL in .env.local matches it, for example:

# PostgreSQL Example
DATABASE_URL="postgresql://user:password@localhost:5432/shipnowkit"

4.2 Generate Prisma Client & Migrate Database

# Generate Prisma Client
npm run db:generate

# Run database migration (uses DATABASE_URL from .env.local)
npm run db:migrate

If you just want to quickly push the schema to an empty database, you can also use:

npm run db:push

If you encounter connection timeouts or inability to connect, prioritize checking:

• Is DATABASE_URL spelled correctly?
• Is the database service started and port open?
• Do local firewalls or proxies affect the connection?

5. Configure Authentication (Better Auth)

ShipNowKit uses Better Auth as the built-in authentication solution, supporting Email/Password, Magic Link, and multiple OAuth providers.

5.1 Set Basic Auth Keys

Configure at least the following in .env.local:

BETTER_AUTH_SECRET=your_secret_key   # Can be generated with `openssl rand -base64 32`
BETTER_AUTH_URL=http://localhost:3000

After configuration:

• The application will automatically enable authentication logic.
• Accessing pages requiring login will check endpoints like /api/auth/get-session.

5.2 Optional: Configure OAuth Login

If you wish to experience Google/GitHub login locally, configure as needed:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
# Same for other providers

These configurations will take effect on the dashboard settings page and login page. You can experience different login methods in the browser.

5.3 Enable Specific Login Methods (AUTH_*_ENABLED)

ShipNowKit uses a set of AUTH_*_ENABLED environment variables to finely control allowed login methods. For example:

# Enable Email/Password Login
AUTH_PASSWORD_ENABLED=true

# Enable Google Login
AUTH_GOOGLE_ENABLED=true

# See .env.example for a full list of other methods (GitHub / Apple / Discord / ...)

Recommendation:

• Only enable login methods you really need to debug during local development.
• Before production, check all AUTH_*_ENABLED switches against .env.example to ensure they meet expectations.

6. Initialize Test User (Optional but Recommended)

To quickly access the dashboard and payment flow, you can use the built-in script to create a test user.

node scripts/create-test-user.js

The script will:

• Create a user with email [email protected] in the database.
• Set default password to test123456.
• Automatically handle password salting/hashing and email verification flag.

After successful creation, you can use the following on the login page:

• Email: [email protected]
• Password: test123456

6.1 Configure Admin for Dashboard (ADMIN_USER_LIST)

To access admin pages and configuration APIs in the dashboard, you need to add the admin user's userId to the ADMIN_USER_LIST environment variable:

1. First run scripts/create-test-user.js. The script will output something like:

   Test user created successfully:
   Email: [email protected]
   Password: test123456
   User ID: cm1234567890abcdef...

2. Configure this User ID into .env.local:

   ADMIN_USER_LIST="cm1234567890abcdef..."
   # For multiple admins, separate with commas:
   # ADMIN_USER_LIST="id1,id2,id3"

lib/admin.ts will parse the admin ID list from ADMIN_USER_LIST. Only users in this list can call /api/dashboard/* related APIs and access corresponding management features.

7. Start Development Server

After completing environment variables, database, and auth configuration, you can start the local development server:

npm run dev

It defaults to listening on http://localhost:3000. Upon first opening, you will see the ShipNowKit Landing Page:

• /: Marketing Landing Page (displayed based on current template)
• /signin: Login Page
• /register: Registration Page
• /dashboard: Dashboard accessible after login

To switch templates (e.g., between ShipNowLike and NotionLike), use:

npm run template:t1  # Switch to Template T1
npm run template:t2  # Switch to Template T2

8. Quickly Verify Functionality

After completing the above steps, you can perform a "Functionality Self-Check" in the following order:

1. Visit Landing Page Open http://localhost:3000, check if multi-language switching, navigation, pricing cards, etc., display correctly.

2. Login / Register

   • Login with test account [email protected] / test123456
   • Or register with email + Magic Link / Password login

3. Enter Dashboard Access /dashboard after successful login, confirm basic data loading.

4. (Optional) Test Payment Flow

   • Configure Stripe / Paddle according to README instructions
   • Use test card numbers to complete a subscription or one-time payment
   • Check subscriptions / oneTimePayments tables in the database for records

9. Next Step: Customize Your ShipNowKit

Once you have successfully run ShipNowKit locally, you can continue reading:

• Modify config/site.ts and messages/*.json to replace with your product name and copy.
• Edit app/[locale]/page.tsx to build your own marketing landing page.

You have now completed the local quick start of ShipNowKit and can continue developing your SaaS product on this foundation.