Your First Contribution

A step-by-step walkthrough for new contributors to get the BlueCollar monorepo running locally and make their first contribution.

Prerequisites
Local Development Setup
Your First Contribution Walkthrough
Common Troubleshooting
Good First Issues

Prerequisites

Install these tools before you start:

Tool	Version	Install
Node.js	>= 20	nodejs.org
pnpm	>= 9	`npm i -g pnpm`
PostgreSQL	>= 14	postgresql.org or Docker
Git	any	git-scm.com
Rust	stable	`curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh`
Docker (optional)	any	docker.com

Verify your setup:

node --version    # v20.x.x or higher
pnpm --version    # 9.x.x or higher
psql --version    # psql (PostgreSQL) 14.x or higher
git --version     # git version 2.x.x
rustc --version   # rustc 1.x.x (stable)

Local Development Setup

1. Fork and clone

Fork the repository on GitHub, then clone your fork:

git clone https://github.com/<your-username>/Blue-Collar.git
cd Blue-Collar

Add the upstream remote so you can pull future changes:

git remote add upstream https://github.com/abore9769/Blue-Collar.git

2. Install dependencies

From the repo root, install all workspace dependencies at once:

pnpm install

This installs dependencies for all three packages (api, app, contracts) in one step.

API (`packages/api`)

The backend REST API — Node.js, Express, TypeScript, Prisma, PostgreSQL.

Step 1 — Set up environment variables

cp packages/api/.env.example packages/api/.env

Open packages/api/.env and fill in the required values:

Variable	Required	Example
`DATABASE_URL`	Yes	`postgresql://user:pass@localhost:5432/bluecollar`
`TEST_DATABASE_URL`	Yes (for tests)	`postgresql://user:pass@localhost:5432/bluecollar_test`
`JWT_SECRET`	Yes	`openssl rand -hex 32` output
`PORT`	No	`3000`
`NODE_ENV`	No	`development`
`APP_URL`	No	`http://localhost:3001`
`ALLOWED_ORIGINS`	No	`http://localhost:3001`
`GOOGLE_CLIENT_ID`	No	From Google Cloud Console
`GOOGLE_CLIENT_SECRET`	No	From Google Cloud Console
`MAIL_HOST`	No	`smtp.example.com`
`MAIL_PORT`	No	`587`
`MAIL_USER`	No	`no-reply@example.com`
`MAIL_PASS`	No	Your SMTP password
`VAPID_PUBLIC_KEY`	No	Generate with `npx web-push generate-vapid-keys`
`VAPID_PRIVATE_KEY`	No	Generate with `npx web-push generate-vapid-keys`

For local development, only DATABASE_URL, JWT_SECRET, and PORT are strictly required. Google OAuth and email features will be unavailable without their respective variables.

Step 2 — Create the database

createdb bluecollar
createdb bluecollar_test   # for running tests

Or with Docker (no local PostgreSQL needed):

pnpm docker:up   # starts PostgreSQL + API + Adminer at localhost:8080

Step 3 — Run migrations

cd packages/api
pnpm migrate

This runs prisma migrate dev and applies all schema migrations.

Step 4 — Seed the database

pnpm seed

Populates the database with default job categories.

Step 5 — Start the dev server

pnpm dev

The API is now available at http://localhost:3000/api.

Verify it's running:

curl http://localhost:3000/health
# {"status":"ok","service":"bluecollar-api"}

Optional — Create an admin user

pnpm admin:create --email admin@example.com --password secret123 --firstName Jane --lastName Doe

Useful API scripts

Script	Description
`pnpm dev`	Start dev server with hot reload
`pnpm build`	Compile TypeScript to `dist/`
`pnpm test`	Run tests with Vitest (watch mode)
`pnpm test -- --run`	Run tests once (no watch)
`pnpm test:coverage`	Run tests with coverage report
`pnpm migrate`	Run Prisma migrations
`pnpm seed`	Seed default categories
`pnpm admin:create`	Create an admin user via CLI
`pnpm db:reset`	Reset the database (dev only)
`pnpm lint`	Run ESLint
`pnpm format`	Format with Prettier

App (`packages/app`)

The Next.js 14 frontend — React, Tailwind CSS, next-intl, Stellar SDK.

Step 1 — Set up environment variables

cp packages/app/.env.example packages/app/.env

Open packages/app/.env and fill in:

Variable	Required	Example
`NEXT_PUBLIC_API_URL`	Yes	`http://localhost:3000/api`
`NEXT_PUBLIC_STELLAR_NETWORK`	No	`TESTNET`
`NEXT_PUBLIC_MARKET_CONTRACT_ID`	No	Deployed contract ID
`NEXT_PUBLIC_REGISTRY_CONTRACT_ID`	No	Deployed contract ID
`NEXT_PUBLIC_VAPID_PUBLIC_KEY`	No	Must match API's `VAPID_PUBLIC_KEY`

For local development, only NEXT_PUBLIC_API_URL is required.

Step 2 — Start the dev server

cd packages/app
pnpm dev

The app is available at http://localhost:3001.

Useful App scripts

Script	Description
`pnpm dev`	Start Next.js dev server
`pnpm build`	Production build
`pnpm test`	Run component tests with Vitest
`pnpm lint`	Run ESLint
`pnpm type-check`	TypeScript type check (no emit)

Contracts (`packages/contracts`)

Stellar Soroban smart contracts written in Rust.

Step 1 — Install Rust toolchain

rustup target add wasm32-unknown-unknown
cargo install --locked stellar-cli --features opt

Verify:

rustc --version
stellar --version

Step 2 — Build contracts

cd packages/contracts
make build
# or: cargo build --release --target wasm32-unknown-unknown

Output WASMs:

target/wasm32-unknown-unknown/release/bluecollar_registry.wasm
target/wasm32-unknown-unknown/release/bluecollar_market.wasm

Step 3 — Run contract tests

make test
# or: cargo test

Run a single contract's tests:

cargo test -p bluecollar-registry
cargo test -p bluecollar-market

Useful contract scripts

Command	Description
`make build`	Build all contracts to WASM
`make test`	Run all contract tests
`make clippy`	Lint with Clippy (zero warnings)
`make fmt`	Format with `cargo fmt`

Your First Contribution Walkthrough

Here's the full flow from picking an issue to opening a PR.

Step 1 — Pick an issue

Browse good first issues on GitHub. Leave a comment saying you'd like to work on it so maintainers can assign it to you.

Step 2 — Sync with upstream

Before starting, make sure your main is up to date:

git checkout main
git fetch upstream
git merge upstream/main

Step 3 — Create a feature branch

Follow the branch naming convention <type>/<short-description>:

git checkout -b fix/worker-toggle-auth
# or
git checkout -b feat/add-worker-search
# or
git checkout -b docs/update-api-readme

Step 4 — Make your changes

Write your code. Keep commits small and focused. Follow the Conventional Commits format:

git commit -m "fix(api): return 403 instead of 401 on missing role"
git commit -m "feat(app): add search bar to workers page"
git commit -m "docs(api): document rate limiting headers"

Step 5 — Run checks locally

Before pushing, make sure everything passes:

# API
cd packages/api
pnpm test -- --run
pnpm build

# App
cd packages/app
pnpm lint
pnpm type-check

# Contracts (if you changed Rust code)
cd packages/contracts
make clippy
make test

Step 6 — Push and open a PR

git push origin fix/worker-toggle-auth

Then open a pull request on GitHub against the main branch. A PR template will pre-fill — it includes a checklist covering the type of change you made. Use the appropriate issue template when opening issues:

Issue Type	Template
Bug Report	`.github/ISSUE_TEMPLATE/bug_report.yml`
Feature Request	`.github/ISSUE_TEMPLATE/feature_request.yml`
Documentation	`.github/ISSUE_TEMPLATE/documentation.yml`

PR template (.github/pull_request_template.md):

## Summary

Brief description of what this PR does and why.

## Related Issue

Closes #

## Type of Change

- [ ] feat — New feature
- [ ] fix — Bug fix
- [ ] docs — Documentation
...

## Checklist

- [ ] Linter passes (`pnpm lint`)
- [ ] Tests pass (`pnpm test -- --run`)
- [ ] PR title follows Conventional Commits
...

Common Troubleshooting

PostgreSQL connection error (`P1001: Can't reach database server`)

Ensure PostgreSQL is running: pg_isready or sudo service postgresql start
Double-check DATABASE_URL in packages/api/.env — username, password, host, port, and database name must all match
Make sure the database exists: createdb bluecollar

`prisma migrate dev` fails with "database does not exist"

createdb bluecollar

Missing environment variable errors on startup

Confirm packages/api/.env exists: ls packages/api/.env
Ensure you copied from the example: cp packages/api/.env.example packages/api/.env
Check that JWT_SECRET, DATABASE_URL, and PORT are set and non-empty

`pnpm: command not found`

npm i -g pnpm

Port 3000 already in use

# Find and kill the process
lsof -ti:3000 | xargs kill
# Or use a different port
PORT=3001 pnpm dev

`cargo: command not found`

Install Rust:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

`wasm32-unknown-unknown` target missing

rustup target add wasm32-unknown-unknown

`stellar: command not found`

cargo install --locked stellar-cli --features opt

Next.js build fails with type errors

cd packages/app
pnpm type-check   # see all type errors

Fix the reported errors before pushing — CI will fail on type errors.

Tests fail with "Cannot find module"

Make sure you ran pnpm install from the repo root, not from inside a package directory:

cd Blue-Collar   # repo root
pnpm install

Good First Issues

Look for issues tagged good first issue on GitHub. These are scoped to be approachable for new contributors and have enough context to get started without deep knowledge of the codebase.

If you're unsure where to start, these areas are always good for contributions:

Documentation — improving READMEs, adding code comments, fixing typos
Tests — adding test coverage for untested services or controllers
Validation — strengthening input validation rules
UI components — building or improving frontend components in packages/app/src/components/

Feel free to open a GitHub Discussion if you have questions before diving in.

FilesExpand file tree

CONTRIBUTING_GUIDE.md

Latest commit

History

CONTRIBUTING_GUIDE.md

File metadata and controls

Your First Contribution

Table of Contents

Prerequisites

Local Development Setup

1. Fork and clone

2. Install dependencies

API (packages/api)

Step 1 — Set up environment variables

Step 2 — Create the database

Step 3 — Run migrations

Step 4 — Seed the database

Step 5 — Start the dev server

Optional — Create an admin user

Useful API scripts

App (packages/app)

Step 1 — Set up environment variables

Step 2 — Start the dev server

Useful App scripts

Contracts (packages/contracts)

Step 1 — Install Rust toolchain

Step 2 — Build contracts

Step 3 — Run contract tests

Useful contract scripts

Your First Contribution Walkthrough

Step 1 — Pick an issue

Step 2 — Sync with upstream

Step 3 — Create a feature branch

Step 4 — Make your changes

Step 5 — Run checks locally

Step 6 — Push and open a PR

Common Troubleshooting

PostgreSQL connection error (P1001: Can't reach database server)

prisma migrate dev fails with "database does not exist"

Missing environment variable errors on startup

pnpm: command not found

Port 3000 already in use

cargo: command not found

wasm32-unknown-unknown target missing

stellar: command not found

Next.js build fails with type errors

Tests fail with "Cannot find module"

Good First Issues

API (`packages/api`)

App (`packages/app`)

Contracts (`packages/contracts`)

PostgreSQL connection error (`P1001: Can't reach database server`)

`prisma migrate dev` fails with "database does not exist"

`pnpm: command not found`

`cargo: command not found`

`wasm32-unknown-unknown` target missing

`stellar: command not found`