Skip to content

README.md

Latest commit

 

History

History
209 lines (142 loc) · 7.91 KB

README.md

File metadata and controls

209 lines (142 loc) · 7.91 KB
Raw

@better-auth-cloudflare/cli

NPM Version NPM Downloads License: MIT

Part of the Better Auth Cloudflare ecosystem - A complete authentication solution for Cloudflare Workers with Better Auth, featuring ready-to-use templates and integrations.

Generate a Better Auth Cloudflare project with D1, KV, R2, or Hyperdrive. This CLI tool provides scaffolding for both Hono and Next.js (OpenNext.js) applications with automatic Cloudflare resource setup.

Note: The generate command configures one primary database (D1, Postgres via Hyperdrive, or MySQL via Hyperdrive). You can add additional database connections manually after project creation.

What This CLI Replaces

The generate command eliminates manual project setup:

🏗️ Creates complete Hono or Next.js projects with pre-configured auth (more types coming)

  • Sets up TypeScript configs, package.json scripts, file structure, and API routes
  • Creates database adapters for D1, Postgres, or MySQL

☁️ Handles Cloudflare resource creation:

  • Runs wrangler d1/kv/r2 create commands and configures wrangler.toml
  • Sets up Hyperdrive connections and auth integrations

📦 Runs initial setup: @better-auth/cli generate, drizzle-kit generate, and optionally applies migrations

🚀 Deploys to Cloudflare Workers when resources are set up (automatic in non-interactive mode, prompted in interactive mode)

The migrate command streamlines schema updates:

🔄 Handles the workflow when you modify auth configuration: generates auth schema, creates Drizzle migrations, and optionally applies them

Quick Start

Check version and get help:

npx @better-auth-cloudflare/cli --version    # Show version
npx @better-auth-cloudflare/cli -v           # Show version (short)
npx @better-auth-cloudflare/cli version      # Show version (command)
npx @better-auth-cloudflare/cli              # Show help with version

Interactive mode (asks questions):

npx @better-auth-cloudflare/cli generate

Non-interactive mode (use arguments):

# Simple D1 app with KV (ready to run)
npx @better-auth-cloudflare/cli generate \
  --app-name=my-auth-app \
  --template=hono \
  --database=d1 \
  --kv=true \
  --r2=false \
  --apply-migrations=dev

Migration workflow:

npx @better-auth-cloudflare/cli migrate              # Interactive
npx @better-auth-cloudflare/cli migrate --migrate-target=dev  # Non-interactive

migrate searches the current directory and its parents for wrangler.json, then wrangler.jsonc, then wrangler.toml. It handles:

  • D1 databases with local and remote migration options
  • Hyperdrive databases with migration guidance

Arguments

--app-name=<name>              Project name (default: my-app)
--template=<template>          hono | nextjs (default: hono)
--database=<db>                d1 | hyperdrive-postgres | hyperdrive-mysql (default: d1)
--geolocation=<bool>           Enable geolocation tracking (default: true)
--kv=<bool>                    Use KV as secondary storage for Better Auth (default: true)
--r2=<bool>                    Enable R2 to extend Better Auth with user file storage (default: false)

KV Integration: Provides session caching and legacy Better Auth 1.5/1.6 secondary-storage fallbacks. Better Auth 1.7 requires atomic verification and rate-limit operations that Workers KV cannot provide. See the repository's KV configuration guide before upgrading.

R2 Integration: Enables file upload and management capabilities. See R2 setup guide for detailed configuration and usage.

Database-specific arguments

--d1-name=<name>               D1 database name (default: <app-name>-db)
--d1-binding=<binding>         D1 binding name (default: DATABASE)
--hd-name=<name>               Hyperdrive instance name (default: <app-name>-hyperdrive)
--hd-binding=<binding>         Hyperdrive binding name (default: HYPERDRIVE)
--hd-connection-string=<url>   Database connection string (required for hyperdrive)

Storage arguments

--kv-binding=<binding>         KV binding name (default: KV)
--kv-namespace-name=<name>     KV namespace name (default: <app-name>-kv)
--r2-binding=<binding>         R2 binding name (default: R2_BUCKET)
--r2-bucket-name=<name>        R2 bucket name (default: <app-name>-files)

Cloudflare account arguments

--account-id=<id>              Cloudflare account ID (only required if you have multiple accounts)
--skip-cloudflare-setup=<bool> Skip Cloudflare resource creation and deployment (default: false)
--apply-migrations=<choice>    Apply D1 migrations: dev | prod | skip (default: skip)

Migrate command arguments

--migrate-target=<target>      For migrate command: dev | remote | skip (default: skip)

Examples

Create a Hono app with D1 database:

npx @better-auth-cloudflare/cli generate --app-name=my-hono-app --template=hono --database=d1

Create a Next.js app with PostgreSQL via Hyperdrive:

npx @better-auth-cloudflare/cli generate --app-name=my-next-app --template=nextjs \
  --database=hyperdrive-postgres --hd-connection-string=postgres://user:pass@host:5432/db

Create app without KV or R2:

npx @better-auth-cloudflare/cli generate --app-name=minimal-app --kv=false --r2=false

Create and deploy in one command (default behavior):

npx @better-auth-cloudflare/cli generate --app-name=my-app
# Creates resources, runs migrations, and deploys automatically

Skip Cloudflare setup and deployment (useful for CI/CD):

npx @better-auth-cloudflare/cli generate --app-name=ci-app --skip-cloudflare-setup=true
# Only generates project files, no Cloudflare resources or deployment

Specify account ID for non-interactive mode:

npx @better-auth-cloudflare/cli generate --app-name=prod-app --account-id=your-account-id

Apply migrations automatically in non-interactive mode:

npx @better-auth-cloudflare/cli generate --app-name=auto-app --apply-migrations=dev

Run migration workflow interactively:

npx @better-auth-cloudflare/cli migrate

Run migration workflow with non-interactive target:

npx @better-auth-cloudflare/cli migrate --migrate-target=dev

Creates a new Better Auth Cloudflare project from Hono or OpenNext.js templates, optionally creating Cloudflare D1, KV, R2, or Hyperdrive resources for you. The migrate command runs auth:update, db:generate, and optionally db:migrate.

Troubleshooting

Error ...Error [ERR_REQUIRE_ESM]: require() of ES Module...:

Loading ECMAScript modules using require() should be supported by your nodejs. Make sure your node version is at least v23.0.0, v22.12.0, or v20.19.0, depending on the major version you use. Read more here

Related

  • 📦 better-auth-cloudflare - Main package and documentation
  • 🌐 Better Auth - The authentication library powering this ecosystem
  • 📚 Examples - Ready-to-use templates and implementations
  • 🐛 Issues - Bug reports, typos, and support

License

MIT

Contributing

Contributions are welcome! Whether it's bug fixes, feature additions, or documentation improvements, we appreciate your help in making this project better. For major changes or new features, please open an issue first to discuss what you would like to change.