Liteguard

Appearance

JavaScript SDK Guide (Browser) ​

This guide covers adding Liteguard to a browser-side JavaScript or TypeScript application. For Node.js servers see the Node.js guide. For React applications see the React guide.

Prerequisites ​

  • A Project Client Token from your Liteguard project. Follow the Getting Started guide through the Copy a Project Client Token step if you do not have one yet.
  • A browser build pipeline such as Vite, webpack, esbuild, or Rollup.

Install the SDK ​

bash
npm install @liteguard/liteguard

The package detects the browser environment automatically and uses the browser runtime entry point, which relies on performance.now() and performance.memory for measurement and flushes buffered telemetry signals on visibilitychange and pagehide.

Initialize the client ​

Create a single LiteguardClient instance at application startup and reuse it for the lifetime of the page.

ts
import { LiteguardClient } from '@liteguard/liteguard';

const client = new LiteguardClient('pcid-...');
await client.start();

start() fetches the guard bundle and begins the background refresh cycle. Call it once before evaluating any guards.

The token is included in your built application bundle. This is acceptable because it grants access only to your project's public guard data.

Environment ​

To target a named environment, pass environment in the options:

ts
const client = new LiteguardClient('pcid-...', {
  environment: 'production',
});

The slug must match one of the environments defined in your workspace. Slugs are visible in Config > Workspace > [your workspace] under Environments.

Evaluate a guard ​

client.isOpen(guardName) is synchronous and reads from the locally cached bundle. There is no network round-trip per check.

When you use TypeScript, string literals passed to isOpen, peekIsOpen, evaluate, and executeIfOpen are checked at compile time against the guard-name contract. Dynamically constructed strings are not validated in the client.

ts
if (client.isOpen('feature.new_ui')) {
  showNewUI();
} else {
  showLegacyUI();
}

Passing properties ​

Pass a properties map to match against rules configured in the Liteguard UI:

ts
if (client.isOpen('feature.new_ui', {
  properties: {
    userId: currentUser.id,
    plan: currentUser.plan,
  },
})) {
  showNewUI();
}

Scopes ​

For a set of related checks sharing the same properties, create a scope once and call isOpen on it:

ts
const scope = client.createScope({
  properties: {
    userId: currentUser.id,
    plan: currentUser.plan,
  },
});

if (scope.isOpen('feature.new_ui')) { /* ... */ }
if (scope.isOpen('feature.export')) { /* ... */ }

In the browser runtime, scopes do not propagate across await boundaries. For async paths, pass the scope explicitly to each isOpen call.

Verify in Liteguard ​

After calling isOpen at least once, open the Guards tab and confirm your guard appears. See Your First Guard to configure its behavior.

Next steps ​