Site icon JD Bots

How to Set Up and Run Next.js Authentication with Better Auth and PostgreSQL

A card titled From Zip to Running App, set up and run Next.js Authentication with Better Auth and PostgreSQL, with a terminal listing four checked steps: npm install, docker compose up -d, npx auth migrate and npm run dev.

From the zip to a running app in four commands.

You have the source code of Next.js Authentication with Better Auth and PostgreSQL. This guide takes it from the zip file to the app running on your own computer, with its database in Docker and your first account signed in.

By the end, the Bookshop app runs at http://localhost:3000, and you’ve created an account with an email address and a password.

Every command and output on this page is real, run with Node.js 26 and Docker Desktop on macOS. The commands are the same in Windows PowerShell, except where a step shows both.

Cost: free to run. Everything runs on your own computer, and the app needs no accounts or API keys. Docker Desktop is free for personal use, education, non-commercial open source projects and small businesses (fewer than 250 employees and less than $10 million in annual revenue); larger organizations and government entities need a paid subscription (Docker Desktop license agreement).

Get the Source Code

Get the complete source code of Next.js Authentication with Better Auth and PostgreSQL on Dewiride Store →
The archive holds the app this guide sets up and runs.

Prerequisites

Step 1: Unzip the Source Code

Open a terminal in the folder that holds the zip, such as Downloads, and unzip it:

Terminal (macOS / Linux)

unzip nextjs-authentication-better-auth-postgresql-1.0.0.zip

PowerShell (Windows)

Expand-Archive -Path nextjs-authentication-better-auth-postgresql-1.0.0.zip -DestinationPath .

It creates a folder named nextjs-authentication-better-auth-postgresql. Go into it:

Terminal

cd nextjs-authentication-better-auth-postgresql

The folder holds the app’s code (app, components and lib), compose.yaml for the database, .env.example with the settings, and a README.

Step 2: Install the Packages

npm install downloads the packages the app uses, at the exact versions listed in package-lock.json:

Terminal

npm install

Output

added 86 packages, and audited 93 packages in 6s

17 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Step 3: Add Your Settings

The app reads its settings from a file named .env. Create it from the example file:

Terminal (macOS / Linux)

cp .env.example .env

PowerShell (Windows)

Copy-Item .env.example .env

Better Auth needs a secret: a long random value it uses to sign and encrypt data, such as session cookies. Its command-line tool makes one (How to Generate a Better Auth Secret explains it):

Terminal

npx auth@latest secret

The first time, npx asks to install auth: type y. It prints a new secret. Yours is a different value, so it’s hidden here:

Output

npm notice run bookshop@1.0.0 npx
npm notice run 'auth' secret
Add the following to your .env file:
BETTER_AUTH_SECRET=<your-secret>

Open .env in your code editor and paste your secret after BETTER_AUTH_SECRET=. The file then looks like this:

.env

# Settings for the Bookshop. Copy this file to .env and fill in the values.

# A random secret of at least 32 characters. Generate one with: npx auth@latest secret
BETTER_AUTH_SECRET=<your-secret>

# The address the app runs on
BETTER_AUTH_URL=http://localhost:3000

# The PostgreSQL database from compose.yaml
DATABASE_URL=postgres://bookshop:local-only-password@localhost:5435/bookshop

BETTER_AUTH_URL is the address the app runs on, and DATABASE_URL points to the database you start in Step 4. Keep both as they are.

Warning: Keep .env private and out of Git, because it holds your secret. The project’s .gitignore file already keeps it out.

Step 4: Start the Database

compose.yaml describes a PostgreSQL 18 database in Docker. Start it in the background (How to Run PostgreSQL in Docker with Docker Compose explains the file):

Terminal

docker compose up -d

The first time, Docker downloads the PostgreSQL image first. Then it creates the database’s volume (its storage) and network, and starts it:

Output

[+] up 3/3
 ✔ Volume better-auth-bookshop_db-data  Created                                       0.0s
 ✔ Network better-auth-bookshop_default Created                                       0.0s
 ✔ Container better-auth-bookshop-db-1  Started                                       0.2s

The database accepts connections only from your own computer, on port 5435.

Step 5: Create Better Auth’s Tables

Better Auth keeps users, sessions, accounts and verification codes in four tables, and its migrate command creates them (Better Auth Database Tables Explained describes each one). When it asks Are you sure you want to run these migrations?, type y:

Terminal

npx auth@latest migrate

Output

npm notice run bookshop@1.0.0 npx
npm notice run 'auth' migrate
🔑 The migration will affect the following:
-> name, email, emailVerified, image, createdAt, updatedAt fields on user table.
-> expiresAt, token, createdAt, updatedAt, ipAddress, userAgent, userId fields on session table.
-> accountId, providerId, userId, accessToken, refreshToken, idToken, accessTokenExpiresAt, refreshTokenExpiresAt, scope, password, createdAt, updatedAt fields on account table.
-> identifier, value, expiresAt, createdAt, updatedAt fields on verification table.
✔ Are you sure you want to run these migrations? … yes
🚀 migration was completed successfully!

Step 6: Start the App

Terminal

npm run dev

Output

npm notice run bookshop@1.0.0 dev
npm notice run next dev
▲ Next.js 16.4.6 (Turbopack)
- Local:         http://localhost:3000
- Network:       http://192.168.x.x:3000
- Environments: .env
✓ Ready in 283ms
✓ Running next.config.ts took 2.0s
- Cache Components enabled
- Partial Prefetching enabled

Keep this terminal open: the app runs as long as it does. Open http://localhost:3000 in your browser. The Bookshop shows its books, with Sign in and Sign up in the top-right corner:

The Bookshop, running at localhost:3000.

Step 7: Create Your First Account

Click Sign up. Enter your name, your email address and a password of at least 8 characters, then click Sign up:

Create the first account.

Better Auth creates the account and signs you in. The header now shows your name:

Signed in: the header shows the name.

To sign in again later, click Sign out, then Sign in, and enter the same email address and password.

Clean Up When You’re Done

  1. Stop the app: press Ctrl+C in the terminal that runs npm run dev.
  2. Stop the database and keep its data: docker compose stop. Start it again later with docker compose start.

To remove the database and delete every account in it, run:

Terminal

docker compose down -v

Warning: docker compose down -v deletes the database’s data for good. Without -v, it removes the container and keeps the data.

Troubleshooting

ProblemFix
npm run dev stops with An error occurred while loading instrumentation hook: The settings in .env are missing or invalidThe lines below the error name each setting to fix. Check .env against Step 3.
npx auth@latest migrate prints ECONNREFUSEDThe database isn’t running. Start Docker Desktop, then run docker compose up -d.
docker compose up -d fails with ports are not available: exposing port TCP 127.0.0.1:5435 … bind: address already in useAnother program uses port 5435. In compose.yaml, change the first number in 127.0.0.1:5435:5432 to a free port, and change the port in DATABASE_URL to match.
User already exists. Use another email. on the sign-up pageThat email address already has an account: sign in instead.
Invalid email or password on the sign-in pageCheck both and try again.

FAQ

How do I run the tests?

Run npm test. It runs the five tests of the settings check with the test runner built into Node.js, so it needs no database:

Terminal

npm test

Output

npm notice run bookshop@1.0.0 test
npm notice run node --test tests/
✔ accepts complete, valid settings (0.750041ms)
✔ reports every missing setting (0.091ms)
✔ rejects a secret shorter than 32 characters (0.117208ms)
✔ rejects an app address that isn't http or https (0.077417ms)
✔ rejects a database address that isn't PostgreSQL (0.069625ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 92.585625

Where are the accounts stored?

In the PostgreSQL database from Step 4. Better Auth keeps each person in the user table and a hash of their password in the account table, never the password itself.

Does it work on Windows and Linux?

The commands are the same on Windows and Linux, except the two in Steps 1 and 3, which this guide also shows for PowerShell. This guide was run on macOS with Docker Desktop.

Conclusion

You unzipped the code, installed it, added your settings, started PostgreSQL in Docker, created Better Auth’s tables and signed up in the running app. To learn how the code works, follow the free Better Auth Tutorial for Beginners: Part 2 sets up Better Auth in Next.js, and Part 3 builds the sign-up and sign-in pages.

Additional Resources

Related

Better Auth, Next.js and other names mentioned are trademarks of their respective owners. JD Bots isn’t affiliated with or endorsed by Better Auth, Inc. or Vercel.

Exit mobile version