Togglely
Get Started

Introduction

Togglely is an open-source feature flag management platform designed for modern development teams. It allows you to deploy code more frequently and safely by decoupling feature releases from code deployments.

Self-Hosted

Your data stays in your infrastructure

Open Source

MIT Licensed, fully customizable

Multi-Tenant

Organizations & Brands support

Enterprise Ready

RBAC, audit logs, API keys

Quick Start

Get Togglely running locally in under 5 minutes using Docker Compose.

1. Clone and Configure

bash
git clone https://github.com/nuvooo/togglely.git
cd togglely

# Copy environment file
cp .env.example .env

# Edit .env with your settings
# Then start with Docker Compose
docker-compose up -d

# The app will be available at http://localhost

2. Install SDK

bash
npm install @togglely/sdk-core
# or
yarn add @togglely/sdk-core

3. Use in Your App

typescript
import { TogglelyClient } from '@togglely/sdk-core';

const client = new TogglelyClient({
  apiKey: 'your-sdk-key',
  project: 'my-app',
  environment: 'production',
  // Optional: Custom base URL for self-hosted
  baseUrl: 'https://api.togglely.de'
});

// Initialize the client
await client.init();

// Check if feature is enabled
const isEnabled = await client.getValue('new-dashboard');

// With user context for targeting
const theme = await client.getValue('theme', {
  userId: 'user-123',
  plan: 'premium',
  region: 'eu'
});

Installation

Prerequisites

  • Docker and Docker Compose
  • Node.js 18+ (for SDK development)
  • MongoDB 5.0+ (or use the included Docker container)
  • Redis 6+ (optional, for caching)

Configuration

Create a .env file with the following variables:

env
# Required
DATABASE_URL=mongodb://mongodb:27017/togglely?replicaSet=rs0
JWT_SECRET=your-super-secret-jwt-key

# Optional - for email notifications
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@togglely.de

# Frontend URL for invite links
FRONTEND_URL=https://togglely.de

Feature Flags

Feature flags (or feature toggles) allow you to enable or disable functionality without deploying new code.

Flag Types

  • BOOLEANSimple on/off toggle
  • STRINGText values like themes, configs
  • NUMBERNumeric values for limits, thresholds
  • JSONComplex configuration objects

Environments

Environments allow you to manage flags separately for different stages of your deployment pipeline.

Default Environments

Each project comes with three default environments:

  • Development - For local development and testing
  • Staging - For pre-production validation
  • Production - For live users

Tip: Environment-specific values override the default flag value. This lets you enable a feature in development while keeping it off in production.

Organizations

Organizations are the top-level container in Togglely. They contain projects, members, and API keys.

Creating an Organization

  1. Sign up or log in to Togglely
  2. Click "New Organization" on the organizations page
  3. Enter a name and unique slug
  4. Invite team members

Projects

Each organization can have multiple projects. Projects contain feature flags and environments. There are two project types:

  • Single - Standard project with feature flags
  • Multi - Supports multiple brands/tenants with brand-specific flags

Roles & Permissions

Togglely uses role-based access control (RBAC) to manage permissions within organizations.

OWNERFull Access

Can manage organization settings, delete organization, manage billing, and all other actions.

ADMINManager

Can create projects, manage members, manage API keys, and configure settings. Cannot delete organization.

MEMBERDeveloper

Can create and manage feature flags, toggle values. Cannot manage organization settings or members.

VIEWERRead Only

Can view flags and their values. Cannot make any changes.

JavaScript/TypeScript SDK

The official JavaScript SDK provides a simple interface for evaluating feature flags with built-in caching and offline support.

Installation

bash
npm install @togglely/sdk-core

Basic Usage

typescript
import { TogglelyClient } from '@togglely/sdk-core';

const client = new TogglelyClient({
  apiKey: 'your-sdk-key',
  project: 'my-app',
  environment: 'production',
  // Optional: Custom base URL for self-hosted
  baseUrl: 'https://api.togglely.de'
});

// Initialize the client
await client.init();

// Check if feature is enabled
const isEnabled = await client.getValue('new-dashboard');

// With user context for targeting
const theme = await client.getValue('theme', {
  userId: 'user-123',
  plan: 'premium',
  region: 'eu'
});

React Integration

Use Togglely with React using hooks and context for seamless feature flag management.

Installation

bash
npm install @togglely/sdk-core

Usage with Hooks

tsx
import { useEffect, useState } from 'react';
import { TogglelyClient } from '@togglely/sdk-core';

// Initialize client outside component
const togglely = new TogglelyClient({
  apiKey: process.env.REACT_APP_TOGGLELY_KEY,
  project: 'my-app',
  environment: 'production'
});

function App() {
  const [isReady, setIsReady] = useState(false);

  useEffect(() => {
    togglely.init().then(() => setIsReady(true));
  }, []);

  if (!isReady) return <div>Loading...</div>;

  return (
    <div>
      {togglely.getValueSync('new-feature') ? (
        <NewFeature />
      ) : (
        <OldFeature />
      )}
    </div>
  );
}

// Or with Hook
function useFeatureFlag(key, context) {
  const [value, setValue] = useState(null);
  
  useEffect(() => {
    togglely.getValue(key, context).then(setValue);
  }, [key, JSON.stringify(context)]);
  
  return value;
}

Tip: Initialize the client outside your components to ensure a single instance across re-renders.

Svelte Integration

Integrate Togglely with Svelte using reactive statements and stores.

Installation

bash
npm install @togglely/sdk-core

Component Usage

svelte
<script>
  import { onMount } from 'svelte';
  import { TogglelyClient } from '@togglely/sdk-core';

  const togglely = new TogglelyClient({
    apiKey: import.meta.env.VITE_TOGGLELY_KEY,
    project: 'my-app',
    environment: 'production'
  });

  let isEnabled = false;
  let isReady = false;

  onMount(async () => {
    await togglely.init();
    isEnabled = togglely.getValueSync('new-feature');
    isReady = true;
  });
</script>

{#if !isReady}
  <div>Loading...</div>
{:else if isEnabled}
  <NewFeature />
{:else}
  <OldFeature />
{/if}

<!-- Or with store -->
<script context="module">
  import { writable } from 'svelte/store';
  
  export function featureFlag(key, context = {}) {
    const { subscribe, set } = writable(null);
    
    togglely.getValue(key, context).then(set);
    
    return { subscribe };
  }
</script>

Tip: Create a Svelte store wrapper for reactive flag updates across your app.

Vue.js Integration

Use Togglely with Vue 3 using the Composition API and custom composables.

Installation

bash
npm install @togglely/sdk-core

Usage with Composition API

vue
<template>
  <div v-if="!isReady">Loading...</div>
  <NewFeature v-else-if="isEnabled" />
  <OldFeature v-else />
</template>

<script setup>
import { ref, onMounted } from 'vue';
import { TogglelyClient } from '@togglely/sdk-core';

const togglely = new TogglelyClient({
  apiKey: import.meta.env.VITE_TOGGLELY_KEY,
  project: 'my-app',
  environment: 'production'
});

const isReady = ref(false);
const isEnabled = ref(false);

onMounted(async () => {
  await togglely.init();
  isEnabled.value = togglely.getValueSync('new-feature');
  isReady.value = true;
});
</script>

<!-- Or with Composable -->
<script>
// composables/useFeatureFlag.js
import { ref, onMounted } from 'vue';

export function useFeatureFlag(key, context = {}) {
  const value = ref(null);
  const isReady = ref(false);

  onMounted(async () => {
    value.value = await togglely.getValue(key, context);
    isReady.value = true;
  });

  return { value, isReady };
}
</script>

Tip: Create a reusable useFeatureFlag composable for cleaner component code.

SDK Configuration

Configuration Options

OptionTypeDescription
apiKeystringYour SDK API key
projectstringProject identifier
environmentstringEnvironment name (dev, staging, prod)
baseUrlstringCustom API base URL (for self-hosted)
refreshIntervalnumberCache refresh interval in ms (default: 60000)

REST API

The REST API allows you to evaluate feature flags from any language or platform.

Evaluate Flags

bash
curl -X POST https://api.togglely.de/api/sdk/flags   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "keys": ["new-feature", "theme-color"],
    "context": {
      "userId": "user-123",
      "email": "user@example.com"
    }
  }'

Response

json
{
  "flags": {
    "new-feature": {
      "key": "new-feature",
      "enabled": true,
      "value": true,
      "type": "BOOLEAN"
    },
    "theme-color": {
      "key": "theme-color",
      "enabled": true,
      "value": "dark",
      "type": "STRING"
    }
  }
}

Docker Compose

The easiest way to run Togglely is with Docker Compose. This sets up the backend, frontend, MongoDB, and Redis.

bash
git clone https://github.com/nuvooo/togglely.git
cd togglely

# Copy environment file
cp .env.example .env

# Edit .env with your settings
# Then start with Docker Compose
docker-compose up -d

# The app will be available at http://localhost

Services

  • frontend - React app served via Nginx (port 80)
  • backend - NestJS API (port 4000)
  • mongodb - Database for storing flags and configs
  • redis - Caching layer (optional)

Environment Variables

env
# Required
DATABASE_URL=mongodb://mongodb:27017/togglely?replicaSet=rs0
JWT_SECRET=your-super-secret-jwt-key

# Optional - for email notifications
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@togglely.de

# Frontend URL for invite links
FRONTEND_URL=https://togglely.de

Required Variables

  • DATABASE_URL - MongoDB connection string
  • JWT_SECRET - Secret for signing JWT tokens

Email Configuration (Optional)

Configure SMTP settings to enable email notifications for invites and password resets.

Deploying with Coolify

Coolify is an open-source alternative to Heroku/Netlify that makes self-hosting easy.

One-Click Deploy

  1. Install Coolify on your server
  2. Create a new resource and select "Public Repository"
  3. Enter https://github.com/nuvooo/togglely
  4. Configure environment variables
  5. Deploy!

Note: Make sure to set up MongoDB and Redis as separate services in Coolify, or use managed services like MongoDB Atlas.