Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/revokslab/shipfree/llms.txt

Use this file to discover all available pages before exploring further.

​
Quickstart

Get your ShipFree application running locally in just a few steps. This guide will take you from zero to a working application.
This quickstart assumes you have Bun and PostgreSQL already installed. If not, check out the Installation guide for detailed setup instructions.
1

Clone the repository

Clone the ShipFree repository to your local machine:
git clone https://github.com/revokshq/shipfree.git
cd shipfree
2

Install dependencies

ShipFree uses Bun as its package manager. Install all dependencies with:
bun install
Bun is significantly faster than npm or yarn. If you don’t have it installed yet, visit bun.sh for installation instructions.
3

Set up environment variables

Copy the example environment file and configure your settings:
cp .env.example .env
Open .env and configure the required variables:
# Database connection
DATABASE_URL=postgres://postgres:postgres@localhost:5432/shipfree

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

# Better-Auth secret (generate with: openssl rand -base64 32)
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=http://localhost:3000

# Email provider (set to 'log' for development)
EMAIL_PROVIDER=log

# Environment
NEXT_PUBLIC_ENV=development
Make sure to generate a secure BETTER_AUTH_SECRET using openssl rand -base64 32. Never use the example value in production.
4

Set up the database

Create a PostgreSQL database for your application:
# Using psql
createdb shipfree

# Or using PostgreSQL CLI
psql -U postgres -c "CREATE DATABASE shipfree;"
Make sure your DATABASE_URL in .env matches your database credentials.
5

Run database migrations

Apply the database schema using Drizzle migrations:
bun run migrate:local
This command runs the migration script at scripts/migrate.ts and sets up all required tables.
6

Start the development server

Launch the Next.js development server:
bun dev
Your application will be available at http://localhost:3000
The development server supports hot reloading, so changes you make will be reflected instantly.

​
Verify your setup

Once the development server is running, you should be able to:
  1. Visit the homepage at http://localhost:3000
  2. Navigate to the sign-up page
  3. Create a test account
  4. Access the dashboard
With EMAIL_PROVIDER=log, authentication emails will be printed to your console instead of being sent. This is perfect for development.

​
Available commands

Here are the key commands you’ll use during development: 
bun dev

​
Next steps

Now that your application is running, here’s what to do next:

Configure authentication

Set up OAuth providers like Google, GitHub, and Microsoft

Set up payments

Configure Stripe, Polar, or other payment providers

Configure emails

Set up Resend, Postmark, or your preferred email service

Customize branding

Update colors, logo, and brand settings

Add translations

Add support for additional languages

Deploy your app

Deploy to Vercel, Railway, or your preferred platform

​
Common issues

If you see a database connection error, verify that:
  • PostgreSQL is running
  • Your DATABASE_URL is correct
  • The database exists (createdb shipfree)
  • Your PostgreSQL user has the correct permissions
Make sure Bun is installed and in your PATH:
curl -fsSL https://bun.sh/install | bash
Then restart your terminal.
If port 3000 is already in use, you can specify a different port:
PORT=3001 bun dev
If migrations fail, try:
  1. Checking your database connection
  2. Ensuring the database is empty for a fresh install
  3. Running bun run generate-migration to regenerate migrations
For more detailed troubleshooting, see the Installation guide or join our community for support.

Build docs developers (and LLMs) love

Get started for freeTalk to us