🚀 Getting Started

Welcome to the Sharing Excess development team! 🎉 This guide will get you from zero to hero in no time. We'll walk you through everything you need to start contributing to our food rescue platform.

🛠️ What You'll Need

Before we dive in, let's make sure you have all the tools you need. Don't worry if you don't have everything yet – we'll help you get set up!

📋 Required Tools

Bun (our JavaScript runtime and package manager)

Version: 1.2.23 or newer
Download from bun.sh
Why we use it: Bun is lightning fast and handles our monorepo dependencies in a helpful and (mostly) thoughtless way.

Git (version control)

Any recent version works
Download from git-scm.com

Node.js (for compatibility)

Version: 20+
Download from nodejs.org
Note: We primarily use Bun, but some tools still expect Node.js, so it's good to have this set up.

Docker (containerization)

Download Docker Desktop
Used for: Running the full stack locally, important for replicating the production environment and testing builds before deploying.

💻 Code Editor Setup

We recommend Visual Studio Code or Cursor. If you're working as an in-house developer, be sure to request access to the organization's Cursor Pro account.

Once you have your code editor of choice, make sure to install the recommended extensions from the .vscode/extensions.json file.

📥 Getting the Code

First things first – let's get the codebase on your machine:

Important Note: If you're working as an in-house developer, you'll need to request access to the organization's GitHub account. This can be done by contacting the team lead.

You may also need to setup an SSH key on your local machine to use your GitHub account locally. This can be done by following the instructions here.

git clone git@github.com:sharingexcess/sharingexcess.git
cd sharingexcess

Our app needs an environment variable file in place to work properly. We maintain one of these files for each "environment" (staging, production and development_[github_username] per each developer). These are the files that contain the sensitive information that is not committed to the repository.

Here's how to set them up:

1️⃣ Get Your Environment Files

Ask a team member for the /environments folder contents. This will contain:

.env.development - For local development (you'll need to customize this)
.env.staging - For testing against staging
.env.production - For production (you probably won't need this)

Your own personal .env.development file will need to be updated to point to your own development database branch, as well as a few other services that are configured per developer. Talk to your team lead for more details.

Place the entire environments folder in the root of your project.

📦 Installing Dependencies

Now let's install all the packages our monorepo needs:

# Install all dependencies for all workspaces
bun install

Bun will recursively install dependencies for all of the services and shared packages in the monorepo, including:

The main client app apps/client
The server API apps/server
The docs site apps/docs (what you're reading now!)
The automated cron apps (crons/backup, crons/cleanup)
All shared packages (packages/db, packages/types)

It will also install the few "root" dependencies that are needed to run the monorepo, including (these are managed in the main package.json file).

🚦 Starting the Development Servers

Time for the magic! Let's start everything up:

# This copies .env.development to .env, and starts the development servers
bun dev

This single command starts:

Client app at http://localhost:5173 (React + Vite)
Server API at http://localhost:8080 (Hono + Bun)
Docs site at http://localhost:3000 (Next.js, also what you're reading right now!)
...and a number of other background processes, including:
- The database schema diagram generator inside (packages/db)
- The ongoing server compilation process (apps/server) to allow for type safety in the client's API requests

As a safety precaution, the dev script in the root of the repo will automatically copy the contents of .env.development file to .env (the file that the app will read from when it starts). This protects against accidentally running against production or staging data during local development.

The servers will automatically reload when you make changes to the code. Pretty neat, right?

✅ Verify Everything is Working

Let's make sure your setup is working correctly:

1️⃣ Check the Client App

Open http://localhost:5173 in your browser
You should see the Sharing Excess App homepage

2️⃣ Check the API

Open http://localhost:8080 in your browser
You should see a JSON response like {"status": "active"}

3️⃣ Check the Docs

Open http://localhost:3000 in your browser
You should see this documentation site running locally
Try navigating between pages

🐳 Alternative: Docker Setup

Want to run everything exactly like production? Use docker-compose:

# Build all the Docker images
bun build

# Start everything inside Docker containers
bun start

This runs everything exactly as it does normally, but as minified, production-ready Docker containers (as it does in production):

Client at http://localhost:5173
Server at http://localhost:8080
Docs at http://localhost:3000

🔧 Common Issues & Solutions

❌ "bun: command not found"

Make sure Bun is installed: curl -fsSL https://bun.sh/install | bash
Restart your terminal after installation
Check your PATH includes Bun: echo $PATH | grep bun

🚫 Port Already in Use

If you see "port already in use" errors:

# Find what's using the port (replace 5173 with your port)
lsof -ti:5173

# Kill the process (replace PID with the number from above)
kill -9 PID

# Or kill all Node/Bun processes
pkill -f node
pkill -f bun

🔐 Environment Variables Not Loading

Double-check the environments folder is in your project root
Verify .env file exists in project root after running bun dev
Try running bun dev again to regenerate the .env file

🗄️ Database Connection Issues

Ensure your DATABASE_URL in .env is correct

📦 Dependencies Won't Install

# Clear Bun cache and try again
# This will remove all `node_modules` and allow Bun to reinstall them from scratch
bun run clean
bun install

🎉 Next Steps

Congratulations! 🎉 You now have a fully functional local development environment. Here's what to explore next:

Monorepo Guide - Understand our project structure
Platform Overview - Learn about our architecture
Code Style - Our coding standards and tools
Services - Deep dive into each application

🆘 Getting Help

Stuck? Don't worry, we've all been there! Here's how to get help:

Ask the team - We're friendly and love helping new developers
Check existing docs - Most questions are answered somewhere in these docs
Look at the code - Our codebase is the source of truth
Create an issue - If you find gaps in documentation or bugs

Welcome to the team! We're excited to have you building the future of food rescue with us. 🌱

Sharing Excess