Skip to main content

​
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:
2

Install dependencies

ShipFree uses Bun as its package manager. Install all dependencies with:
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:
Open .env and configure the required variables:
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:
Make sure your DATABASE_URL in .env matches your database credentials.
5

Run database migrations

Apply the database schema using Drizzle migrations:
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:
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:

​
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:
Then restart your terminal.
If port 3000 is already in use, you can specify a different port:
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.