Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Node.js

Version 18 or higher required

npm

Comes with Node.js installation

PostgreSQL

Required for local database

Git

For version control

​
Verify Prerequisites

Run these commands to verify your installations: 
node --version  # Should be v18.0.0 or higher
npm --version   # Should be 8.0.0 or higher
psql --version  # PostgreSQL version

​
Initial Project Setup

1

Clone the repository

Clone the Agora repository to your local machine:
git clone <repository-url>
cd agora-next
2

Install dependencies

Install all required npm packages:
npm install
This will install all dependencies listed in package.json, including:
  • Next.js 14.2.35 - React framework
  • Prisma 5.22.0 - Database ORM
  • TypeScript 5.4.5 - Type safety
  • Tailwind CSS 3.3.2 - Styling
  • ethers.js 6.16.0 - Ethereum library
  • wagmi 2.13.0 - React hooks for Ethereum
3

Set up environment variables

Create a .env.local file in the project root. Contact your team on Discord to get the complete environment configuration.
Never commit .env.local or .env files to version control. These files contain sensitive credentials.
See the Configuration Guide for detailed environment variable documentation.

​
Database Setup with Prisma

1

Configure database connection

Set your database URL in .env.local:
# Option 1: Use environment-specific URLs
READ_WRITE_WEB2_DATABASE_URL_DEV=postgres://user:password@localhost:5432/agora_web2
READ_ONLY_WEB3_DATABASE_URL_DEV=postgres://user:password@localhost:5432/agora_web3

# Option 2: Use a single database URL
DATABASE_URL=postgres://user:password@localhost:5432/agora
Agora uses a dual-database architecture:
  • READ_WRITE_WEB2_DATABASE_URL - User-generated content (profiles, settings)
  • READ_ONLY_WEB3_DATABASE_URL - Blockchain indexed data (proposals, votes, delegates)
2

Pull the latest schema

The database schema is managed in a separate repository. Pull the latest schema:
npx prisma db pull
This command introspects your database and updates the Prisma schema file at prisma/schema.prisma.
3

Generate Prisma Client

Generate the TypeScript Prisma Client:
npx prisma generate
This creates type-safe database access methods based on your schema.
4

Verify database access

You can explore your database using a SQL client:

TablePlus

Recommended by the team

pgAdmin

Free PostgreSQL tool
The database has the following schemas:
  • center - Admin-only access
  • config - Shared configuration data
  • agora - Shared data (customer info, aggregations)
  • [dao namespace] - DAO-specific schemas (optimism, ens, uniswap, etc.)

​
Development Environment Setup

1

Generate TypeChain contracts

Generate TypeScript typings for smart contracts:
npm run generate-typechain
This creates type-safe contract interfaces in src/lib/contracts/generated/.
2

Start the development server

Launch the Next.js development server:
npm run dev
The application will be available at http://localhost:3000
3

Verify the setup

Open your browser and navigate to http://localhost:3000. You should see the Agora interface.
If you see the homepage loading successfully, your setup is complete!

​
Development Tools

​
Code Quality Commands

Before committing code, always run: 
# Format code with Prettier
npm run prettier-src

# Check code formatting
npm run check-prettier

# Run linting
npm run lint

# Type checking
npm run typecheck

# Run tests
npm test
Always run npm run prettier-src, npm run lint, and npm run typecheck before committing to ensure code quality.

​
Additional Utilities

# Build for production
npm run build

# Analyze bundle size
npm run analyze

# Generate API key (for Agora staff)
npm run generate-apikey -- --email [email protected] --address 0x123... --chain-id 1

# Generate JWT token
npm run generate-jwt

​
Database Management

​
Keeping Schema Updated

The database schema is managed externally. To sync your local schema: 
# Pull latest schema from database
npx prisma db pull

# Regenerate Prisma Client
npx prisma generate
Learn more in the Database Manual

​
Troubleshooting

Verify your database is running and credentials are correct:
psql -h localhost -U your_username -d agora
Check that your DATABASE_URL in .env.local matches your database configuration.
This usually means the database schema is out of sync:
npx prisma db pull
npx prisma generate
Ensure you have all required variables in .env.local:
  • NEXT_PUBLIC_AGORA_INSTANCE_NAME
  • NEXT_PUBLIC_AGORA_INSTANCE_TOKEN
  • NEXT_PUBLIC_AGORA_ENV
  • NEXT_PUBLIC_ALCHEMY_ID
  • NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID
See the Configuration Guide for the complete list.
Either stop the other process or use a different port:
PORT=3001 npm run dev

​
Next Steps

Configuration

Learn about environment variables and configuration options

Deployment

Deploy your Agora instance to production

Customization

Customize themes, branding, and features

Architecture

Understand the application structure

Build docs developers (and LLMs) love

Get started for freeTalk to us