Installation

This guide walks you from a fresh clone to a running local app. Allow 15–30 minutes on your first setup — most of that is creating a Postgres database and filling in env vars.

Quick start

After you have the repository on your machine:

git clone <repository-url> motoko-base
cd motoko-base
pnpm install
cp .env.example .env
pnpm db:migrate
pnpm dev

Open http://localhost:3000. Sign up at Sign up, verify your email, then open /dashboard.

The sections below explain each step and what to configure before the app works end to end.

Node version

Motoko Base requires Node.js 22 or newer.

node -v

You should see v22.x.x or higher. The repo pins this in .nvmrc — if you use nvm:

nvm use

If Node is missing or too old, install the current LTS from nodejs.org or via your version manager.

pnpm

This project uses pnpm as the package manager (packageManager is set in package.json). Do not use npm install or yarn — lockfile and scripts are pnpm-only.

Install pnpm and project dependencies from the project root:

corepack enable
corepack prepare pnpm@latest --activate
pnpm install

The postinstall script runs fumadocs-mdx to compile documentation content. A successful install ends without errors.

Environment variables

Copy the template and edit the new file:

cp .env.example .env

You can also use .env.local — Next.js loads both. Never commit real secrets; .env* is gitignored except .env.example.

Required for minimal boot

These three variables are enough to start the dev server and run migrations:

Generate a secret:

openssl rand -base64 32

Paste the output into BETTER_AUTH_SECRET in .env.

Strongly recommended for signup testing

Email verification is required before dashboard access. Without Resend configured, you can start the app but you will not receive verification emails after sign-up.

Optional integrations

Polar, R2, PostHog, Sentry, OpenAI, Google OAuth, and GitHub OAuth are all optional. The app soft-fails when they are unset — unrelated routes keep working, and feature pages show a clear configuration message.

See .env.example for every variable and inline comments. Never put server secrets on NEXT_PUBLIC_*.

Database

Motoko Base uses PostgreSQL with Drizzle ORM. You need a running Postgres instance before pnpm db:migrate.

Create a database

Pick one:

• Supabase — create a project, copy the connection string from Project Settings → Database
• Local Postgres — create a database and user, then build a postgresql:// URL

For the Next.js app at runtime, prefer Supabase’s transaction pooler (often port 6543). For migrations, if DDL fails through the pooler, temporarily point DATABASE_URL at the direct connection (often port 5432).

Set the URL in .env:

DATABASE_URL=postgresql://...

Run migrations

From the project root:

pnpm db:migrate

This applies SQL migrations from drizzle/migrations/ using Drizzle Kit. You only need to re-run after pulling new migrations or changing the schema yourself (pnpm db:generate then pnpm db:migrate).

Optional: open Drizzle Studio to inspect tables:

pnpm db:studio

Better Auth

Authentication is handled by Better Auth with a Drizzle adapter. No extra auth service is required beyond Postgres and the env vars above.

For local development, set:

BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_APP_URL=http://localhost:3000

Keep BETTER_AUTH_URL aligned with the URL you actually open in the browser — OAuth redirect URIs and session cookies depend on it.

Google / GitHub sign-in are optional. Leave GOOGLE_* and GITHUB_* unset to boot without them; the buttons stay disabled until configured. Callback URLs must match BETTER_AUTH_URL:

• Google: {BETTER_AUTH_URL}/api/auth/callback/google
• GitHub: {BETTER_AUTH_URL}/api/auth/callback/github

Auth API routes live at /api/auth/*. Protected dashboard routes require a verified session.

First run

1. Start the dev server:

   Copy

   pnpm dev

2. Open http://localhost:3000.

3. Click Sign up, create an account with email and password.

4. Check your inbox for the verification email (requires Resend). Click the link.

5. Sign in and open Dashboard (/dashboard).

6. Explore core pages (Settings, Billing) and demo features under Demos (Link Manager, Storage, AI Email). Demos that need extra env vars show a configuration notice instead of crashing.

With only the minimal env vars set, auth and the dashboard shell work. Billing stays on Free, Storage and AI Email show setup hints, and analytics/monitoring stay quiet.