Building from Source

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

Clone from GitHub

Clone the ContextFort repository to your local machine:

git clone https://github.com/ContextFort-AI/ContextFort.git
cd ContextFort

Verify the structure

The repository contains two main components:

chrome-extension/ - Browser extension code
contextfort-dashboard/ - Next.js dashboard interface

Building the Project

Option 1: Build Everything (Recommended)

The easiest way to build the entire project is using the automated build script:

./build-all.sh

The build-all.sh script automatically:

Builds the Next.js dashboard
Extracts inline scripts for CSP compliance
Copies dashboard assets to the extension
Installs extension dependencies
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

cd chrome-extension
npm install
npm run build

cd chrome-extension
npm run watch

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:

Navigate to dashboard directory

cd contextfort-dashboard

Install dependencies

npm install

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

Start development server

npm run dev

The dashboard will be available at http://localhost:3000

Extension Development

For Chrome extension development:

Navigate to extension directory

cd chrome-extension

Install dependencies

npm install

Configure environment (optional)

Create a .env file for PostHog analytics and API settings:

POSTHOG_KEY=your_posthog_key
API_URL=http://localhost:8000

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:

Open Chrome Extensions

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

Enable Developer Mode

Toggle the Developer mode switch in the top-right corner

Load the extension

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

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:

Verify the build completed successfully
Check that chrome-extension/dist/ contains all required files
Look for errors in chrome://extensions/ (enable Developer mode)
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

Resources

Development

Prerequisites

Clone the Repository

Building the Project

Option 1: Build Everything (Recommended)

Option 2: Build Components Separately

Development Setup

Dashboard Development

Extension Development

Loading the Extension in Chrome

Project Structure

Build Scripts Explained

Dashboard Scripts

Extension Scripts

Troubleshooting

Build Failures

Extension Not Loading

Dashboard Build Issues

Missing Dependencies

Next Steps

Contributing

Architecture

​Prerequisites

​Clone the Repository

​Building the Project

​Option 1: Build Everything (Recommended)

​Option 2: Build Components Separately

​Development Setup

​Dashboard Development

​Extension Development

​Loading the Extension in Chrome

​Project Structure

​Build Scripts Explained

​Dashboard Scripts

​Extension Scripts

​Troubleshooting

​Build Failures

​Extension Not Loading

​Dashboard Build Issues

​Missing Dependencies

​Next Steps

Contributing

Architecture

Prerequisites

Clone the Repository

Building the Project

Option 1: Build Everything (Recommended)

Option 2: Build Components Separately

Development Setup

Dashboard Development

Extension Development

Loading the Extension in Chrome

Project Structure

Build Scripts Explained

Dashboard Scripts

Extension Scripts

Troubleshooting

Build Failures

Extension Not Loading

Dashboard Build Issues

Missing Dependencies

Next Steps