5-Minute Quickstart

This guide will get you up and running with the BISO Sites monorepo in about 5 minutes. We'll skip the theory and focus on getting the applications running on your machine.

Goal

Install dependencies and boot all three applications locally.
Confirm Fast Refresh works by editing a component.
Learn the core commands you'll use daily (dev, build, lint, check-types).

ℹ️

Prerequisites

Before starting, make sure you have:

Node.js 18+ installed
Bun 1.3+ installed (install here)
Git for version control

Quick Setup

Clone the repository

git clone <repository-url>
cd biso-sites

Install dependencies

Bun makes this super fast:

bun install

This installs all dependencies for all apps and packages in the monorepo.

Configure environment variables (optional)

For basic development, you can skip this. The apps will work with mock data.

For full functionality with Appwrite:

# In apps/web/
cp .env.example .env.local

# In apps/admin/
cp .env.example .env.local

📝

See Installation Guide for detailed environment configuration.

Start all development servers

bun run dev

This starts all three applications simultaneously:

Web (port 3000)
Admin (port 3001)
Docs (port 3002)

⚠️

First build may take a moment

The first time you run this, Next.js needs to compile everything. Subsequent runs will be much faster thanks to caching.

Open the applications

Once the servers are running, open these URLs:

Web: http://localhost:3000 - Public website
Admin: http://localhost:3001 - Admin dashboard
Docs: http://localhost:3002 - Documentation

✅

You're running!

All three applications should now be running. Try navigating around and exploring the interfaces.

Start the dev server your way

Keep the entire stack in sync when you need to QA end-to-end flows.

# start web, admin, and docs together
bun run dev

Making Your First Change

Let's verify hot reload works by making a small change:

Open a component file

Open apps/web/src/app/page.tsx in your editor.

Make a change

Change any text on the page and save the file.

See it update

Switch to your browser - the change should appear automatically without refreshing! This is Next.js Fast Refresh in action.

Common Commands

Here are the most common commands you'll use:

# Development
bun run dev                    # Start all apps
bun run dev --filter=web       # Start specific app

# Build
bun run build                  # Build all apps
bun run build --filter=web     # Build specific app

# Type checking
bun run check-types            # Check TypeScript across all packages

# Linting
bun run lint                   # Lint all packages
bun run format                 # Format code with Prettier

ℹ️

Need the rest of the scripts? The Commands Reference covers every Bun and Turbo command plus when to run them.

Project Structure at a Glance

📁apps/

📁web/

📁src/app/

📁src/components/

📁messages/

📁admin/

📁src/app/(admin)/

📁src/components/

📁docs/

📄app/(home)/page.tsx

📁content/docs/

📁packages/

📁api/

📁payment/

📁ui/

📁editor/

📁configs/

⚙️package.json

⚙️turbo.json

⚙️bun.lock

Troubleshooting

Port already in use?

If you see errors about ports being taken:

# Find and kill processes on specific ports
lsof -ti:3000 | xargs kill -9  # Web
lsof -ti:3001 | xargs kill -9  # Admin
lsof -ti:3002 | xargs kill -9  # Docs

Or change the port in each app's package.json:

{
  "scripts": {
    "dev": "next dev -p 3050"  // Use different port
  }
}

Module not found errors?

Try reinstalling dependencies:

# Clear node_modules and reinstall
rm -rf node_modules apps/*/node_modules packages/*/node_modules
bun install

Type errors?

Generate Next.js types:

bun run check-types

Next Steps

Now that you have everything running:

Understand the Architecture - Read the Architecture Overview to understand how everything fits together
Explore the Packages - Check out the API Package documentation to see how to use shared code
Development Workflow - Learn the Development Workflow for day-to-day development
Create Your First Feature - Follow the Creating Features guide to build something new