ToggleBox

Open source remote configuration, feature flags, and experimentation platform.

Self-host it anywhere or use our hosted version for a fully managed experience.

Visual Overview

Core Features

Remote Configs

Update your app's settings without redeploying. Change themes, API endpoints, copy, or any JSON configuration instantly.

Feature Flags

Ship code when you're ready, release when you want. Control who sees what with targeting rules and percentage rollouts.

Experiments

Run A/B tests to make decisions with data. Split traffic between variants and track which performs better.

Analytics

Track flag evaluations, experiment exposures, and configuration fetches. Know what's happening in your apps.

Why ToggleBox?

Feature	ToggleBox
Self-Hostable	Deploy on your infrastructure with full control
Multi-Database	DynamoDB, PostgreSQL, MySQL, MongoDB, SQLite, Cloudflare D1
Multi-Platform	AWS Lambda, Cloudflare Workers, Docker, Netlify
Type-Safe SDKs	JavaScript, Next.js, Expo/React Native, PHP, Laravel
Open Source	Inspect the code, contribute, customize
Hosted Option	ToggleBox Cloud for zero maintenance

Quick Start

Prerequisites

Node.js 18+
pnpm 8.x (npm install -g pnpm)

Installation

# Clone the repository
git clone https://github.com/ulpi-io/togglebox.git
cd togglebox

# Install dependencies
pnpm install

# Build packages
pnpm build:packages

# Configure environment
cp apps/api/.env.example apps/api/.env

# Start the API
pnpm dev:api

# Start the admin dashboard (in another terminal)
pnpm dev:admin

The API runs at http://localhost:3000 and the admin dashboard at http://localhost:3001.

Docker Development (Alternative)

For a containerized development environment with hot reload:

# Start development environment
make dev

# View all services
make status

# View logs
make logs          # All services
make logs-api      # API only
make logs-admin    # Admin only

# Stop services
make down

# Rebuild from scratch
make rebuild

Available Make Commands:

Command	Description
`make dev`	Start development environment with hot reload
`make prod`	Start production environment
`make down`	Stop all services
`make restart`	Restart all services
`make build`	Rebuild containers (no cache)
`make rebuild`	Clean volumes and rebuild from scratch
`make logs`	View logs for all services
`make logs-api`	View API logs only
`make logs-admin`	View Admin logs only
`make status`	Show service status and access points
`make shell-api`	Open shell in API container
`make shell-admin`	Open shell in Admin container
`make test`	Run tests in API container
`make help`	Show all available commands

Access Points (Docker):

Seed Demo Data

To populate the database with demo data for all example apps:

# Run the seed script (no API required - seeds directly to database)
pnpm seed

The seed script creates:

Resource	Description
Demo Admin User	`admin@togglebox.com` / `Parola123!`
API Key	Full permissions for authenticated requests
Platforms	`web`, `mobile`, `ecommerce`
Environments	`staging` (web/mobile), `development` (ecommerce)
Config Parameters	`theme`, `apiTimeout` per platform
Feature Flags	`dark-mode`, `new-checkout-flow`, `beta-features`, `biometric-auth`
Experiments	`checkout-test`, `cta-test`, `checkout-button-test`, `pricing-display-test`

All experiments are automatically started and in "running" status.

SDKs

ToggleBox provides official SDKs for multiple platforms:

SDK	Package	Description
JavaScript		Core JavaScript SDK for browser and Node.js
Next.js		Next.js SDK with React hooks and SSR support
Expo		React Native/Expo SDK with offline support
PHP		Core PHP SDK (PHP 8.1+)
Laravel		Laravel SDK with service provider and facade

JavaScript SDK

npm install @togglebox/sdk

import { ToggleBoxClient } from "@togglebox/sdk";

const client = new ToggleBoxClient({
  platform: "web",
  environment: "production",
  apiUrl: "https://your-togglebox-api.com",
});

// Remote config (Tier 1)
const config = await client.getConfig();
const theme = await client.getConfigValue("theme", "light");

// Feature flag (Tier 2)
const showNewUI = await client.isFlagEnabled("new-dashboard", {
  userId: "user-123",
});
if (showNewUI) {
  renderNewDashboard();
}

// Experiment (Tier 3)
const assignment = await client.getVariant("checkout-experiment", {
  userId: "user-123",
});
if (assignment?.variationKey === "one-click") {
  renderOneClickCheckout();
}

Next.js SDK

npm install @togglebox/sdk-nextjs

import {
  ToggleBoxProvider,
  useFlag,
  useExperiment,
  useConfig,
} from "@togglebox/sdk-nextjs";

// Wrap your app
<ToggleBoxProvider
  platform="web"
  environment="production"
  apiUrl={process.env.NEXT_PUBLIC_TOGGLEBOX_URL!}
>
  <App />
</ToggleBoxProvider>;

// Use in components
function PricingPage() {
  const config = useConfig();
  const { isEnabled } = useFlag("new-pricing");
  const { getVariant } = useExperiment("pricing-test", { userId: user.id });
  const [showNewPricing, setShowNewPricing] = useState(false);
  const [variant, setVariant] = useState<string | null>(null);

  useEffect(() => {
    isEnabled().then(setShowNewPricing);
    getVariant().then(setVariant);
  }, [isEnabled, getVariant]);

  return showNewPricing ? <NewPricing variant={variant} /> : <OldPricing />;
}

Expo/React Native SDK

npm install @togglebox/sdk-expo

import {
  ToggleBoxProvider,
  useConfig,
  useFlags,
  useToggleBox,
} from "@togglebox/sdk-expo";

// Wrap your app with offline persistence
<ToggleBoxProvider
  platform="mobile"
  environment="production"
  apiUrl="https://your-togglebox-api.com"
  persistToStorage={true}
  storageTTL={86400000}
>
  <App />
</ToggleBoxProvider>;

// Use in components
function HomeScreen() {
  const config = useConfig();
  const flags = useFlags();
  const { isLoading, isOnline, refresh } = useToggleBox();

  // Works offline with cached data
  return <View>...</View>;
}

Example Apps

Both example apps are kitchen sink demos with copy-paste ready code:

Next.js Example

Full-featured Next.js 15 app demonstrating:

Quick Start	Complete Examples
Provider Setup	Feature Toggle UI
useConfig Hook	A/B Test CTA Buttons
useFlag Hook	Config-Driven Themes
useExperiment Hook	SSR with Hydration
Event Tracking	Polling Updates
SSR Config Fetching

pnpm dev:example-nextjs  # http://localhost:3002

Expo Example

React Native/Expo app demonstrating:

Quick Start	Advanced
Provider Setup	Conversion Tracking
Remote Config	Offline Storage (MMKV)
Feature Flags	Polling & Refresh
Experiments	Health Check
	Error Handling

pnpm dev:example-expo  # Expo Go or simulator

See the Next.js Example README and Expo Example README for detailed documentation.

Deployment

AWS Lambda

cd apps/api
npm install -g serverless
serverless deploy --stage production

Best with DynamoDB for serverless-native performance.

Cloudflare Workers

cd apps/api
npm install -g wrangler
wrangler deploy

Use with Cloudflare D1 for edge-first deployment.

Docker

docker build -t togglebox .
docker run -p 3000:3000 togglebox

Works with any database backend.

Self-Hosted

Deploy on any Node.js environment with your preferred database.

Database Support

Database	Best For
DynamoDB	AWS Lambda, serverless
Cloudflare D1	Cloudflare Workers, edge
PostgreSQL	Self-hosted, full SQL
MySQL	Self-hosted, enterprise
MongoDB	Document-oriented workloads
SQLite	Local development, testing

Configure via DB_TYPE environment variable:

DB_TYPE=postgresql
DATABASE_URL=postgresql://user:pass@localhost:5432/togglebox

Repository Structure

togglebox/
├── apps/
│   ├── api/              # Express.js API (multi-platform)
│   ├── admin/            # Admin dashboard (Next.js)
│   ├── example-nextjs/   # Next.js example app
│   └── example-expo/     # Expo example app
├── packages/
│   ├── core/             # Core business logic
│   ├── database/         # Multi-database abstraction
│   ├── cache/            # Cache providers (CloudFront, Cloudflare)
│   ├── auth/             # Authentication (optional)
│   ├── flags/            # Feature flag logic
│   ├── experiments/      # Experimentation logic
│   ├── configs/          # Remote config logic
│   ├── stats/            # Analytics and tracking
│   ├── sdk-js/           # JavaScript SDK
│   ├── sdk-nextjs/       # Next.js SDK
│   └── sdk-expo/         # Expo SDK
└── infrastructure/       # IaC templates

Hosted Version

Don't want to manage infrastructure? ToggleBox Cloud gives you:

Zero maintenance - We handle hosting, scaling, and updates
Team collaboration - Multi-user workspaces with roles
Enterprise features - SSO, audit logs, advanced analytics
Guaranteed uptime - SLA-backed reliability

Get started free - No credit card required.

License

Elastic License 2.0 (ELv2)

Use, modify, and self-host for your organization
Build products and services on top of it
Distribute modified versions

Limitation: Cannot offer ToggleBox as a hosted service to third parties.

SDK Publishing & Monorepo

This repository is a monorepo containing all ToggleBox packages and SDKs. SDKs are automatically published to npm and Packagist via GitHub Actions workflows.

Published SDKs

JavaScript (npm):

@togglebox/sdk - Core JavaScript SDK
@togglebox/sdk-nextjs - Next.js SDK with React hooks
@togglebox/sdk-expo - Expo/React Native SDK

PHP (Packagist):

togglebox/sdk - Core PHP SDK
togglebox/laravel - Laravel SDK

Automated Publishing

JavaScript SDKs (npm):

Managed in the monorepo at packages/sdk-js/, packages/sdk-nextjs/, packages/sdk-expo/
Published directly from monorepo to npm
See PUBLISHING.md for details

PHP SDKs (Packagist):

Managed in the monorepo at packages/sdk-php/, packages/sdk-laravel/
Automatically synced to separate repositories via GitHub Actions on every push to main:
- packages/sdk-php/ → togglebox-php
- packages/sdk-laravel/ → togglebox-laravel
Packagist auto-detects updates from the split repositories
See PUBLISHING.md for details

How it works:

Developers work in the monorepo (packages/sdk-php/, packages/sdk-laravel/)
On push to main, GitHub Actions automatically splits and syncs to separate repos
Packagist detects changes via GitHub webhooks and updates packages
No manual splitting or syncing required!

Contributing

Contributions welcome! See our contributing guide.

# Fork and clone
git clone https://github.com/your-username/togglebox.git

# Create a branch
git checkout -b feature/your-feature

# Make changes and test
pnpm test
pnpm lint

# Submit a PR

Links

Built with TypeScript, Express.js, Next.js, and pnpm. .

Name		Name	Last commit message	Last commit date
Latest commit History 178 Commits
.claude		.claude
.github		.github
apps		apps
docker		docker
docs		docs
infrastructure		infrastructure
packages		packages
scripts		scripts
.gitignore		.gitignore
.prettierignore		.prettierignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
PUBLISHING.md		PUBLISHING.md
README.md		README.md
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.prod.yml		docker-compose.prod.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
settings.local.json		settings.local.json
tsconfig.json		tsconfig.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

ToggleBox

Visual Overview

Core Features

Remote Configs

Feature Flags

Experiments

Analytics

Why ToggleBox?

Quick Start

Prerequisites

Installation

Docker Development (Alternative)

Seed Demo Data

SDKs

JavaScript SDK

Next.js SDK

Expo/React Native SDK

Example Apps

Next.js Example

Expo Example

Deployment

AWS Lambda

Cloudflare Workers

Docker

Self-Hosted

Database Support

Repository Structure

Hosted Version

License

SDK Publishing & Monorepo

Published SDKs

Automated Publishing

Contributing

Links

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages