Skip to main content
This guide walks you through building ContextFort from source, setting up your development environment, and loading the extension locally.

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v18 or higher)
  • npm (comes with Node.js)
  • Git
  • Chrome browser (for testing the extension)

​
Clone the Repository

1

Clone from GitHub

Clone the ContextFort repository to your local machine:
git clone https://github.com/ContextFort-AI/ContextFort.git
cd ContextFort
2

Verify the structure

The repository contains two main components:
  • chrome-extension/ - Browser extension code
  • contextfort-dashboard/ - Next.js dashboard interface

​
Building the Project

The easiest way to build the entire project is using the automated build script: 
./build-all.sh
The build-all.sh script automatically:
  1. Builds the Next.js dashboard
  2. Extracts inline scripts for CSP compliance
  3. Copies dashboard assets to the extension
  4. Installs extension dependencies
  5. Builds the Chrome extension with Webpack
The built extension will be available in chrome-extension/dist/

​
Option 2: Build Components Separately

If you need to build components individually: 
cd contextfort-dashboard
npm install
npm run build
If you build components separately, you must manually copy the dashboard build output to chrome-extension/dashboard/ before building the extension.

​
Development Setup

​
Dashboard Development

For local dashboard development with hot reload:
1

Navigate to dashboard directory

cd contextfort-dashboard
2

Install dependencies

npm install
3

Set up environment variables

Copy the example environment file and configure:
cp .env.example .env
Edit .env with your local settings:
# For local development
NEXT_PUBLIC_POST_MONITOR_API=http://localhost:8000
NEXT_PUBLIC_CLICK_DETECTION_API=http://localhost:8000

# Refresh intervals (milliseconds)
NEXT_PUBLIC_REFRESH_INTERVAL_POST=5000
NEXT_PUBLIC_REFRESH_INTERVAL_CLICK=1000
4

Start development server

npm run dev
The dashboard will be available at http://localhost:3000

​
Extension Development

For Chrome extension development:
1

Navigate to extension directory

cd chrome-extension
2

Install dependencies

npm install
3

Configure environment (optional)

Create a .env file for PostHog analytics and API settings:
POSTHOG_KEY=your_posthog_key
API_URL=http://localhost:8000
4

Run in watch mode

npm run watch
This watches for file changes and automatically rebuilds.

​
Loading the Extension in Chrome

Once you’ve built the extension, load it into Chrome for testing:
1

Open Chrome Extensions

Navigate to chrome://extensions/ in your Chrome browser
2

Enable Developer Mode

Toggle the Developer mode switch in the top-right corner
3

Load the extension

Click Load unpacked and select the chrome-extension/dist/ directory
4

Verify installation

The ContextFort icon should appear in your Chrome toolbar. Click it to access the dashboard.
If you’re running in watch mode (npm run watch), the extension will automatically rebuild when you make changes. You’ll need to click the refresh icon on the extension card in chrome://extensions/ to reload it.

​
Project Structure

ContextFort/
├── build-all.sh                    # Automated build script
├── chrome-extension/
│   ├── background.js              # Service worker
│   ├── content.js                 # Content script
│   ├── popup.js                   # Popup UI logic
│   ├── manifest.json              # Extension manifest
│   ├── webpack.config.js          # Webpack configuration
│   ├── package.json               # Extension dependencies
│   └── dist/                      # Build output (generated)
└── contextfort-dashboard/
    ├── src/
    │   ├── app/                   # Next.js routes
    │   ├── components/            # React components
    │   ├── hooks/                 # Custom hooks
    │   ├── lib/                   # Utilities
    │   └── styles/                # Tailwind config
    ├── extract-inline-scripts.js  # CSP compliance script
    └── package.json               # Dashboard dependencies

​
Build Scripts Explained

​
Dashboard Scripts

  • npm run dev - Start development server with hot reload
  • npm run build - Create production build with Next.js
  • npm run lint - Run Biome linter
  • npm run format - Format code with Biome
  • npm run check - Run linting and formatting checks
  • npm run check:fix - Auto-fix linting and formatting issues

​
Extension Scripts

  • npm run build - Build extension with Webpack (production mode)
  • npm run watch - Watch mode for development with auto-rebuild

​
Troubleshooting

​
Build Failures

If the build script fails, check:
  • Node.js version (must be v18+)
  • All dependencies are installed (npm install)
  • No other processes are using port 3000 (for dashboard dev)

​
Extension Not Loading

If the extension doesn’t load in Chrome:
  1. Verify the build completed successfully
  2. Check that chrome-extension/dist/ contains all required files
  3. Look for errors in chrome://extensions/ (enable Developer mode)
  4. Check the Chrome DevTools console for runtime errors

​
Dashboard Build Issues

If the dashboard fails to build: 
# Clear Next.js cache
cd contextfort-dashboard
rm -rf .next
npm run build

​
Missing Dependencies

If you encounter module not found errors: 
# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

​
Next Steps

Contributing

Learn how to contribute to ContextFort

Architecture

Understand the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us