Liteguard

Appearance

React SDK Guide ​

This guide covers adding Liteguard to a React application using LiteguardProvider and the provided hooks. If you are doing server-side rendering or using a meta-framework see the Node.js guide for the server portion.

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.
  • React 18 or later.

Install the SDK ​

bash
npm install @liteguard/liteguard @liteguard/liteguard-react

@liteguard/liteguard provides the core client. @liteguard/liteguard-react provides the provider and hooks.

Add the provider ​

Wrap your application root (or the subtree that needs guard access) with LiteguardProvider. Pass your Project Client Token directly and the provider manages the client lifecycle for you.

tsx
import { LiteguardProvider } from '@liteguard/liteguard-react';

function App() {
  return (
    <LiteguardProvider
      projectClientToken="pcid-..."
      environment="production"
      loading={<Spinner />}
    >
      <Router />
    </LiteguardProvider>
  );
}

The loading prop is rendered while the provider is fetching the initial bundle. When omitted it defaults to rendering nothing (no flash of unguarded content). Once the bundle is ready, children renders and guard evaluations return real values.

Using an externally managed client ​

If you need to control the client lifecycle yourself — for example to call start() before mounting React — pass the client instance directly instead:

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

<LiteguardProvider client={client}>
  <App />
</LiteguardProvider>

In this mode the provider does not call start() or shutdown() — those are your responsibility.

Passing default properties ​

Pass a properties map to the provider to make those properties available to all guard evaluations in the subtree. These are useful for properties that are stable for the session, such as the current user's plan tier:

tsx
<LiteguardProvider
  projectClientToken="pcid-..."
  properties={{ plan: currentUser.plan }}
>
  <App />
</LiteguardProvider>

useIsOpen ​

useIsOpen is the primary hook. It evaluates a guard and returns a boolean. The component re-renders automatically whenever the guard bundle refreshes.

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

tsx
import { useIsOpen } from '@liteguard/liteguard-react';

function CheckoutButton() {
  const checkoutEnabled = useIsOpen('payments.checkout');

  return checkoutEnabled ? <NewCheckout /> : <LegacyCheckout />;
}

Passing properties per call ​

tsx
const betaEnabled = useIsOpen('feature.beta', {
  properties: {
    userId: currentUser.id,
    plan: currentUser.plan,
  },
});

Properties passed to the hook are merged with any properties set on the provider.

useLiteguardReady ​

Returns true once the client has loaded the initial bundle. Use this to defer rendering that depends on guard values until the bundle is available:

tsx
import { useLiteguardReady } from '@liteguard/liteguard-react';

function Dashboard() {
  const ready = useLiteguardReady();

  if (!ready) return <Spinner />;
  return <DashboardContent />;
}

When you provide a loading prop to LiteguardProvider, children does not mount until the bundle is ready, so useLiteguardReady is mainly needed in the external-client mode or when you mount children unconditionally.

useLiteguardClient ​

Returns the underlying LiteguardClient instance when you need direct access, for example to read properties from a scope or call peekIsOpen without triggering a re-render:

tsx
import { useLiteguardClient } from '@liteguard/liteguard-react';

function DiagnosticsPanel() {
  const client = useLiteguardClient();
  // client can be null if no provider is in the tree
  const decision = client?.evaluate('feature.beta', { properties: { userId: '...' } });
  // ...
}

Verify in Liteguard ​

After your application renders and useIsOpen is called, open the Guards tab and confirm the guard appears in the catalog. See Your First Guard to configure its behavior.

Next steps ​