Skip to content

Setup & Local Development

Complete guide for setting up the Eventify platform locally.

Prerequisites

  • Node.js 20+ and npm
  • Python 3.11+ (for MkDocs documentation)
  • Wrangler CLI for Cloudflare development
  • Git for version control

Quick Start

1. Clone & Install

git clone https://github.com/kinguru-io/kinguru-next.git
cd kinguru-next
npm install

2. Environment Variables

Create .dev.vars in the project root:

# Authentication
NEXTAUTH_SECRET="your-secret-key-min-32-chars"
NEXTAUTH_URL="http://localhost:3000"

# Database
DATABASE_URL="file:./dev.db"

# Email (Brevo)
BREVO_API_KEY="your-brevo-api-key"
EMAIL_FROM="noreply@eventify.today"

# Stripe
STRIPE_SECRET_KEY="sk_test_..."
STRIPE_PUBLISHABLE_KEY="pk_test_..."
STRIPE_WEBHOOK_SECRET_KEY="whsec_..."

# Mapbox
MAPBOX_TOKEN="your-mapbox-token"

# R2 Storage (Cloudflare)
R2_ENDPOINT_URL="https://YOUR_ACCOUNT_ID.r2.cloudflarestorage.com"
R2_ACCESS_KEY_ID="your-r2-access-key"
R2_SECRET_ACCESS_KEY="your-r2-secret-key"
R2_BUCKET_NAME="eventify-storage-dev"
R2_REGION="auto"
R2_PUBLIC_URL="https://static.dev.eventify.today"

3. Database Setup

Local SQLite (Development)

# Generate Prisma client
npx prisma generate

# Run migrations
npm run db:migrate:local

# Seed with fake data
npm run seed

Cloudflare D1 (Staging/Production)

# Generate migration from Prisma schema
npm run prisma:generate-migration

# Apply to staging
npm run db:migrate:staging

# Apply to production
npm run db:migrate:production

4. Start Development Server

# Start Next.js dev server with Wrangler
npx wrangler dev

# Or use npm script
npm run dev

Visit http://localhost:3000

Project Scripts

Development

npm run dev              # Start dev server with Wrangler
npm run build            # Build for production
npm run build:opennext   # Build with OpenNext adapter for Cloudflare
npm run preview          # Preview production build locally
npm run lint             # Run ESLint
npm run lint:fix         # Fix ESLint issues

Database

npm run prisma:generate-migration  # Generate D1 migration from Prisma
npm run db:migrate:local           # Run migrations locally
npm run db:migrate:staging         # Run migrations on staging
npm run db:migrate:production      # Run migrations on production
npm run seed                       # Seed local database with fake data

Testing

npm run test             # Run Vitest tests
npm run test:watch       # Watch mode
npm run storybook        # Component development
npm run build-storybook  # Build Storybook

Documentation

npm run docs:dev         # Start documentation server
npm run docs:build       # Build documentation

Styling

npm run prepare          # Generate Panda CSS (runs automatically)

Architecture Overview

Tech Stack

  • Framework: Next.js 15 (App Router)
  • Hosting: Cloudflare Pages + Workers
  • Database: Cloudflare D1 (SQLite)
  • ORM: Prisma
  • Styling: Panda CSS
  • Auth: NextAuth.js
  • Payments: Stripe
  • Email: Brevo (formerly Sendinblue)
  • Storage: Cloudflare R2
  • i18n: next-intl (English/Polish)

Project Structure

src/
├── app/                    # Next.js App Router
│   └── [locale]/          # Internationalized routes
├── components/            # React components
│   ├── uikit/            # Design system
│   └── {domain}/         # Domain-specific components
├── lib/
│   ├── actions/          # Server actions (business logic)
│   ├── shared/           # Shared utilities & configs
│   └── utils/            # Pure utility functions
├── server/               # Server-side code
└── auth.ts              # NextAuth configuration

docs/
├── content/             # Documentation markdown
└── mkdocs.yml          # MkDocs configuration

prisma/
├── schema.prisma       # Database schema
└── migrations/         # D1 migrations

Key Patterns

Internationalization: All routes under [locale] (en/pl) 

import { useTranslations } from "next-intl";
import { Link, redirect } from "@/navigation";

Server Actions: Business logic in src/lib/actions/ 

"use server"
export async function createBooking(data: BookingData) {
  // Validation, DB operations, Stripe integration
}

Styling: Panda CSS with design tokens 

import { css } from "~/styled-system/css";
import { Stack } from "~/styled-system/jsx";

Cloudflare Development

Wrangler Configuration

Main config in wrangler.jsonc:

{
  "name": "eventify-dev",
  "compatibility_flags": ["nodejs_compat"],
  "d1_databases": [{
    "binding": "DB",
    "database_name": "DEV_DB",
    "database_id": "local"
  }],
  "r2_buckets": [{
    "binding": "R2",
    "bucket_name": "eventify-storage-dev"
  }]
}

Type Generation

Generate TypeScript types for Cloudflare bindings:

npm run cf-typegen

This creates cloudflare-env.d.ts with types for D1, R2, and other bindings.

Troubleshooting

Build Fails with R2 Connection Error

Issue: CI build tries to connect to Wrangler bindings during build.

Solution: Cloudflare initialization is automatically skipped during builds. If you see this error: - Check next.config.mjs has conditional initOpenNextCloudflareForDev() - Ensure SKIP_CLOUDFLARE_INIT=true in build scripts

Database Migration Conflicts

Issue: Prisma schema changes don't match D1 migrations.

Solution: 1. Update prisma/schema.prisma 2. Generate migration: npm run prisma:generate-migration 3. Review generated SQL in migrations/ 4. Apply: npm run db:migrate:local

Styling Not Updating

Issue: Panda CSS changes not reflected.

Solution: 

npm run prepare  # Regenerate Panda CSS

Panda watches for changes automatically during npm run dev.

Email Not Sending

Issue: Emails failing in development.

Solution: - Check BREVO_API_KEY in .dev.vars - Verify sender email is verified in Brevo dashboard - Check Brevo logs for delivery status

Next Steps