Base is a secure, low-cost, developer-friendly Ethereum L2 built to bring the next billion users onchain. It's built on Optimism's open-source OP Stack.

1. Ensure that nvm is installed.
2. Clone the repository.
3. If nvm doesn't auto-load the Node.js environment when changing to the repo directory, run nvm use.
4. Enable Yarn by running corepack enable.

After cloning the repository begin by installing dependencies at the root.

yarn
yarn build

To start a development server on localhost, run yarn workspace @app/<project> dev.

For example, to start the web app locally, you would run yarn workspace @app/web dev.

There are three projects which can be run individually.

yarn workspace @app/web dev

We welcome contributions to Base! For guidelines on how to contribute please refer to CONTRIBUTING.md.

If you're a builder who wants to add or update your project on the Base Ecosystem page, follow these steps:

1. Fork this repository.

2. Create a new branch for your changes.

3. Update the ecosystem.json file in apps/web/src/data/ with your project's details :

   {
     "name": "Your Project Name",
     "description": "A brief description (less than 200 characters)",
     "url": "https://your-project.com",
     "imageUrl": "/images/partners/your-logo.png",
     "category": "one of: ai, consumer, defi, infra, onramp, wallet",
     "subcategory": "see categories below"
   }

   • name: Your project's name
   • description: A brief description of your project, must be less than 200 characters
   • url: Your project's website URL
   • imageUrl: Path to your project's logo image
   • category: Your project's category, one of: ai, consumer, defi, infra, onramp, wallet
   • subcategory: Your project's subcategory, with the following options associated with each category
     • ai: Simply add ai as the subcategory as well
     • consumer: One of creator, crypto taxes, dao, gaming, messaging, music, nft, payments, real world, social
     • defi: One of dex, dex aggregator, insurance, lending/borrowing, liquidity management, portfolio, stablecoin, yield vault
     • infra: One of bridge, data, depin, developer tool, identity, node provider, raas, security
     • onramp: One of centralized exchange, fiat on-ramp
     • wallet: One of account abstraction, multisig, self-custody

If your app supports multiple networks, ensure the URL provided points to a page with Base already selected as the network, for people who will be visiting from base.org.

4. Add your project's logo:

   • Place a 192x192 pixel PNG/WebP file in apps/web/public/images/partners/
   • Name should match what you specified in imageUrl
   • Use an App/Play Store style icon (not a full wordmark)

5. Check if your project has been listed by running it locally:

yarn workspace @app/web dev

6. Make sure the build works properly before creating the PR:

yarn workspace @app/web build

By opening a PR to add your project, you authorize and license Coinbase on a non-exclusive, worldwide, irrevocable, sublicensable, and royalty-free basis to reproduce, distribute, transmit, make available, perform, display, or otherwise use the submitted Multimedia Assets for any purpose, including any marketing or promotional activities related to Base or Coinbase. Any goodwill associated with use of trademarks submitted in your Multimedia Assets will inure to your benefit. You further acknowledge and represent that you have all IP rights in the Multimedia Assets, that the Multimedia Assets do not infringe the rights of any third party, and that you have the right to grant this license to Coinbase.

Note: Submissions do not guarantee inclusion and all submissions are subject to review. Your project must be live on Base to potentially be included. Ensure all information is accurate and up-to-date.

• App content adheres to the Base Editorial Style Guide
• App has been live on Base for at least 30 days
• App has a Terms of Service and Privacy Policy
• App supports HTTPS and 301 redirects HTTP requests
• App is not a TGE (Token Generation Event), ICO (Initial Coin Offering), airdrop, claim, or similar
• Landing page is a Base-specific page for users who will be coming from base.org
• Active development and community engagement can be observed without issue

• Node.js >= 20
• Yarn >= 1.22

git clone https://github.com/base/web.git
cd web
yarn install
yarn dev

This monorepo contains multiple applications and libraries:

• apps/web - Main Base website application built with Next.js 15
• apps/bridge - Base bridge application
• libs/base-ui - Shared UI component library

• Framework: Next.js 15 with App Router
• Language: TypeScript 5.0+
• Styling: Tailwind CSS with custom design system
• Blockchain: Wagmi v2 + Viem for Ethereum interactions
• 3D Graphics: Three.js with React Three Fiber
• Animation: Framer Motion
• Testing: Jest + Playwright for E2E
• Deployment: Vercel with custom Docker configuration

1. Install Node.js 20+ using nvm:

   nvm install 20
   nvm use 20

2. Enable Yarn package manager:

   corepack enable

3. Install dependencies:

   yarn install

# Start the main web application
yarn workspace @app/web dev

# Build the entire project
yarn build

# Run tests
yarn test

# Run E2E tests
yarn test:e2e

# Run E2E tests with UI
yarn test:e2e:ui

yarn test

# Run all E2E tests
yarn test:e2e

# Run with browser UI
yarn test:e2e:ui

# Debug mode
yarn test:e2e:debug

# Run in headed mode
yarn test:e2e:headed

• Unit Tests: Jest with React Testing Library
• E2E Tests: Playwright with custom wallet configurations
• Test Coverage: Configured for comprehensive coverage reporting

yarn build
yarn workspace @app/web start

Required environment variables for production:

# Database
DATABASE_URL=postgresql://...

# Redis
REDIS_URL=redis://...

# External APIs
CLOUDINARY_URL=cloudinary://...

# Analytics
DATADOG_CLIENT_TOKEN=...
BUGSNAG_API_KEY=...

# Build Docker image
docker build -t base-web .

# Run container
docker run -p 3000:3000 base-web

Node.js Version Issues

# Ensure you're using Node.js 20+
nvm use 20

Yarn Installation Issues

# Clear yarn cache
yarn cache clean

# Reinstall dependencies
rm -rf node_modules yarn.lock
yarn install

Build Failures

# Clear Next.js cache
rm -rf .next

# Rebuild
yarn build

E2E Test Issues

# Install Playwright browsers
npx playwright install

# Run tests in debug mode
yarn test:e2e:debug

• Bundle Analysis: Run yarn workspace @app/web analyze to analyze bundle size
• Million.js: Use yarn workspace @app/web dev:million for performance monitoring
• Image Optimization: All images are automatically optimized with Next.js Image component

web/
├── apps/
│   ├── web/                 # Main website application
│   │   ├── app/            # Next.js 15 App Router
│   │   ├── src/            # Source code
│   │   ├── public/         # Static assets
│   │   └── e2e/            # End-to-end tests
│   └── bridge/             # Bridge application
├── libs/
│   └── base-ui/            # Shared UI components
├── tools/                  # Build tools and CI
└── docs/                   # Documentation

If you have any questions, please reach out to us in #developer-chat in the Base Discord.