JavaScript SDK

Reference integration flow for games and wrappers.

The JavaScript SDK is the current reference implementation for Persistly. Use it first when you want the intended client behavior and contract mapping.

Status

This is the reference SDK for the first public Persistly release.

The JavaScript SDK is the current behavior reference for all other SDK tracks.

Create, load, and sync always return canonical save payloads from the server.

Conflict responses preserve the canonical server save so the game can decide how to recover.

The SDK validates payload-size limits before requests leave the client.

Install

Use the published JavaScript package as the default integration path.

npm install @persistly/sdk-js

Repository

The public JavaScript repository is the release-facing source of truth.

https://github.com/persistly/persistly-sdk-js

Example

Create, load, and sync with explicit runtime configuration.

import { PersistlyClient, PersistlySyncStatus } from "@persistly/sdk-js";

const client = new PersistlyClient({
  runtimeKey: process.env.PERSISTLY_RUNTIME_KEY!,
});

const created = await client.createSave({
  externalUserId: "player-184",
  metadata: {
    characterName: "Ayla",
    slotLabel: "Mage"
  },
  state: {
    checkpoint: "vault",
    coins: 418
  }
});

const reloaded = await client.loadSave(created.saveId);

const result = await client.syncSave(created.saveId, {
  baseVersion: reloaded.version,
  metadata: reloaded.metadata,
  state: {
    checkpoint: "vault",
    coins: 612
  }
});

if (result.status === PersistlySyncStatus.Conflict) {
  console.error("Conflict. Canonical server save:", result.save);
}

Common Mistakes

These are the integration errors most likely to create bad product assumptions.

Do not use externalUserId as a public runtime lookup key from shipped clients.

Do not treat runtime keys as privileged admin secrets.

Do not invent slot_id semantics at the platform layer; put save-selection labels in metadata instead.

Do not ignore canonical sync responses. Replace your local canonical snapshot after every create, load, or sync.

Do not sync every frame or use Persistly for real-time PvP state.