Skip to main content
This guide walks you through installing Coffee Finder and getting it running on your local machine. Coffee Finder is built with Next.js 16, TypeScript, and uses Bun as the package manager.

​
Prerequisites

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

Install Bun

Coffee Finder uses Bun as its package manager and runtime. Install Bun by running:
curl -fsSL https://bun.sh/install | bash
Verify the installation:
bun --version
Bun is a fast all-in-one JavaScript runtime that serves as a drop-in replacement for Node.js. It includes a package manager, bundler, and test runner.
2

Install Node.js (optional)

While Bun is the primary runtime, some tools may require Node.js. Install Node.js 18+ if needed:
# Using nvm (recommended)
nvm install 18
nvm use 18
Visit nodejs.org for other installation methods.
3

Verify Git installation

Ensure Git is installed on your system:
git --version
If not installed, download it from git-scm.com.

​
Clone the repository

Clone the Coffee Finder repository to your local machine: 
git clone https://github.com/your-org/coffee-finder.git
cd coffee-finder
If you’re forking the project, replace the URL with your fork’s URL.

​
Install dependencies

Install all required packages using Bun: 
bun install
This command installs all dependencies defined in package.json, including:
  • Next.js 16 - React framework with App Router
  • TypeScript 5 - Type-safe JavaScript
  • Tailwind CSS 4 - Utility-first CSS framework
  • Prisma 6 - Database ORM
  • shadcn/ui - UI component library
  • Leaflet - Interactive map library
  • React Query - Data fetching and caching
  • Zustand - State management
The complete list of dependencies can be found in /home/daytona/workspace/source/package.json.

​
Database setup

Coffee Finder uses SQLite with Prisma ORM for data persistence. The database stores user information and posts.
1

Configure database URL

Create a .env file in the project root:
touch .env
Add the database connection string:
.env
DATABASE_URL="file:./db/custom.db"
SQLite is used by default for simplicity. For production, consider PostgreSQL or MySQL.
2

Review the Prisma schema

The database schema is defined in prisma/schema.prisma:
prisma/schema.prisma
datasource db {
  provider = "sqlite"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

model Post {
  id        String   @id @default(cuid())
  title     String
  content   String?
  published Boolean  @default(false)
  authorId  String
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}
3

Generate Prisma client

Generate the Prisma client based on your schema:
bun run db:generate
This command runs prisma generate and creates the TypeScript types for your database.
4

Push database schema

Create the database and tables:
bun run db:push
This command runs prisma db push and synchronizes your schema with the database.
Use db:push for development. For production, use migrations with bun run db:migrate.

​
Environment variables

Coffee Finder requires minimal environment configuration. Create a .env file with the following variables:
.env
# Database
DATABASE_URL="file:./db/custom.db"
VariableRequiredDescriptionDefault
DATABASE_URLYesPrisma database connection stringfile:./db/custom.db
Coffee Finder uses the public Overpass API endpoint (https://overpass-api.de/api/interpreter) directly in the code. No API key is required.

​
Verify installation

Start the development server to verify everything is working: 
bun run dev
You should see output similar to: 
▲ Next.js 16.1.1
- Local:        http://localhost:3000
- Environments: .env

✓ Ready in 2.1s
Open http://localhost:3000 in your browser. You should see the Coffee Finder application with an interactive map.
The application requests geolocation permission to show coffee shops near your location. Grant permission for full functionality.

​
Available scripts

The following scripts are available in package.json:
ScriptCommandDescription
devbun run devStart development server on port 3000
buildbun run buildBuild for production with standalone output
startbun run startStart production server
lintbun run lintRun ESLint for code quality
db:pushbun run db:pushPush schema changes to database
db:generatebun run db:generateGenerate Prisma client
db:migratebun run db:migrateRun database migrations
db:resetbun run db:resetReset database to initial state

​
Troubleshooting

If Bun installation fails, try:
  1. Ensure you have curl installed: curl --version
  2. Use npm as alternative: npm install -g bun
  3. Check system requirements at bun.sh
If you encounter database errors:
  1. Verify .env file exists with DATABASE_URL
  2. Ensure db directory exists: mkdir -p db
  3. Run bun run db:push to create the database
  4. Check file permissions on the db directory
If port 3000 is occupied:
# Use a different port
bun run dev -- -p 3001
Or kill the process using port 3000:
# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F
The project uses ignoreBuildErrors: true in next.config.ts for flexibility. To enable strict type checking:
  1. Edit next.config.ts
  2. Set ignoreBuildErrors: false
  3. Run bun run lint to check for issues

​
Next steps

Now that you have Coffee Finder installed:

Build docs developers (and LLMs) love

Get started for freeTalk to us