Traffical

Traffical is a parameter-first experimentation and optimization platform. It unifies feature flags, A/B testing, and contextual bandits into a single system. SDKs resolve parameters locally at the edge — no per-request API calls, sub-millisecond latency, works offline.

Mental Model

Traffical is parameter-first. You define parameters with defaults, and Traffical handles the rest.

┌─────────────────────────────────────────────────────────────────────┐
│  Your Code                                                          │
│                                                                     │
│  1. Define parameters with defaults                                 │
│  2. Use the resolved values                                         │
│  3. Track events on conversion                                      │
└─────────────────────────────────────────────────────────────────────┘
                              ▲
                              │  (hidden from you)
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Traffical                                                          │
│                                                                     │
│  • Layers & policies for mutual exclusivity                         │
│  • Bucket assignment & deterministic hashing                        │
│  • Thompson Sampling & contextual bandits                           │
│  • Statistical analysis & optimization                              │
└─────────────────────────────────────────────────────────────────────┘

Key insights:

1. Parameters, Not Experiments — You define parameters with defaults. Experiments, feature flags, and optimizations are policies that control parameter assignment. Your code doesn't need to know which.
2. Resolution Is Local — The SDK fetches a config bundle once and caches it. Every resolution call is synchronous from cache — no network latency, no render flicker.
3. Decisions Are Tracked Automatically — When you call

   useTraffical()

   or

   decide()

   , a decision event is automatically sent to Traffical (enabled by default via

   trackDecisions: true

   ). This connects parameter resolution to conversion events for intent-to-treat analysis. No manual setup needed.
4. Track Events for Learning — Call

   track()

   when valuable actions happen (purchase, signup, etc.). Traffical uses this data for adaptive optimization.

When to Use Traffical

Recommended Workflow

Always use the Traffical CLI to manage parameters. The CLI is the primary tool for setting up and syncing configuration. Do not skip it.

1. Initialize — Run

   npx @traffical/cli init --api-key <management-key> --framework <name> --yes

   to set up the project non-interactively (or check for an existing

   .traffical/

   directory). The user must provide a Management Key or Full Access key from the dashboard. Always pass

   --framework

   and

   --yes

   to avoid interactive prompts.
2. Define parameters — Add parameters and events to

   .traffical/config.yaml

3. Sync — Run

   npx @traffical/cli push

   to sync parameters to the Traffical platform
4. Install SDK — Add the appropriate SDK package to your project
5. Use in code — Resolve parameters and track events using the SDK
6. Verify — Run

   npx @traffical/cli status

   to confirm everything is in sync

The Traffical CLI

The CLI (

@traffical/cli

npx

npx @traffical/cli <command>

Or install globally for shorter commands:

npm install -g @traffical/cli
traffical <command>

Check for existing setup

Look for a

.traffical/

traffical.yaml

Initialize a new project

If no

.traffical/

Important: The

--api-key

flag requires a real Management Key or Full Access key. Never fabricate or guess API keys. If no key is available in environment variables (

TRAFFICAL_API_KEY

) or

~/.trafficalrc

, ask the user to provide one from https://app.traffical.io/settings/api-keys.

# Basic init (will auto-detect framework and prompt if needed):
npx @traffical/cli init --api-key <management-key>

# Fully non-interactive init (recommended for AI agents and CI/CD):
npx @traffical/cli init --api-key <management-key> --framework react --yes

Available flags for

init

--api-key <key>

TRAFFICAL_API_KEY

~/.trafficalrc

--framework <name>

react

nextjs

svelte

sveltekit

vue

nuxt

node

--project <id>

-y, --yes

--no-sdk-key

For AI agents: Always pass

--framework

and

--yes

to avoid interactive prompts that will hang in non-TTY environments.

This creates:

.traffical/
├── config.yaml      # Parameter and event definitions (committed)
├── .env             # TRAFFICAL_API_KEY=... (gitignored, auto-generated SDK key)
├── .gitignore       # Ensures .env is never committed
├── AGENTS.md        # AI agent integration guide (project-specific)
└── TEMPLATES.md     # Framework-specific code templates

The CLI auto-detects your framework (React, Next.js, Svelte, SvelteKit, Vue, Nuxt, Node.js) and generates appropriate templates. Existing synced parameters and events are imported into

config.yaml

After init, add

TRAFFICAL_API_KEY

.traffical/.env

.env

sdk:read

sdk:write

Managing parameters with the CLI

After initialization, use the CLI to keep local config and the Traffical platform in sync:

# After adding or modifying parameters in config.yaml — push to platform
npx @traffical/cli push

# Before writing code — check what parameters exist and their sync status
npx @traffical/cli status

# Pull latest parameters from the platform into local config
npx @traffical/cli pull

# Bidirectional sync (local wins for conflicts)
npx @traffical/cli sync

# Import specific parameters from the dashboard (supports wildcards)
npx @traffical/cli import "ui.*"

# Validate config without pushing (dry run)
npx @traffical/cli push --dry-run

Always run

npx @traffical/cli push

.traffical/config.yaml

Authentication

Traffical uses different API key types for different purposes:

traffical_sk_*

sdk:read

sdk:write

traffical_sk_*

mgmt:read

mgmt:write

traffical_sk_*

sdk:*

mgmt:*

admin

How init handles keys

1. You provide a Management Key (or Full Access key) via

   --api-key

   or

   ~/.trafficalrc

2. The CLI authenticates and selects org/project
3. The CLI auto-creates a project-scoped SDK key via the API and saves it to

   .traffical/.env

4. The

   .traffical/.gitignore

   is created/updated to ensure

   .env

   is never committed

This means:

• The Management Key stays in

  ~/.trafficalrc

  (for CLI operations like push/pull/sync)
• The SDK Key goes into

  .traffical/.env

  (for runtime use in your app)
• Only the least-privileged key (SDK) is used at runtime — no risk of leaking management access

SDK key location

The SDK key auto-generated by

init

.traffical/.env
# Contains: TRAFFICAL_API_KEY=traffical_sk_...

Copy this value to your project's

.env

SDK configuration values

After

traffical init

.traffical/config.yaml

project.id

project.orgId

env

"production"

.traffical/.env

TRAFFICAL_API_KEY

Install an SDK

@traffical/react

@traffical/svelte

@traffical/node

@traffical/js-client

# Pick the one matching your framework
npm install @traffical/react
# or
npm install @traffical/svelte
# or
npm install @traffical/node

SDK Usage

React / Next.js

Provider setup (wrap your app once):

import { TrafficalProvider } from "@traffical/react";

function App() {
  return (
    <TrafficalProvider
      config={{
        orgId: "org_xxx",
        projectId: "proj_xxx",
        env: "production",
        apiKey: "pk_live_your_public_key",
      }}
      // Optional: provide unitKeyFn for logged-in users
      // unitKeyFn: () => currentUser.id,
    >
      <MyApp />
    </TrafficalProvider>
  );
}

Use in components:

import { useTraffical } from "@traffical/react";

function CheckoutButton() {
  const { params, track } = useTraffical({
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.button.label": "Buy now",
    },
  });

  return (
    <button
      style={{ backgroundColor: params["checkout.button.color"] }}
      onClick={() => track("checkout_click")}
    >
      {params["checkout.button.label"]}
    </button>
  );
}

Svelte / SvelteKit

Layout setup:

<!-- src/routes/+layout.svelte -->
<script>
  import { setTrafficalContext } from "@traffical/svelte";

  setTrafficalContext({
    orgId: "org_xxx",
    projectId: "proj_xxx",
    env: "production",
    apiKey: "pk_live_your_public_key",
    context: { userId: data.user?.id ?? "anonymous" },
  });
</script>

<slot />

Use in components (

params

track

$

<script>
  import { getTraffical } from "@traffical/svelte";

  const { params, track } = getTraffical({
    defaults: {
      "checkout.button.color": "#1E6EFB",
      "checkout.button.label": "Buy now",
    },
  });
</script>

<button
  style="background-color: {$params['checkout.button.color']}"
  on:click={() => $track("checkout_click")}
>
  {$params["checkout.button.label"]}
</button>

Node.js (Server-side)

import { createTrafficalClient } from "@traffical/node";

const traffical = await createTrafficalClient({
  orgId: "org_xxx",        // from .traffical/config.yaml
  projectId: "proj_xxx",   // from .traffical/config.yaml
  env: "production",
  apiKey: process.env.TRAFFICAL_API_KEY!,  // from .traffical/.env
});

// Resolve parameters (synchronous, from cached bundle)
const params = traffical.getParams({
  context: { userId: "user_789", locale: "en-US" },
  defaults: {
    "checkout.button.color": "#1E6EFB",
    "pricing.discount_pct": 0,
  },
});

// Track events (value goes in properties, unitKey in options)
traffical.track("purchase", { value: 49.99 }, { unitKey: "user_789" });

Node.js (CLI / Scripts)

For non-web contexts like CLI tools, batch jobs, or scripts, you can use

@traffical/node

import { createTrafficalClient } from "@traffical/node";

const traffical = await createTrafficalClient({
  orgId: "org_xxx",        // from .traffical/config.yaml
  projectId: "proj_xxx",   // from .traffical/config.yaml
  env: "production",
  apiKey: process.env.TRAFFICAL_API_KEY!,
});

const params = traffical.getParams({
  context: { unitKey: "batch-job" },
  defaults: {
    "feature.new_algorithm": false,
    "processing.batch_size": 100,
  },
});

if (params["feature.new_algorithm"]) {
  // Use new algorithm
}

track() API

The

track()

• React/Svelte (client-side):

  track(event, properties?)

  — The

  decisionId

  and

  unitKey

  are automatically bound from the provider context. Just call

  track("purchase", { value: 49.99 })

  .
• Node.js (server-side):

  track(event, properties?, options?)

  — You must provide

  unitKey

  in the third argument:

  traffical.track("purchase", { value: 49.99 }, { unitKey: userId })

  . Optionally pass

  decisionId

  for explicit attribution.

Config-as-Code

Parameters and events are defined in

.traffical/config.yaml

traffical.yaml

version: "1.0"
project:
  id: proj_xxx
  orgId: org_xxx

parameters:
  checkout.button.color:
    type: string
    default: "#1E6EFB"
    description: Primary CTA button color

  checkout.show_trust_badges:
    type: boolean
    default: false

  pricing.discount_pct:
    type: number
    default: 0

events:
  purchase:
    valueType: currency
    unit: USD
    description: User completes a purchase

  add_to_cart:
    valueType: count
    description: User adds item to cart

Parameter types

string

number

boolean

json

Event value types

currency

count

rate

boolean

Adding events to config.yaml

Define events in the

events:

.traffical/config.yaml

events:
  purchase:
    valueType: currency
    unit: USD
    description: User completes a purchase

  signup:
    valueType: boolean
    description: User creates an account

  page_view:
    valueType: count
    description: User views a page

Each event has:

• valueType

  (required):

  currency

  ,

  count

  ,

  rate

  , or

  boolean

• unit

  (optional): unit label for currency events (e.g.,

  USD

  ,

  EUR

  )

• description

  (optional but recommended): human-readable explanation

After adding events, run

npx @traffical/cli push

Events discovered at runtime (via

track()

Namespaces

Namespaces are optional organizational groupings for parameters. They help organize parameters in the dashboard but do not affect how you use them in code.

parameters:
  bookmarks.max_stored:
    type: number
    default: 100
    namespace: bookmarks   # optional organizational grouping
    description: Maximum bookmarks per user

• The

  "main"

  namespace is the default and is omitted from config
• When parameters are imported from the dashboard (via

  npx @traffical/cli pull

  or during

  init

  ), they may include

  namespace: <name>

  — this is normal
• Namespace is independent of dot-notation naming (e.g.,

  bookmarks.max_stored

  can be in namespace

  bookmarks

  , but this is a convention, not enforced)
• You do not need to specify a namespace when creating new parameters — they will use the default namespace

Parameter Naming Conventions

Use dot notation:

category.subcategory.name

feature.*

feature.new_checkout

feature.dark_mode

ui.*

ui.cta.text

ui.hero.variant

pricing.*

pricing.discount

pricing.tier_multiplier

copy.*

copy.headline

copy.cta_text

experiment.*

experiment.checkout.variant

Best Practices

1. Always use the CLI — Run

   npx @traffical/cli push

   after editing config. Run

   npx @traffical/cli status

   to check sync state. Never skip the CLI — it is the bridge between your config files and the Traffical platform.

2. Check existing parameters first — Look in

   .traffical/config.yaml

   (or

   traffical.yaml

   ) before creating new ones. Run

   npx @traffical/cli status

   to see what's already defined. Reuse existing parameters where possible.

3. Define parameters in config, then push — Add new parameters to

   .traffical/config.yaml

   and run

   npx @traffical/cli push

   to sync them. This keeps the config file as the source of truth and prevents drift with the dashboard.

4. Always provide in-code defaults — Defaults appear in two places: in

   config.yaml

   (the source of truth for the dashboard and experiment setup) and in your

   getParams()

   /

   useTraffical()

   calls (the offline fallback). In-code defaults are what the SDK returns when the config bundle hasn't loaded yet or is unreachable. The bundle's resolved value always takes precedence when available.

5. Track events at conversion points — Call

   track()

   on purchases, signups, and other valuable actions. This enables adaptive optimization.

6. Group related parameters — Keep correlated params in one

   useTraffical()

   /

   getTraffical()

   /

   getParams()

   call for proper attribution.

7. Use meaningful param names — Follow dot notation:

   category.subcategory.name

   . Be descriptive.

What You Don't Need to Know

These are internal concepts handled by Traffical automatically:

• Layers, policies, allocations — Experiment infrastructure is managed in the dashboard
• Bucket assignment and hashing — Deterministic user assignment happens automatically
• Whether an A/B test vs. optimization is running — Your code is the same either way
• Statistical significance calculations — Traffical handles analysis in the background
• Decision deduplication — Multiple resolution calls are handled efficiently

Just parametrize your app, track conversions, and let Traffical handle the rest.

Documentation

• Quickstart: https://docs.traffical.io/quickstart
• How It Works: https://docs.traffical.io/how-it-works
• Parameters: https://docs.traffical.io/concepts/parameters
• React SDK: https://docs.traffical.io/sdks/react
• Svelte SDK: https://docs.traffical.io/sdks/svelte
• Node.js SDK: https://docs.traffical.io/sdks/node
• CLI: https://docs.traffical.io/tools/cli
• API Overview: https://docs.traffical.io/api/overview
• Dashboard: https://app.traffical.io