Variables

Forge Variables are key-value pairs that store environment-specific configuration for your app — such as external URLs, feature flags, or display settings. Variables are managed separately from the app manifest and can be updated without redeploying.

Overview

Each app has two independent variable sets: one for dev and one for live. This allows you to use different endpoints or settings per environment without changing your code.

Variables are stored as plain text

Do not store secrets, API keys, passwords, or other sensitive values in variables. Variable values are stored unencrypted in the database and are readable by anyone with access to the app's configuration.

Variables are:

Not part of the manifest — they are managed through the API or SDK, not in ptkl.config.js
Per-environment — dev and live have completely separate values
Injected at runtime — available as a global inside services and lifecycle scripts

Managing Variables

Using the SDK

import { Platform } from '@ptkl/sdk'

const platform = new Platform()

// Read all variables for the current environment
const vars = await platform.forge.getVariables('my-app')

// Replace all variables for the current environment
await platform.forge.updateVariables('my-app', {
    WEBHOOK_URL: 'https://example.com/hook',
    MAX_RETRIES: 3,
    FEATURE_V2_ENABLED: true,
})

// Add or update a single variable
await platform.forge.addVariable('my-app', 'WEBHOOK_URL', 'https://example.com/hook')

Using the API

# Read variables (dev environment)
curl https://api.ptkl.app/v1/forge/my-app/variables \
  -H "X-Project-Env: dev" \
  -H "Authorization: Bearer <token>"

# Update variables (dev environment)
curl -X PATCH https://api.ptkl.app/v1/forge/my-app/variables \
  -H "X-Project-Env: dev" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"WEBHOOK_URL": "https://staging.example.com/hook", "MAX_RETRIES": 3}'

The environment is determined by the X-Project-Env header (defaults to dev).

Accessing Variables in Services

Variables are available as the $variables global inside service scripts:

import '@ptkl/components/forge-service'

const webhookUrl = $variables.WEBHOOK_URL
const maxRetries = $variables.MAX_RETRIES || 3

const result = await http.post(webhookUrl, {
    event: 'invoice.created',
    data: input,
})

response.json({ delivered: true })

The platform injects the correct variable set (dev or live) based on which environment the service is executing in.

Accessing Variables in Lifecycle Scripts

Variables are also available in install and uninstall scripts:

import { Platform } from '@ptkl/sdk'

const platform = new Platform()

const endpoint = $variables.EXTERNAL_API_URL

if (endpoint) {
    await http.post(endpoint, { event: 'app_installed' })
}

return { success: true }

Setting Variables During Installation

When an app is installed from the marketplace, initial variables can be provided as part of the installation payload. This allows marketplace apps to prompt for configuration during setup — for example, selecting a region or setting a default language.

Example: Environment-Specific Configuration

A common pattern is to use variables for values that differ between dev and live:

Dev variables:

{
    "WEBHOOK_URL": "https://staging.example.com/hook",
    "DEFAULT_LOCALE": "en_US",
    "DEBUG": true
}

Live variables:

{
    "WEBHOOK_URL": "https://example.com/hook",
    "DEFAULT_LOCALE": "sr",
    "DEBUG": false
}

Your service code stays the same — the platform injects the right set at runtime:

const locale = $variables.DEFAULT_LOCALE || 'en_US'