Development Setup

This guide will help you set up LiveDash for local development.

Prerequisites

• Node.js (LTS version 18.18+ or 20.4+)
• pnpm (preferred package manager)
• Git
• VS Code (recommended IDE)

Installing pnpm

# Windows (via npm)
npm install -g pnpm

# macOS (via Homebrew)
brew install pnpm

# Linux (via npm)
npm install -g pnpm

Quick Start

1. Clone the Repository

git clone https://github.com/kjanat/livedash-node.git
cd livedash-node

2. Install Dependencies

pnpm install

3. Set Up Environment Variables

Copy the example environment files and configure them:

# Create local environment file
cp .env.local.example .env.local

# Create Cloudflare development file
cp .dev.vars.example .dev.vars

See the Environment Variables guide for detailed configuration.

4. Set Up the Database

Apply database migrations to your local D1 database:

# Apply migrations to local D1
pnpm run seedLocalD1

# Generate Prisma client
pnpm run prisma:generate

5. Start Development Server

# Start Next.js development server (recommended)
pnpm run dev

The application will be available at http://localhost:3000.

Default Login Credentials

For local development, use these default credentials:

• Email: [email protected]
• Password: admin123

Development Environments

Next.js Development (Recommended)

pnpm run dev

• URL: http://localhost:3000
• Runtime: Node.js
• Database: Local Cloudflare D1 (SQLite)
• Hot Reload: ✅ Enabled
• Auth: Full Auth.js v5 support

Cloudflare Workers Preview

pnpm run preview

• URL: http://localhost:3000
• Runtime: Cloudflare Workers (workerd)
• Database: Local Cloudflare D1 (SQLite)
• Hot Reload: ❌ Requires rebuild
• Auth: Production-like environment

Database Management

Local Database Operations

# Apply migrations to local D1
pnpm run seedLocalD1

# View database with Prisma Studio
pnpm run prisma:studio

# Generate Prisma client after schema changes
pnpm run prisma:generate

# Create new migration
pnpm run prisma:migrate

# Query D1 database directly
pnpm run d1:query

# Export database backup
pnpm run d1:backup

Database Schema Changes

When modifying the Prisma schema:

1. Update prisma/schema.prisma
2. Generate migration: pnpm run prisma:migrate
3. Apply to local D1: pnpm run seedLocalD1
4. Regenerate client: pnpm run prisma:generate

Code Quality & Formatting

Auto-formatting

# Format all code (Prettier)
pnpm run format

# Check formatting without changes
pnpm run format:check

# Fix linting issues
pnpm run lint:fix

# Fix markdown linting
pnpm run lint:md:fix

Pre-commit Setup

The project uses automated formatting. Configure your IDE:

VS Code Settings

Add to .vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  }
}

Project Structure

livedash-node/
├── app/             # Next.js App Router
│   ├── (auth)/          # Auth-related pages
│   ├── api/             # API routes
│   └── dashboard/       # Dashboard pages
├── components/      # React components
│   ├── ui/              # shadcn/ui components
│   └── charts/          # Chart components
├── lib/             # Utility functions
│   ├── auth.ts          # Auth.js configuration
│   ├── db.ts            # Database utilities
│   └── utils.ts         # General utilities
├── prisma/          # Database schema & migrations
├── public/          # Static assets
├── scripts/         # Build and utility scripts
├── .wiki/           # Project documentation
└── types/           # TypeScript type definitions

Common Development Tasks

Adding New Components

# Create new shadcn/ui component
npx shadcn@latest add [component-name]

# Example: Add a new button variant
npx shadcn@latest add button

Working with Auth.js

The project uses Auth.js v5 with Cloudflare D1 adapter:

// lib/auth.ts - Main auth configuration
import { NextAuth } from "next-auth"
import { D1Adapter } from "@auth/d1-adapter"

export const {
  handlers: { GET, POST },
  auth,
  signIn,
  signOut,
} = NextAuth({
  adapter: D1Adapter(env.DB),
  // ... configuration
})

Adding New Pages

1. Create page in app/ directory
2. Add to navigation in components/nav/
3. Update TypeScript types if needed

Troubleshooting

Common Issues

"Cannot find module" errors

# Clear Next.js cache and reinstall
rm -rf .next node_modules
pnpm install

Database connection issues

# Reset local D1 database
pnpm run seedLocalD1

Auth/CSRF errors

• Try using Chrome instead of VS Code's embedded browser
• Check console logs for specific error messages
• Verify environment variables are set correctly

Hot reload not working

# Restart development server with Turbopack
pnpm run dev

Getting Help

• Check the Environment Variables guide
• Review the Deployment Guide
• Check project issues: GitHub Issues
• Consult the Main Repository

IDE Extensions (VS Code)

Recommended extensions for the best development experience:

• ES7+ React/Redux/React-Native snippets
• Prettier - Code formatter
• ESLint
• Tailwind CSS IntelliSense
• Prisma
• TypeScript Importer
• Auto Rename Tag
• Bracket Pair Colorizer

Install all at once:

code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension prisma.prisma