DEV_ENVIRONMENT.md

Development Environment

This guide explains how to configure a local development environment for contributing to the CeloHT ecosystem.

---

Overview

A consistent development environment helps ensure that every contributor can build, test, and maintain the project efficiently.

---

Minimum Requirements

• Git 2.40+
• Node.js 20 LTS or newer
• npm 10+ or pnpm
• Visual Studio Code (recommended)

---

Recommended Operating Systems

• Ubuntu 24.04 LTS or newer
• macOS (latest stable)
• Windows 11 with WSL2

---

Recommended VS Code Extensions

Install the following extensions:

• ESLint
• Prettier
• GitHub Pull Requests
• GitLens
• Tailwind CSS IntelliSense
• Solidity
• Error Lens
• Markdown All in One
• EditorConfig

---

Clone the Repository

git clone https://github.com/Celo-HT/CeloHT.git

cd CeloHT

---

Install Dependencies

Using npm

npm install

Using pnpm

pnpm install

---

Configure Environment Variables

Create:

.env.local

Example:

NEXT_PUBLIC_NETWORK=alfajores

NEXT_PUBLIC_RPC_URL=https://alfajores-forno.celo-testnet.org

NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=YOUR_PROJECT_ID

Never commit .env files.

---

Run Development Server

npm run dev

Open:

http://localhost:3000

---

Linting

Run ESLint:

npm run lint

Automatically fix issues:

npm run lint -- --fix

---

Formatting

Format the project:

npm run format

CeloHT uses Prettier to maintain a consistent code style.

---

Type Checking

npm run typecheck

Every Pull Request should pass TypeScript validation.

---

Testing

Run all tests:

npm test

Run coverage:

npm run coverage

---

Smart Contracts

Compile contracts:

npx hardhat compile

Run contract tests:

npx hardhat test

---

Git Workflow

Create a feature branch:

git checkout -b feature/my-feature

Examples:

feature/education-dashboard

fix/mobile-menu

docs/api-reference

---

Commit Messages

Follow Conventional Commits.

Examples:

feat: add education dashboard

fix: resolve wallet connection issue

docs: improve API reference

refactor: simplify agent service

---

Before Opening a Pull Request

Verify:

• Documentation updated
• Lint passes
• Tests pass
• Build succeeds
• No merge conflicts

---

Useful Commands

Install dependencies

npm install

Run development server

npm run dev

Build

npm run build

Run tests

npm test

Lint

npm run lint

Type checking

npm run typecheck

Compile contracts

npx hardhat compile

---

Debugging

If something goes wrong:

• Check the terminal output.
• Verify environment variables.
• Update dependencies.
• Ensure Node.js is supported.
• Review GitHub Issues.

---

Best Practices

• Keep branches small.
• Write descriptive commits.
• Document new features.
• Never commit secrets.
• Keep dependencies updated.
• Review code before submitting.

---

Future Improvements

Planned improvements include:

• Development Docker environment
• Dev Containers (VS Code)
• Nix development environment
• GitHub Codespaces support
• Automated local setup script
• One-command project bootstrap

---

Conclusion

A well-configured development environment enables contributors to build, test, and improve CeloHT efficiently while maintaining the project's standards for quality, security, and collaboration.