Initialization

Constructor


import { CanaryGate } from '@canarygate/sdk/client' // browser
// or
import { CanaryGate } from '@canarygate/sdk/server' // server runtimes
 
new CanaryGate(apiKey: string, options?: CanaryGateOptions)

Parameters

Parameter	Type	Required	Description
`apiKey`	`string`	Yes	Environment API Key. Created under Settings → API Keys.
`options`	`CanaryGateOptions`	No	Configuration options. See below.

`CanaryGateOptions`

The API base URL is resolved automatically from the CANARYGATE_BASE_URL environment variable (or NEXT_PUBLIC_CANARYGATE_BASE_URL in browser builds), defaulting to https://api.canarygate.dev. Set the variable when self-hosting or during local development. Options that belong to the other entry point throw at construction.

Option	Type	Default	Description
`environment`	`string`	default environment	Environment slug, sent via the `X-Environment` header.
`pollIntervalMs`	`number`	`30000`	Browser polling interval in ms (clamped to a 3000ms minimum); set 0 to disable. Throws on the server entry.
`reconnectDelay`	`number`	`5000`	Initial delay in ms before reconnecting a dropped stream. Server-only; throws on the browser entry.
`maxReconnectDelay`	`number`	`30000`	Maximum backoff delay in ms for stream reconnection. Server-only.
`heartbeatTimeoutMs`	`number`	`65000`	Time in ms without a server heartbeat before the stream is considered dead and reconnects. Server-only.
`onUpdate`	`function`	—	Called whenever the evaluated flag set changes, with the updated flags. Never called on initial load.

`init()`


await canary.init()

Executes two actions in sequence:

Makes an HTTP fetch to load all flags for the environment (snapshot)
On the server, opens SSE automatically; in the browser, starts polling.

Always await init() before reading flags — otherwise, getFlag() may return undefined before the initial load completes.

Examples

Browser (React)

In browsers the SDK uses the snapshot plus polling (pollIntervalMs). Changes detected by the polling refresh are reported through the onUpdate callback, so the UI can react without a full reload.


import { CanaryGate, type FlagData } from '@canarygate/sdk/client'
import { useEffect, useState } from 'react'
 
export function useCanaryGate() {
  const [flags, setFlags] = useState<FlagData[]>([])
  const [isReady, setIsReady] = useState(false)
 
  useEffect(() => {
    const client = new CanaryGate(process.env.NEXT_PUBLIC_CANARYGATE_KEY!, {
      onUpdate: (updated) => setFlags(updated)
    })
 
    client.init().then(() => {
      setFlags(client.getFlags())
      setIsReady(true)
    })
 
    return () => {
      client.disconnect()
    }
  }, [])
 
  return { flags, isReady }
}

Node.js (singleton)


import { CanaryGate } from '@canarygate/sdk/server'
 
let client: CanaryGate | null = null
 
export async function getCanaryGate() {
  if (!client) {
    client = new CanaryGate(process.env.CANARYGATE_KEY!)
    await client.init()
  }
  return client
}

One-shot script


import { CanaryGate } from '@canarygate/sdk/server'
 
const client = new CanaryGate('cg_api_key')
await client.init()
 
const flag = client.getFlag('run-migration')
if (flag?.enabled) {
  await runMigration()
}
 
// Disconnect (closes the SSE stream so the process can exit)
client.disconnect()