🚀 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.3.0 or newer
Install with: curl -fsSL https://bun.com/install | bash
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
Git is likely already installed by default on your system
If not installed, we recommend using Homebrew: brew install git

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

📦 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).

🔧 Environment Setup

Environment variables are automatically supplied by the Railway CLI session. You no longer need to manage .env files locally!

Before running the development servers, you'll need to authenticate with Railway from your terminal. Railway is our platform for deploying and managing our services, and it also provides a CLI to run our services locally using environment variables from the Railway platform.

You can login to Railway by running the following command:

bun railway login

This will open your browser to authenticate with Railway. Once logged in, the Railway CLI will automatically provide all necessary environment variables when you run bun dev.

Once you're logged in, you'll want to connect the sharingexcess Railway project to your local directory.

bun railway link

> Select a workspace: Sharing Excess
> Select a project: sharingexcess
> Select an environment: <your development environment name>
? Select a service <esc to skip>: <esc>

Project sharingexcess linked successfully! 🎉

Note: Because of our monorepo structure, you don't need to select any services to link to the root directory. We'll configure the services later.

2️⃣ Configure Development Services (First Time Only)

The next step will be to start the local servers using bun dev, but you'll likely be prompted to configure your development scripts for each service (if you're not prompted by default, you can do this manually by running bun railway dev configure). You'll need to configure the following services:

client - The React frontend application
server - The Hono API backend
storage - The S3 file host proxy
docs - The documentation site

For each service, use these values:

Dev command: bun run --filter='@sharingexcess/<service-name>' dev
Directory: apps/<service-name>

For example, here are some example logs from configuring client:

bun railway dev configure

> Select service to configure: client

Configure 'client'
> Dev command for 'client': bun run --filter='@sharingexcess/client' dev
> Directory for 'client' (relative to current directory): apps/client
✓ Configured 'client'

Repeat this process for server, storage, and docs as needed. After the initial configuration, Railway will remember these settings for future runs.

🚦 Starting the Development Servers

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

# Starts all development servers with environment variables from Railway CLI
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

The dev script uses bun railway dev, which automatically provides all environment variables from your Railway CLI session. This ensures you're always using the correct environment configuration without needing to manage .env files locally.

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

🔧 Common Issues & Solutions

❌ "bun: command not found"

Make sure Bun is installed: curl -fsSL https://bun.com/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

Ensure you've logged in to Railway CLI: bun railway login
Verify your Railway CLI session is active: bun railway whoami
Try logging out and back in: bun railway logout then bun railway login

🗄️ Database Connection Issues

Ensure your Railway CLI session has access to the correct environment
Verify your Railway project is configured correctly

📦 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