> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web SDK Quickstart

> Get started with Suki.js Web SDK - from installation to mounting the SDK UI

This guide walks you through setting up Suki.js in your existing JavaScript or React application, from installation to mounting the SDK UI.

**What will you do**

1. Install the Suki Web SDK package for your framework (JavaScript or React)
2. Initialize the SDK by creating a `SukiAuthManager` from `@suki-sdk/core` with your `partnerToken` and provider fields
3. Mount the SDK UI into your application using the `encounter` object.

<Tip>
  **Using an AI coding tool?**

  Copy the following prompt to add the Suki developer documentation as a skill and [MCP server](/documentation/mcp) to your tool for better AI-assisted coding during the integration process. For all AI options (contextual menu, `llms.txt`, and `skill.md`), refer to [AI-optimized documentation](/documentation/ai-optimized-documentation).

  <Prompt description="Install the Suki developer docs as a skill to get context on Suki's developer tools, APIs, and SDKs. Add the [MCP server](/documentation/mcp) for documentation search." icon="gear" iconType="regular" actions={["copy", "cursor"]}>
    Install the Suki developer docs as skill to get context on Suki's developer tools, APIs, and SDKs.

    npx skills add [https://developer.suki.ai](https://developer.suki.ai)

    Then add the Suki developer docs MCP server for access to documentation search. Follow the MCP instructions at [https://developer.suki.ai/documentation/mcp](https://developer.suki.ai/documentation/mcp).
  </Prompt>
</Tip>

## Prerequisites

For the rest of this documentation, we assume the following setup is complete:

* You have received your `partnerId` from Suki.

* Your host URLs are on the Suki allowlist.

* Your partner configuration in the Suki Platform points to your correct JWKS endpoint.

* Your JWT token contains the key that you specified as your **User identifier field**.

## Install the Suki SDK package

To begin, install the Suki web SDK package in your project. Choose the appropriate package based on your framework:

<Tip>
  You must choose the appropriate package based on your framework. Refer to the [Installation guide](/web-sdk/installation) for more information.
</Tip>

<View title="JavaScript" icon="js">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/js @suki-sdk/core
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/js @suki-sdk/core
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/js @suki-sdk/core
    ```
  </CodeGroup>
</View>

<View title="React" icon="react">
  <CodeGroup>
    ```shell pnpm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    pnpm add @suki-sdk/react @suki-sdk/core
    ```

    ```shell npm theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    npm install @suki-sdk/react @suki-sdk/core
    ```

    ```shell yarn theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    yarn add @suki-sdk/react @suki-sdk/core
    ```
  </CodeGroup>
</View>

For detailed setup instructions, refer to the [Installation guide](/web-sdk/installation).

### Step 1: Initialize the SDK

Initialize the Suki SDK by creating `SukiAuthManager` from `@suki-sdk/core` with the following **required** fields:

* `partnerId` <Badge color="red" size="sm">Required</Badge> - Your `partnerId` from Suki
* `partnerToken` <Badge color="red" size="sm">Required</Badge> - Your `partnerToken` from Suki
* `providerName` <Badge color="red" size="sm">Required</Badge> - The full name of the provider
* `providerOrgId` <Badge color="red" size="sm">Required</Badge> - The organization ID of the provider

Then pass this `authManager` into `initialize()` in JavaScript or `init()` in React.

Run initialization **once**, usually from your app **entry point**, so your app can sign in to Suki and use Web SDK features.

<View title="JavaScript" icon="js">
  Import `@suki-sdk/core` and `@suki-sdk/js`, create `SukiAuthManager` with your `partnerToken` and provider fields, then call `initialize({ authManager })`. Do this in your main application file (for example `index.js` or `app.js`).

  ```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

  const authManager = new SukiAuthManager({
    partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
    partnerToken:
      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
    providerName: "John doe", // Replace with the full name of the provider
    providerOrgId: "1234", // Replace with the provider's organization ID
    environment: "production",
    loginOnInitialize: true,
    providerId,
    providerName,
    providerOrgId,
    providerSpecialty,
  });

  const sdkClient = initialize({
    authManager,
  });
  ```
</View>

<View title="React" icon="react">
  In **Web SDK v3**, your app root only needs `SukiProvider` from `@suki-sdk/react` (no partner props on the provider). In a child component, create `SukiAuthManager` from `@suki-sdk/core` with your `partnerId`, `partnerToken`, and provider fields, then call `init({ authManager })` from `useSuki()` when the SDK is not initialized yet. See `ComponentA.jsx` in the example below.

  <CodeGroup>
    ```jsx App.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { SukiProvider } from "@suki-sdk/react";

    function App() {
      return (
        <SukiProvider>
          {/* init({ authManager }) runs in a child (ComponentA.jsx), not here */}
          <ComponentA />
        </SukiProvider>
      );
    }
    ```

    ```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    import { useEffect, useMemo } from "react";
    import { SukiAuthManager } from "@suki-sdk/core";
    import { useSuki } from "@suki-sdk/react";

    function ComponentA() {
      const authManager = useMemo(
        () =>
          new SukiAuthManager({
            partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
            partnerToken:
              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
            providerName: "John doe", // Replace with the full name of the provider
            providerOrgId: "1234", // Replace with the provider's organization ID
            environment: "production",
            loginOnInitialize: true,
            providerId,
            providerName,
            providerOrgId,
            providerSpecialty,
          }),
        [],
      );

      const { init, isInitialized } = useSuki();

      useEffect(() => {
        if (!isInitialized) {
          init({ authManager });
        }
      }, [init, isInitialized, authManager]);

      return (
        // rest of your code
        <>{/* your ComponentA content */}</>
      );
    }
    ```
  </CodeGroup>
</View>

### Mount the SDK UI

After initializing the web SDK, you can mount the Suki UI into your application using the [`encounter`](/web-sdk/api-reference/types/encounter) object. This object provides patient context for ambient documentation and transcription.

<Note>
  **Encounter and patient IDs:** **`patient.identifier`** and **`encounter.identifier`** (when you set it) must each be strings **at most 36 characters** (<Tooltip tip="VARCHAR is a variable-length SQL string type. varchar(36) caps these identifiers at 36 characters. See the Glossary." cta="View in Glossary" href="/Glossary/v#varchar-36">varchar(36)</Tooltip>). Longer values can fail during composition or ambient setup. See [Patient](/web-sdk/api-reference/types/patient) and [Encounter](/web-sdk/api-reference/types/encounter).
</Note>

<Note>
  If you face any issues while mounting the SDK UI, make sure you are using the correct package and framework.
</Note>

<View title="JavaScript" icon="js">
  ```js main.js theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { SukiAuthManager } from "@suki-sdk/core";
  import { initialize } from "@suki-sdk/js";

  // replace this with your actual encounter data
  const encounterDetails = {
    identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
    patient: {
      identifier: "905c2521-25eb-4324-9978-724636df3436",
      name: {
        use: "official",
        family: "Doe",
        given: ["John"],
        suffix: ["MD"],
      },
      birthDate: "1990-01-01",
      gender: "Male",
    },
  };

  const authManager = new SukiAuthManager({
    partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
    partnerToken:
      "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
    providerName: "John doe", // Replace with the full name of the provider
    providerOrgId: "1234", // Replace with the provider's organization ID
    environment: "production",
    loginOnInitialize: true,
    providerId,
    providerName,
    providerOrgId,
    providerSpecialty,
  });

  const sdkClient = initialize({
    authManager,
  });

  const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
    if (isInitialized) {
      sdkClient.mount({
        rootElement: document.getElementById("suki-root"), // The root element to mount the SDK into
        encounter: encounterDetails,
      });
    }
  });

  // unsubscribe from the init event when no longer needed
  window.addEventListener("beforeunload", () => {
    unsubscribeInit();
  });
  ```
</View>

<View title="React" icon="react">
  ```jsx ComponentA.jsx theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
  import { useEffect, useMemo } from "react";
  import { SukiAuthManager } from "@suki-sdk/core";
  import { useSuki, SukiAssistant } from "@suki-sdk/react"; // Mount UI: add SukiAssistant

  function ComponentA() {
    const authManager = useMemo(
      () =>
        new SukiAuthManager({
          partnerId: "f80c8db8-a4d0-4b75-8d63-56c82b5413f0", // Replace with your actual partner ID
          partnerToken:
            "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30", // Replace with your actual partner token
          providerName: "John doe", // Replace with the full name of the provider
          providerOrgId: "1234", // Replace with the provider's organization ID
          environment: "production",
          loginOnInitialize: true,
          providerId,
          providerName,
          providerOrgId,
          providerSpecialty,
        }),
      [],
    );

    const { init, isInitialized } = useSuki();

    // replace this with your actual encounter data
    const currentEncounter = {  // Mount UI: encounter for SukiAssistant
      identifier: "6ec3920f-b0b1-499d-a4e9-889bf788e5ab",
      patient: {
        identifier: "905c2521-25eb-4324-9978-724636df3436",
        name: {
          use: "official",
          family: "Doe",
          given: ["John"],
          suffix: ["MD"],
        },
        birthDate: "1990-01-01",
        gender: "Male",
      },
    };

    useEffect(() => {
      if (!isInitialized) {
        init({ authManager });
      }
    }, [init, isInitialized, authManager]);

    return ( //Mount UI: SukiAssistant 
      <SukiAssistant encounter={currentEncounter} />
      // rest of your code
    );
  }
  ```
</View>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to our [Ambient documentation guide](/web-sdk/guides/ambient) to learn more about how to use the Suki Web SDK to create your first ambient session.