Local Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Node.js

Version 18 or higher required

node --version

pnpm

Recommended package manager

npm install -g pnpm

Git

Version control system

git --version

Code Editor

VS Code recommended with TypeScript support

Installation Steps

Clone the Repository

Clone the repository to your local machine:

git clone <repository-url>
cd your-bible

Or if you’ve forked it:

git clone https://github.com/YOUR_USERNAME/your-bible.git
cd your-bible

Install Dependencies

Install all project dependencies using pnpm:

pnpm install

First installation may take a few minutes as it downloads all packages and dependencies.

Alternative package managers:

npm install

Environment Configuration

Copy the example environment file:

cp .env.example .env

Now you’ll need to configure each environment variable. See the detailed Environment Variables guide for complete information.

Service Configuration

1. API.Bible Setup

Get API Key

Visit API.Bible
Sign up for a free account
Navigate to “API Keys” section
Create a new API key

Configure Environment

Add to your .env file:

API_BASE_URL=https://api.scripture.api.bible/v1
API_KEY=your_api_bible_key_here

2. Convex Backend Setup

Convex provides real-time database and backend functionality for collections, notes, and stories.

Create Convex Account

Visit Convex.dev
Sign up with GitHub or email
Create a new project

Install Convex CLI

pnpm add -g convex

Initialize Convex

Run the Convex development server:

npx convex dev

This will:

Log you in (if first time)
Create/link a project
Deploy your schema
Generate environment variables

Configure Environment

Convex will automatically add these to your .env:

CONVEX_DEPLOYMENT=your_deployment_name
VITE_CONVEX_URL=https://your-project.convex.cloud

3. PostgreSQL Database Setup

Using Neon (Recommended)
Using Local PostgreSQL

Create Neon Account

Visit Neon.tech
Sign up for a free account
Create a new project

Get Connection String

Go to your project dashboard
Copy the connection string
It should look like: postgresql://user:password@host/database

Configure Environment

DATABASE_URL=postgresql://user:password@ep-xxx.region.neon.tech/dbname?sslmode=require

Run Migrations

pnpm drizzle-kit push

Install PostgreSQL

macOS: brew install postgresql
Ubuntu: sudo apt-get install postgresql
Windows: Download from postgresql.org

Start PostgreSQL

# macOS/Linux
brew services start postgresql
# or
sudo service postgresql start

Create Database

createdb yourbible

Configure Environment

DATABASE_URL=postgresql://localhost/yourbible

Run Migrations

pnpm drizzle-kit push

4. Better Auth Configuration

Generate Auth Secret

Generate a secure random string for your auth secret:

openssl rand -base64 32

Configure Environment

BETTER_AUTH_SECRET=your_generated_secret_here
BETTER_AUTH_URL=http://localhost:5173

Optional: GitHub OAuth

If you want to enable GitHub authentication:

Go to GitHub Settings > Developer settings > OAuth Apps
Create a new OAuth App
Set authorization callback URL: http://localhost:5173/api/auth/callback/github
Add to .env:

GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret

5. Google Gemini AI Setup

Get Gemini API Key

Visit Google AI Studio
Sign in with your Google account
Click “Get API Key”
Create a new API key

Configure Environment

GEMINI_MODEL=gemini-1.5-flash
GEMINI_API_KEY=your_gemini_api_key_here

gemini-1.5-flash is recommended for its balance of speed and quality. You can also use gemini-1.5-pro for better quality at higher cost.

6. Redis/Upstash Setup

Redis is used for rate limiting story generation to manage API costs (5 stories per day per user).

Create Upstash Account

Visit Upstash
Sign up for a free account
Create a new Redis database

Get Connection Details

From your Upstash dashboard:

Click on your database
Go to “REST API” section
Copy the connection details

Configure Environment

REDIS_URL=your_redis_url_here
KV_URL=your_kv_url_here
KV_REST_API_URL=your_kv_rest_api_url_here
KV_REST_API_TOKEN=your_kv_rest_api_token_here
KV_REST_API_READ_ONLY_TOKEN=your_kv_rest_api_read_only_token_here

7. Optional: UploadThing (Future Feature)

UploadThing Configuration

If you plan to implement file upload features:

Visit UploadThing
Create an account and project
Get your token from the dashboard
Add to .env:

UPLOADTHING_TOKEN=your_uploadthing_token_here

Running the Development Server

Start Convex

In one terminal, run Convex in development mode:

npx convex dev

Keep this terminal running. It will:

Watch for schema changes
Hot reload functions
Provide real-time sync

Start Development Server

In another terminal, start the Vite development server:

pnpm dev

The application will be available at:

http://localhost:5173

The development server includes:

Hot Module Replacement (HMR)
Fast refresh for React components
TypeScript checking
Automatic route generation

Verification Steps

1. Check Application Loads

Open http://localhost:5173 and verify:

Page loads without errors
No console errors in browser DevTools
Navigation works

2. Test API.Bible Connection

Select a Bible translation from dropdown
Navigate to Genesis chapter 1
Verify verses load correctly

3. Test Authentication

Click “Sign In”
Create a new account with email
Verify successful sign-in
Check that protected routes are now accessible

4. Test Convex Integration

Create a new collection
Add a verse to the collection
Verify data persists after page refresh

5. Test AI Story Generation

Navigate to Stories section
Create a new story
Fill in all required fields
Generate a story
Verify story appears correctly

Common Issues and Troubleshooting

Port Already in Use

If port 5173 is already in use:

# Find and kill the process using port 5173
lsof -ti:5173 | xargs kill -9

# Or specify a different port
pnpm dev --port 3000

Convex Connection Issues

If Convex fails to connect:

Verify VITE_CONVEX_URL is set correctly
Check Convex dashboard for deployment status
Try restarting npx convex dev
Clear browser cache and reload

API.Bible Not Loading

If Bible content fails to load:

Verify API_KEY is valid
Check API key hasn’t expired
Verify API_BASE_URL is correct: https://api.scripture.api.bible/v1
Check browser console for specific error messages
Verify API key has necessary permissions

Database Connection Errors

If you see database connection errors:

# Verify PostgreSQL is running
pg_isready

# Check connection string format
echo $DATABASE_URL

# Test connection with psql
psql $DATABASE_URL

# Retry migrations
pnpm drizzle-kit push

Authentication Not Working

If sign-in/sign-up fails:

Verify BETTER_AUTH_SECRET is set
Check BETTER_AUTH_URL matches your dev server URL
Verify database migrations ran successfully
Clear cookies and try again
Check browser console for errors

Story Generation Failing

If AI story generation fails:

Verify GEMINI_API_KEY is valid
Check API key has necessary permissions
Verify Redis is connected (for rate limiting)
Check browser console and server logs
Ensure you haven’t exceeded rate limit (5 stories/day)

Rate Limiting Issues

If rate limiting isn’t working:

Verify all Redis environment variables are set
Test Redis connection in Upstash dashboard
Check KV_REST_API_TOKEN is valid
Restart development server

TypeScript Errors

If you see TypeScript errors:

# Restart TypeScript server in VS Code
# Command Palette: TypeScript: Restart TS Server

# Clear TypeScript cache
rm -rf node_modules/.vite

# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install

Module Not Found Errors

If you see “Cannot find module” errors:

Verify all dependencies are installed: pnpm install
Check tsconfig.json paths are configured
Restart development server
Clear Vite cache: rm -rf node_modules/.vite

Development Tools

Recommended VS Code Extensions

ES7+ React/Redux/React-Native snippets: React snippets
Tailwind CSS IntelliSense: Tailwind autocompletion
TypeScript: Built-in, ensure it’s enabled
ESLint: Code linting
Prettier: Code formatting
Error Lens: Inline error display

Browser DevTools

React Developer Tools: Inspect React component tree
TanStack Query Devtools: Built into the app (bottom left corner in dev mode)
Network Tab: Monitor API requests
Console: Check for errors and warnings

Build and Production Testing

Building for Production

pnpm build

This creates an optimized production build in the dist directory.

Testing Production Build Locally

# Build the application
pnpm build

# Preview the production build
pnpm preview

The production preview will be available at http://localhost:4173

Production Checklist

Before Deploying

Next Steps

Now that your local environment is set up:

Read the Project Structure guide to understand the codebase
Review the Database Schema documentation
Explore the Integrations to understand external services
Check the Contributing Guide before making changes

Ready to Contribute?

Learn how to contribute code, documentation, and improvements to Your Bible.

Contributing Guide

Project Structure

​Prerequisites

Node.js

pnpm

Git

Code Editor

​Installation Steps

​Service Configuration

​1. API.Bible Setup

​2. Convex Backend Setup

​3. PostgreSQL Database Setup

​4. Better Auth Configuration

​5. Google Gemini AI Setup

​6. Redis/Upstash Setup

​7. Optional: UploadThing (Future Feature)

​Running the Development Server

​Verification Steps

​Common Issues and Troubleshooting

​Development Tools

​Recommended VS Code Extensions

​Browser DevTools

​Build and Production Testing

​Building for Production

​Testing Production Build Locally

​Production Checklist

​Next Steps

Ready to Contribute?

Prerequisites

Installation Steps

Service Configuration

1. API.Bible Setup

2. Convex Backend Setup

3. PostgreSQL Database Setup

4. Better Auth Configuration

5. Google Gemini AI Setup

6. Redis/Upstash Setup

7. Optional: UploadThing (Future Feature)

Running the Development Server

Verification Steps

Common Issues and Troubleshooting

Development Tools

Recommended VS Code Extensions

Browser DevTools

Build and Production Testing

Building for Production

Testing Production Build Locally

Production Checklist

Next Steps