Create an XMTP client
Create an XMTP client that can use the signing capabilities provided by the signer. This signer links the client to the appropriate EOA or SCW.
🎥 walkthrough: Create a client
This video provides a walkthrough of creating a client, covering the key ideas discussed in this doc. After watching, feel free to continue reading for more details.
Create a client
import { Client, type Signer } from "@xmtp/browser-sdk";
// create a signer
const signer: Signer = { /* ... */ };
/**
* The database encryption key is optional but strongly recommended for
* secure local storage of the database.
*
* This value must be consistent when creating a client with an existing
* database.
*/
const dbEncryptionKey = window.crypto.getRandomValues(new Uint8Array(32));
const client = await Client.create(
signer,
// client options
{
dbEncryptionKey,
},
);
When an app first calls Client.create()
, a client creates a local database to manage messaging between the app and the network. In subsequent calls, it loads the existing database. The database is encrypted using the key provided when creating the client.
To learn more about database operations, see the XMTP MLS protocol spec.
Configure an XMTP client
You can configure an XMTP client with these options passed to Client.create
:
import type { ContentCodec } from "@xmtp/content-type-primitives";
type ClientOptions = {
/**
* Specify which XMTP environment to connect to. (default: `dev`)
*/
env?: "local" | "dev" | "production";
/**
* apiUrl can be used to override the `env` flag and connect to a
* specific endpoint
*/
apiUrl?: string;
/**
* historySyncUrl can be used to override the `env` flag and connect to a
* specific endpoint for syncing history
*/
historySyncUrl?: string;
/**
* Allow configuring codecs for additional content types
*/
codecs?: ContentCodec[];
/**
* Path to the local DB
*/
dbPath?: string;
/**
* Encryption key for the local DB
*/
dbEncryptionKey?: Uint8Array;
/**
* Enable structured JSON logging
*/
structuredLogging?: boolean;
/**
* Enable performance metrics
*/
performanceLogging?: boolean;
/**
* Logging level
*/
loggingLevel?: "off" | "error" | "warn" | "info" | "debug" | "trace";
/**
* Disable automatic registration when creating a client
*/
disableAutoRegister?: boolean;
};
XMTP network environments
XMTP provides developer and production network environments. These networks are completely separate and not interchangeable.
For example, an XMTP identity on the developer network is completely distinct from the XMTP identity on the production network, as are the messages associated with these identities. In addition, XMTP identities and messages created on the developer network can't be accessed from or moved to the production network, and vice versa.
The production network is configured to store messages indefinitely. XMTP may occasionally delete messages and identities from the developer network, and will provide advance notice in the XMTP Community Forums.
You can also use a local network to have a client communicate with an XMTP node you are running locally.
During development, it's highly recommended to use a local network environment for speed and reliability.
Build an existing client
Build, or resume, an existing client that's logged in and has an existing local database.
import { Client, type Identifier } from "@xmtp/browser-sdk";
const identifier: Identifier = {
identifier: "0x1234567890abcdef1234567890abcdef12345678",
identifierKind: "Ethereum",
};
const client = await Client.build(identifier, options);
Log out a client
When you log a user out of your app, you can give them the option to delete their local database.
/**
* The Browser SDK client does not currently support deleting the local database.
*/
// this method only terminates the client's associated web worker
client.close();