Setup

Create a new database

supastarter for TanStack Start uses Drizzle as the ORM (database access layer). PostgreSQL is the default database, with optional MySQL and SQLite/libSQL setups covered in the database docs.

Before creating a new supastarter project, make sure to have created a new database and have the connection string ready. For example when using PostgreSQL, the connection string will look something like this:

postgresql://user:password@host:port/database

Initialize a new supastarter project

During the setup process you will be asked to provide the following information:

• Project name - The name of your project
• Database provider - The database provider you are using
• Database connection string - The connection string of your database

To create a new supastarter project all you need to do is run the following command (replace my-awesome-project with the name of your project):

npx supastarter new my-awesome-project

This will clone and configure the supastarter repository, install all the dependencies and set up the database for you.

Repository layout

The TanStack Start codebase contains separate apps for each main surface:

• apps/marketing for the public website
• apps/saas for the product app and auth flows
• apps/docs for the docs site
• apps/mail-preview for email previews

When you customize the UI or routes, choose the app that owns that surface: apps/marketing for the public site and apps/saas for the product app.

Manual setup

The following steps are only necessary if you encounter any errors during the setup process, otherwise you can skip to step 3.

Clone the supastarter repository

git clone https://github.com/supastarter/supastarter-tanstack-start.git

Install the dependencies

Make sure you have installed pnpm before running the following command:

pnpm install

Set up the environment variables

To do this, copy the .env.local.example file in the root of your project and rename it to .env.local.

Then open the .env.local file and set at least the DATABASE_URL:

# Database
DATABASE_URL="YOUR_DATABASE_CONNECTION_STRING"

If you are using Supabase, you want to follow our Supabase setup guide as you will need a second connection string for the database migration.

Configure the database

Drizzle

The default PostgreSQL setup works out of the box. If you change the database provider, make sure the /packages/database/index.ts file exports Drizzle:

export * from "./drizzle";

Next make sure to use the drizzle adapter in the /packages/auth/auth.ts file:

export const auth = betterAuth({
	database: drizzleAdapter(db, {
		provider: "mysql", // or "sqlite" or "pg"
	}),
});

If you are using a different database than PostgreSQL, you will need to export the schema for either mysql or sqlite from the /packages/database/drizzle/schema/index.ts file.

export * from "./postgres";
// or export * from "./mysql";
// or export * from "./sqlite";

Lastly, you will need to set up the correct database client in the client.ts file. Follow the instructions in the Drizzle documentation for the database provider you are using. For PostgreSQL you can use the following example:

import { drizzle } from "drizzle-orm/node-postgres";
import * as schema from "./schema/postgres";

const databaseUrl = process.env.DATABASE_URL as string;

if (!databaseUrl) {
	throw new Error("DATABASE_URL is not set");
}

export const db = drizzle(databaseUrl, {
	schema,
});

Read more about how to use the database in the database documentation.

Select your mail provider

Select your mail provider which is used for sending transactional emails like the magic link for login.

In the /packages/mail/provider/index.ts file, set the export to the provider you want to use:

export * from "./plunk";
// or export * from './resend';
// or export * from './postmark';
// or export * from './nodemailer';
// or export * from './console'; // for development only

Then make sure to set the mandatory environment variables for your provider in the .env.local file:

• Plunk -> PLUNK_API_KEY
• Resend -> RESEND_API_KEY
• Postmark -> POSTMARK_SERVER_TOKEN
• Nodemailer -> MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASS

See the mailing documentation for more information on how to set up your mail provider.

Set up the payment provider

Next, we need to set the payment provider which is used for handling payments:

export * from "./stripe";
// or export * from './lemonsqueezy';
// or export * from './creem';
// or export * from './polar';

Plan configuration is defined with provider priceId values, and checkout is created from planId, type, and optional interval.

Push and generate the database schema

Make sure to check your schema in packages/database/drizzle/schema/ before continuing.

To push the database schema to your database, run the following command:

pnpm --filter database push

Set up the supastarter repository as the upstream origin

The last step is to set the supastarter repository as the upstream origin for your project, so you can pull in updates in the future.

Run the following commands:

rm -rf .git
git init
git remote add upstream https://github.com/supastarter/supastarter-tanstack-start.git
git add .
git commit -m "Initial commit"

Set up your storage provider

Storage is necessary to upload and serve files like images for example for the avatars of users and teams. Setting up a storage provider is optional, but recommended and necessary if you want to enable avatar and logo uploads.

supastarter supports all S3-compatible storage providers like AWS S3, DigitalOcean Spaces, MinIO, etc. and Supabase Storage.

Storage setup guide

Set up your local development environment (optional)

If you want to set up a complete local development environment, you can follow the local development guide.

Start your development server

Now your app should be ready to go. To start the local development server, navigate into your project root folder and run the following command.

pnpm dev

Depending on your workspace setup, this can start multiple apps. The most common local surfaces are:

• apps/marketing for the public site
• apps/saas for the product app
• apps/docs for documentation

Create admin user

To use your application, you want to create an admin user. You can use a simple CLI script to create a new admin user in the database:

pnpm --filter scripts create:user