@digesty/miniapp-sdk-react

Thin React adapter for @digesty/miniapp-sdk.

Use this package when:

• you want a provider-owned Mini App client in a React app
• you want React state updates from a MiniAppClient
• you want bootstrap to run in a React effect instead of wiring it manually

Do not use this package when:

• you are not using React
• you want to manage auth flow entirely outside React

Install

pnpm add @digesty/miniapp-sdk @digesty/miniapp-sdk-react react react-dom

Quick Start

"use client";

import { MiniAppProvider, useMiniApp } from "@digesty/miniapp-sdk-react";

function MiniAppScreen() {
  const { client, state, ready, isBootstrapping, retryBootstrap } = useMiniApp();

  if (!ready) {
    return <p>{isBootstrapping ? "Bootstrapping..." : "Waiting..."}</p>;
  }

  if (state.error) {
    return (
      <div>
        <p>{state.error.message}</p>
        <button type="button" onClick={() => void retryBootstrap()}>
          Retry
        </button>
      </div>
    );
  }

  if (state.status === "idle") {
    return (
      <button type="button" onClick={() => void client.startDirectLaunch()}>
        Start Direct Launch
      </button>
    );
  }

  return <pre>{JSON.stringify(state.claims, null, 2)}</pre>;
}

export default function App() {
  return (
    <MiniAppProvider config={{ appID: "your-app-id" }}>
      <MiniAppScreen />
    </MiniAppProvider>
  );
}

API

MiniAppProvider

<MiniAppProvider
  config={config}
  bootstrap="auto"
>
  {children}
</MiniAppProvider>

Props:

• config: MiniAppClientConfig
• bootstrap?: "auto" | "manual"
• children: ReactNode

Notes:

• the provider creates one MiniAppClient per mount
• the provider destroys that client on unmount
• config is frozen at mount time
• bootstrap is frozen at mount time
• to change either one, remount the provider with a different React key

useMiniApp()

Must be used inside MiniAppProvider.

Returns:

• client: MiniAppClient
• state: MiniAppState
• ready: boolean
• isBootstrapping: boolean
• retryBootstrap(): Promise<void>

Imperative actions stay on the core client:

• client.startDirectLaunch()
• client.handleCallback()
• client.requestRefresh()
• client.clearSession()
• client.onTokenUpdate(...)

useMiniAppState(client)

Low-level hook for apps that create the client themselves with createMiniAppClient() from @digesty/miniapp-sdk.

import { createMiniAppClient } from "@digesty/miniapp-sdk";
import { useMiniAppState } from "@digesty/miniapp-sdk-react";

const client = createMiniAppClient({
  appID: "your-app-id",
});

function StateView() {
  const state = useMiniAppState(client);
  return <p>{state.status}</p>;
}

Bootstrap Behavior

When bootstrap="auto", the provider runs one bootstrap pass after mount:

1. if window.location.hash contains digesty_launch_token, call client.initEmbedded()
2. else if the query string contains launch_code, call client.handleCallback()
3. else call client.restoreSession()

ready means the first bootstrap pass has finished, regardless of outcome.

retryBootstrap():

• re-reads the current URL when called
• returns the in-flight promise if a bootstrap pass is already running
• surfaces errors through state.error

Config Defaults

Core SDK config used by the provider:

type MiniAppClientConfig = {
  appID: string;
  apiURL?: string;
  digestyOrigin?: string;
  getLaunchURL?: (args: {
    appID: string;
    codeChallenge: string;
    digestyOrigin: string;
  }) => string;
  storage?: StorageAdapter;
  autoRefresh?: boolean;
};

Defaults:

• apiURL defaults to "https://worker.digesty.vn"
• digestyOrigin defaults to "https://digesty.vn"
• autoRefresh defaults to false
• getLaunchURL defaults to ${digestyOrigin}/apps/${appID}/launch?code_challenge=...

Most apps can start with:

const config = {
  appID: "your-app-id",
};

Use staging explicitly:

const config = {
  appID: "your-app-id",
  digestyOrigin: "https://staging.digesty.vn",
};

Use local dev explicitly:

const config = {
  appID: "app_local_sdk_test",
  apiURL: "http://localhost:8787",
  digestyOrigin: "http://localhost:3000",
  autoRefresh: false,
};

Use digestyOrigin when your app runs against staging or another Digesty web origin. Use getLaunchURL when the launch page route shape differs from the default.

SSR And Frameworks

This package is safe to import in SSR builds, but bootstrap only runs in effects. In practice:

• use it in client components
• do not expect bootstrap to run during server render
• Next.js App Router and TanStack Start should mount the provider in a client boundary

Security Note

@digesty/miniapp-sdk-react uses the same browser-side trust model as @digesty/miniapp-sdk.

• token payloads are parsed in the browser for UI state
• browser state is not a substitute for backend verification
• if your backend consumes a launch token, verify it against GET {apiURL}/api/v2/app-auth/jwks

With default config, that JWKS endpoint is:

https://worker.digesty.vn/api/v2/app-auth/jwks

Backends should verify at least:

• iss === "digesty.ai"
• aud === "app:{appID}"
• app_id === appID
• mode if the endpoint expects one launch mode
• signature, exp, and iat

The React adapter only supports the browser-managed callback flow. If you want a server-managed direct callback with an HttpOnly cookie session, keep that exchange and session logic on the backend.

Relationship To @digesty/miniapp-sdk

@digesty/miniapp-sdk-react does not replace the core SDK. It wraps it.

Use the core SDK directly when you need:

• framework-agnostic usage
• manual client ownership
• imperative integration outside React