Book by Book

Milestone 1 implementation includes:

• Google OAuth sign-in
• Google Books search and import/cache
• Book detail page backed by local Postgres cache

Required Environment Variables

Create .env.local with:

AUTH_SECRET=your-long-random-secret

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_BOOKS_API_KEY=...

DATABASE_URL=postgres://...

Optional:

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=...
LOG_LEVEL=<trace|debug|info|warn|error|fatal|silent>
CACHE_PROVIDER=<disabled|memory|redis|upstash>
CACHE_REDIS_URL=redis://...
CACHE_UPSTASH_REST_URL=...
CACHE_UPSTASH_REST_TOKEN=...

Generate a strong secret:

openssl rand -base64 32

Google Cloud OAuth redirect URI must include:

http://localhost:3000/api/auth/callback/google

Database Setup

Schema file:

db/schema/data.sql

The SQL expects $APP_USER_PASSWORD to be substituted when creating the app DB user:

export APP_USER_PASSWORD="replace-me"
envsubst < db/schema/data.sql | psql "$DATABASE_URL"

Or bootstrap local PostgreSQL with Docker and apply schema + migrations:

./scripts/setup-local-postgres.sh

Optional env overrides for Docker setup:

PG_CONTAINER_NAME=book-by-book-postgres
PG_IMAGE=postgres:18
PG_PORT=54329
PG_SUPERUSER=postgres
PG_SUPERUSER_PASSWORD=postgres
LOCAL_DB_NAME=book_by_book_local
APP_USER_PASSWORD=local-dev-password
PG_VOLUME_NAME=book-by-book-postgres-data
PG_VOLUME_MOUNT=/var/lib/postgresql

Clean up the local Docker PostgreSQL container and volume:

./scripts/cleanup-local-postgres.sh

Optional env overrides for cleanup:

PG_CONTAINER_NAME=book-by-book-postgres
PG_VOLUME_NAME=book-by-book-postgres-data
REMOVE_VOLUME=1

Run

pnpm dev

next dev, next build, and next start now validate the required application environment before the app fully boots. Missing or invalid values fail fast with one aggregated error message.

LOG_LEVEL controls server log verbosity for the shared Pino logger. It defaults to info. Set LOG_LEVEL=debug to emit repository debug logs, or LOG_LEVEL=silent to suppress them.

When you run npm start or pnpm start, a prestart hook now verifies that local PostgreSQL is reachable at localhost:54329 when DATABASE_URL targets the local dev database. If it is not running, start it with:

./scripts/setup-local-postgres.sh

Quality Gates

pnpm test
pnpm test:integration
pnpm lint
pnpm build

pnpm test and pnpm test:integration do not load .env or .env.local; they use fixed in-repo test fixtures instead.

pnpm test:integration requires Docker and provisions its own PostgreSQL 18 Testcontainers instance for the duration of the Vitest process.