Getting Started

Live

---

Setting Up Your Work Environment

Before cloning, make sure these tools are installed:

Tool	Min Version	Purpose	Install
Node.js	20+	Runtime for scripts and tooling	nodejs.org
Bun	1.x+	Package manager and monorepo runner	curl -fsSL https://bun.sh/install | bash
Git	any	Version control	git-scm.com
Foundry	any	Solidity compiler and testing (forge)	curl -L https://foundry.paradigm.xyz | bash && foundryup
Docker	any	Runs the Envio indexer locally	docker.com

Foundry and Docker are only required if you work on contracts or the indexer, respectively. The setup script warns but does not block if they are missing.

---

Running Development Setup

git clone https://github.com/greenpill-dev-guild/green-goods.git
cd green-goods
bun setup   # checks deps, installs packages, creates .env
bun dev     # starts all services via PM2

What bun setup does

The setup script (scripts/setup.js) runs through four steps:

1. Dependency check -- verifies Node.js 20+, Bun 1.x, Git, Docker, and Foundry are available. Missing optional tools produce warnings, not errors.
2. Install packages -- runs bun install across all workspaces if node_modules does not exist yet.
3. Environment file -- copies .env.example to .env if no .env exists. You will need to fill in API keys for Privy (auth), Storacha (IPFS), and Envio (indexer).
4. Next steps -- prints the commands to start developing.

---

Required Secrets & Variables

Green Goods uses a single root .env file — never create package-level env files. Key variables:

Variable	Role
VITE_CHAIN_ID	Sets the target chain at build time (e.g. 11155111 for Sepolia, 42161 for Arbitrum)
VITE_PRIVY_APP_ID	Privy authentication app ID
VITE_STORACHA_KEY	Ed25519 principal key for IPFS uploads via Storacha
VITE_ENVIO_API_TOKEN	Envio indexer API token
SEPOLIA_RPC_URL	RPC endpoint for Sepolia fork tests

Copy .env.example for the full list. Variables prefixed with VITE_ are embedded into frontend bundles at build time.

Running services

All at once

bun dev launches every service through PM2:

PM2 process	Package	Default port
client	packages/client	3001
admin	packages/admin	3000
docs	docs	3003
indexer	packages/indexer (Docker)	8081
agent	packages/agent	--
storybook	packages/shared	6006

Stop everything with bun dev:stop.

Individual packages

You can also run packages directly without PM2:

bun dev:client      # Gardener PWA
bun dev:admin       # Operator dashboard
bun dev:docs        # Docusaurus site
bun dev:indexer     # Envio indexer (Docker Compose)
bun dev:contracts   # Anvil local chain
bun dev:agent       # Agent bot

First-run checklist

1. 1

   Read project rules

   Start with `AGENTS.md`, `CLAUDE.md`, and `.claude/context/*` for conventions.

2. 2

   Fill in .env

   Add your API keys. Use root `.env` only -- never add package-level env files.

3. 3

   Start services

   Run `bun dev` and verify client, admin, indexer, and docs start cleanly.

4. 4

   Run the quality gate

   Run `bun run test`, `bun lint`, and `bun build` before pushing changes.

Development workflow

The standard edit-test-build-lint cycle:

# 1. Run tests for the package you changed (always `bun run test`, never `bun test`)
cd packages/shared && bun run test

# 2. Lint the workspace
bun lint

# 3. Build (respects dependency order: contracts -> shared -> indexer -> client/admin)
bun build

# 4. Format before committing
bun format

bun test vs bun run test

bun test invokes Bun's built-in test runner, which ignores your Vitest config. Always use bun run test to run the package.json script with proper environment setup.

---

Troubleshooting & Common Issues

Symptom	Cause	Fix
forge: command not found	Foundry not installed	curl -L https://foundry.paradigm.xyz | bash && foundryup
Indexer fails to start	Docker not running	Start Docker Desktop, then retry bun dev:indexer
VITE_CHAIN_ID is undefined	Missing .env	Run bun setup or copy .env.example to .env
Port 3000/3001 in use	Another dev server running	Kill the process or change the port in the package's Vite config
bun install hangs	Stale lockfile	Delete node_modules and bun.lockb, then bun install

Non-negotiables

• All React hooks live in packages/shared -- client and admin only have components and views.
• The target chain derives from VITE_CHAIN_ID at build time. There is no runtime chain switching.
• Deployment changes go through bun deploy:* wrappers, never raw forge commands.
• User-facing strings must be added to all three translation files (en.json, es.json, pt.json).

Next best action

Keep momentum by moving to the next high-value step in this journey.

Architecture

• Build Patterns
• Operations