Skip to Content
DocumentationSetup

Setup

This section guides you through setting up your development environment for Harvide Starter.

Prerequisites

Before you begin, ensure you have the following installed on your system:

  • Node.js: Version 18.x or later. You can download it from nodejs.org .
  • Git: For version control. Download from git-scm.com .
  • Bun (recommended package manager): Install Bun by running: 
    curl -fsSL https://bun.sh/install | bash
    Alternatively, you can use:
    • npm (comes with Node.js)
    • pnpm: npm install -g pnpm
    • yarn: npm install -g yarn
  • Docker (Optional, for database setup): If you plan to use a local PostgreSQL database, Docker will simplify the setup. Download from docker.com .
  • VS Code: A popular code editor with excellent TypeScript and React support.
  • Harvide Starter CLI: The create-harvide-starter CLI tool is used to scaffold new projects. It will be installed automatically when you run bunx create-harvide-starter (or npx / pnpm dlx / yarn dlx).

Database Setup

Harvide Starter uses Drizzle ORM and supports PostgreSQL by default.

Local PostgreSQL with Docker

If you have Docker installed, you can quickly set up a local PostgreSQL instance:

docker run --name harvide-db -e POSTGRES_USER=user -e POSTGRES_PASSWORD=password -e POSTGRES_DB=database -p 5432:5432 -d postgres

This command will:

  • Run a PostgreSQL container named harvide-db.
  • Set up a user, password, and database.
  • Map port 5432 from the container to your local machine.

You can then connect to this database using the DATABASE_URL environment variable: DATABASE_URL="postgres://user:password@localhost:5432/database"

Database Migrations

After setting up your database, you’ll need to run migrations to create the necessary tables:

bun run db:migrate

(Replace bun run with your chosen package manager’s run command if different).

Environment Variables

Harvide Starter relies on environment variables for sensitive information and configuration. Create a .env file in the root of your project based on the .env.example file.

# .env example content
# PostgreSQL database connection string
DATABASE_URL="postgres://user:password@localhost:5432/database"
# Frontend URL, used for redirects, CORS and email links
NEXT_PUBLIC_CLIENT_URL="http://localhost:3000"
# Generate a secret using `openssl rand -base64 32`
BETTER_AUTH_SECRET="your_strong_auth_secret_key"
 
# Mail
# You should only set one of the following options and choose proper provider in `starter.config.ts`
 
# SMTP configuration for sending emails
# SMTP_ADAPTER=
# SMTP_HOST=
# SMTP_PORT=
# SMTP_USER=
# SMTP_PASSWORD=
 
# Resend API Key (for Resend provider)
# RESEND_API_KEY=

Important Notes for Mail Configuration:

  • Choose a Provider: In your starter.config.ts file, you specify which email provider to use ("resend", "mailgun", or "smtp"). Make sure the corresponding environment variables in your .env file are configured.
  • Required for Flows: If you enable features like email verification (auth.emailAndPassword.requireEmailVerification), password reset (auth.emailAndPassword.sendResetPassword), or email OTP (auth.emailAndPassword.otp.enabled), you must configure a mail provider in your .env file and enable email services in starter.config.ts.
  • NEXT_PUBLIC_CLIENT_URL: This variable is crucial for generating correct links in emails (e.g., verification links, password reset links) as it’s used for redirects and email link generation. Ensure it’s set to your application’s public URL.

Ensure your BETTER_AUTH_SECRET is a strong, randomly generated string for security.

Once your environment is set up, you’re ready to start developing with Harvide Starter!

Getting StartedProject Structure