From 21624d7a6670d5ae39b9d35d6b8fe8f21faa1177 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Mon, 21 Aug 2023 15:37:17 -0700 Subject: [PATCH 1/8] firt pass docs for React prod rel --- docs/build/authentication.md | 116 ++++++++---- docs/build/conversations.md | 124 +++++++++++-- docs/build/img/local-first-arch.jpeg | Bin 0 -> 55043 bytes docs/build/local-first.md | 25 +++ docs/build/messages.md | 109 ++++++++++- docs/build/streams.md | 82 ++++++--- docs/content-types/attachment.mdx | 6 + docs/content-types/react-content-types.md | 213 ++++++++++++++++++++++ docs/content-types/reaction.mdx | 6 + docs/content-types/read-receipt.mdx | 6 + docs/content-types/remote-attachment.mdx | 6 + docs/content-types/reply.mdx | 6 + docs/launch/performance.md | 32 ++-- 13 files changed, 637 insertions(+), 94 deletions(-) create mode 100644 docs/build/img/local-first-arch.jpeg create mode 100644 docs/build/local-first.md create mode 100644 docs/content-types/react-content-types.md diff --git a/docs/build/authentication.md b/docs/build/authentication.md index 680d9740e..eb8f12417 100644 --- a/docs/build/authentication.md +++ b/docs/build/authentication.md @@ -14,6 +14,34 @@ The XMTP message API revolves around a network client that allows retrieving a 1. To sign the newly generated key bundle. This happens only the very first time when key bundle is not found in storage. 2. To sign a random salt used to encrypt the key bundle in storage. This happens every time the client is started (including the very first time). +## Add the provider (React SDK only) + +To use the hooks provided by the React SDK, you must wrap your app with an `XMTPProvider`. This gives the hooks access to the XMTP client instance. + +:::info + +There’s only one client instance per provider. + +::: + + + + +```ts +import { XMTPProvider } from "@xmtp/react-sdk"; + +createRoot(document.getElementById("root") as HTMLElement).render( + + + + + , +); +``` + + + + ## Create a client A client is created that requires passing in a connected wallet that implements the [Signer](https://github.com/xmtp/xmtp-js/blob/main/src/types/Signer.ts) interface. @@ -79,19 +107,31 @@ val client = Client().create(account = account, options = options) ```tsx -const { client, error, isLoading, initialize } = useClient(); - -const handleConnect = useCallback(async () => { - await initialize({ signer }); -}, [initialize]); - -if (error) { - return "An error occurred while initializing the client"; -} - -if (isLoading) { - return "Awaiting signatures..."; -} +export const CreateClient: React.FC<{ signer: Signer }> = ({ signer }) => { + const { client, error, isLoading, initialize } = useClient(); + + const handleConnect = useCallback(async () => { + await initialize({ signer }); + }, [initialize]); + + if (error) { + return "An error occurred while initializing the client"; + } + + if (isLoading) { + return "Awaiting signatures..."; + } + + if (!client) { + return ( + + ); + } + + return "Connected to XMTP"; +}; ``` @@ -212,12 +252,26 @@ val client = Client().buildFrom(bundle = keys, options = options) ```tsx import { Client, useClient } from "@xmtp/react-sdk"; - -const { initialize } = useClient(); -// get the keys using a valid Signer -const keys = await Client.getKeys(signer); -// create a client using keys returned from getKeys -await initialize({ keys, signer }); +import type { Signer } from "@xmtp/react-sdk"; + +export const CreateClientWithKeys: React.FC<{ signer: Signer }> = ({ signer }) => { + const { initialize } = useClient(); + + // initialize client on mount + useEffect(() => { + const init = async () => { + // get the keys using a valid Signer + const keys = await Client.getKeys(signer); + // create a client using keys returned from getKeys + await initialize({ keys, signer }); + }; + void init(); + }, []); + + return ( + ... + ); +}; ``` @@ -309,18 +363,18 @@ The `apiUrl`, `keyStoreType`, `codecs`, and `maxContentSize` parameters from the -| Parameter | Default | Description | -| ------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| appVersion | `undefined` | Add a client app version identifier that's included with API requests. **Production apps are strongly encouraged to set this value.**
For example, you can use the following format: `appVersion: APP_NAME + '/' + APP_VERSION`.
Setting this value provides telemetry that shows which apps are using the XMTP client SDK. This information can help XMTP developers provide app support, especially around communicating important SDK updates, including deprecations and required upgrades. | -| env | `dev` | Connect to the specified XMTP network environment. Valid values include `dev`, `production`, or `local`. For important details about working with these environments, see [XMTP `production` and `dev` network environments](#xmtp-production-and-dev-network-environments). | -| apiUrl | `undefined` | Manually specify an API URL to use. If specified, value of `env` will be ignored. | -| keystoreProviders | `[StaticKeystoreProvider, NetworkKeystoreProvider, KeyGeneratorKeystoreProvider]` | Override the default behavior of how the Client creates a Keystore with a custom provider. This can be used to get the user's private keys from a different storage mechanism. | -| persistConversations | `true` | Maintain a cache of previously seen V2 conversations in the storage provider (defaults to `LocalStorage`). | -| skipContactPublishing | `false` | Do not publish the user's contact bundle to the network on Client creation. Designed to be used in cases where the Client session is short-lived (for example, decrypting a push notification), and where it is known that a Client instance has been instantiated with this flag set to false at some point in the past. | -| codecs | `[TextCodec]` | Add codecs to support additional content types. | -| maxContentSize | `100M` | Maximum message content size in bytes. | -| preCreateIdentityCallback | `undefined` | `preCreateIdentityCallback` is a function that will be called immediately before a [Create Identity](/docs/concepts/account-signatures#sign-to-create-an-xmtp-identity) wallet signature is requested from the user. | -| preEnableIdentityCallback | `undefined` | `preEnableIdentityCallback` is a function that will be called immediately before an [Enable Identity](/docs/concepts/account-signatures#sign-to-enable-an-xmtp-identity) wallet signature is requested from the user. | +| Parameter | Default | Description | +| ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| appVersion | undefined | Add a client app version identifier that's included with API requests.
For example, you can use the following format: appVersion: APP_NAME + '/' + APP_VERSION.
Setting this value provides telemetry that shows which apps are using the XMTP client SDK. This information can help XMTP developers provide app support, especially around communicating important SDK updates, including deprecations and required upgrades. | +| env | dev | Connect to the specified XMTP network environment. Valid values include dev, production, or local. For important details about working with these environments, see [XMTP production and dev network environments](https://github.com/xmtp/xmtp-web/blob/main/packages/react-sdk/README.md#xmtp-production-and-dev-network-environments). | +| apiUrl | undefined | Manually specify an API URL to use. If specified, value of env will be ignored. | +| keystoreProviders | [StaticKeystoreProvider, NetworkKeystoreProvider, KeyGeneratorKeystoreProvider] | Override the default behavior of how the client creates a Keystore with a custom provider. This can be used to get the user's private keys from a different storage mechanism. | +| persistConversations | true | Maintain a cache of previously seen V2 conversations in the storage provider (defaults to LocalStorage). | +| skipContactPublishing | false | Do not publish the user's contact bundle to the network on client creation. Designed to be used in cases where the client session is short-lived (for example, decrypting a push notification), and where it is known that a client instance has been instantiated with this flag set to false at some point in the past. | +| codecs | [TextCodec] | Add codecs to support additional content types. | +| maxContentSize | 100M | Maximum message content size in bytes. | +| preCreateIdentityCallback | undefined | preCreateIdentityCallback is a function that will be called immediately before a [Create Identity wallet signature](https://xmtp.org/docs/concepts/account-signatures#sign-to-create-an-xmtp-identity) is requested from the user. | +| preEnableIdentityCallback | undefined | preEnableIdentityCallback is a function that will be called immediately before an [Enable Identity wallet signature](https://xmtp.org/docs/concepts/account-signatures#sign-to-enable-an-xmtp-identity) is requested from the user. | diff --git a/docs/build/conversations.md b/docs/build/conversations.md index 667e12855..2d6e68a15 100644 --- a/docs/build/conversations.md +++ b/docs/build/conversations.md @@ -51,10 +51,43 @@ let canAliceMessageBob = try await client.canMessage(bobClient.address) ```tsx -const { canMessage } = useCanMessage(); -if (await canMessage("0x3F11b27F323b62B159D2642964fa27C46C841897")) { - //Create conversation -} +import { useCanMessage } from "@xmtp/react-sdk"; + +export const CanMessage: React.FC = () => { + const [peerAddress, setPeerAddress] = useState(""); + const [isOnNetwork, setIsOnNetwork] = useState(false); + const [isLoading, setIsLoading] = useState(false); + + const { canMessage } = useCanMessage(); + + const handleAddressChange = useCallback((e: React.KeyboardEvent) => { + setPeerAddress(e.target.value); + }, []); + + const handleCheckAddress = useCallback(async (e: FormEvent) => { + e.preventDefault(); + if (isValidAddress(peerAddress)) { + setIsLoading(true); + setIsOnNetwork(await canMessage(peerAddress)); + setIsLoading(false); + } else { + setIsOnNetwork(false); + } + }; + void checkAddress(); + }, [peerAddress]); + + return ( +
+ +
+ ); +}; ``` @@ -117,11 +150,59 @@ val newConversation = ```tsx -const startConversation = useStartConversation(); -const convv = await startConversation( - "0x3F11b27F323b62B159D2642964fa27C46C841897", - "hi", -); +import { isValidAddress, useStartConversation } from "@xmtp/react-sdk"; +import { useCallback, useState } from "react"; + +export const StartConversation: React.FC = () => { + const [peerAddress, setPeerAddress] = useState(""); + const [message, setMessage] = useState(""); + const [isLoading, setIsLoading] = useState(false); + + const startConversation = useStartConversation(); + + const handleAddressChange = useCallback( + (e: ChangeEvent) => { + setPeerAddress(e.target.value); + }, + [], + ); + + const handleMessageChange = useCallback( + (e: ChangeEvent) => { + setMessage(e.target.value); + }, + [], + ); + + const handleStartConversation = useCallback( + async (e: React.FormEvent) => { + e.preventDefault(); + if (peerAddress && message) { + setIsLoading(true); + const conversation = await startConversation(peerAddress, message); + setIsLoading(false); + } + }, + [message, peerAddress, startConversation], + ); + + return ( +
+ + +
+ ); +}; ``` @@ -199,16 +280,21 @@ for (conversation in allConversations) { ```tsx -const { conversations, error, isLoading } = useConversations(); - -{ - conversations.map((conversation, index) => ( -
- {conversation?.peerAddress}- - {JSON.stringify(conversation.context?.metadata)} -
- )); -} +export const ListConversations: React.FC = () => { + const { conversations, error, isLoading } = useConversations(); + + if (error) { + return "An error occurred while loading conversations"; + } + + if (isLoading) { + return "Loading conversations..."; + } + + return ( + ... + ); +}; ``` diff --git a/docs/build/img/local-first-arch.jpeg b/docs/build/img/local-first-arch.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..a3ea3327bff61c16b1d2babff5fb0a97a89bf25b GIT binary patch literal 55043 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 literal 0 HcmV?d00001 diff --git a/docs/build/local-first.md b/docs/build/local-first.md new file mode 100644 index 000000000..fcf19db02 --- /dev/null +++ b/docs/build/local-first.md @@ -0,0 +1,25 @@ +--- +sidebar_label: Local-first cache +sidebar_position: 1.5 +description: "Get started building apps with XMTP." +--- + +# Use local-first architecture + +If you're building a production-grade app, be sure to use a local-first architecture to help you build a performant app. Using this local-first architecture, the client prioritizes using the local cache on the device where it’s running. + +For example, use the XMTP SDK to initially retrieve existing message data from the XMTP network and place it in the local cache. Asynchronously load new and updated message data as needed. Build your app to get message data from the local cache. + +Here’s an overview of how your app frontend, local cache, client SDK, and the XMTP network work together in this local-first approach: + +import localfirst from '/docs/build/img/local-first-arch.jpeg'; + + + +- When building a web app with the [React SDK](https://github.com/xmtp/xmtp-web/tree/main/packages/react-sdk), the local-first architecture is automatically provided by the SDK. + +- When building a web app with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js), you can use the browser `localStorage` as the local cache to store encrypted data, decrypting data each time before display. + +- When building native iOS and Android mobile apps, you can use the device's encrypted container as the local cache to store decrypted data. + +For more performance best practices, see [Optimize performance of your app](/docs/launch/performance) diff --git a/docs/build/messages.md b/docs/build/messages.md index 44a1fc851..3bc9ce40e 100644 --- a/docs/build/messages.md +++ b/docs/build/messages.md @@ -59,10 +59,93 @@ conversation.send(text = "Hello world") ```tsx import { useSendMessage } from "@xmtp/react-sdk"; +import type { Conversation } from "@xmtp/react-sdk"; +import { useCallback, useState } from "react"; -const sendMessage = useSendMessage(conversation); +export const SendMessage: React.FC<{ conversation: CachedConversation }> = ({ + conversation, +}) => { + const [peerAddress, setPeerAddress] = useState(""); + const [message, setMessage] = useState(""); + const [isSending, setIsSending] = useState(false); + const sendMessage = useSendMessage(); + + const handleAddressChange = useCallback( + (e: ChangeEvent) => { + setPeerAddress(e.target.value); + }, + [], + ); + + const handleMessageChange = useCallback( + (e: ChangeEvent) => { + setMessage(e.target.value); + }, + [], + ); + + const handleSendMessage = useCallback( + async (e: React.FormEvent) => { + e.preventDefault(); + if (peerAddress && isValidAddress(peerAddress) && message) { + setIsLoading(true); + await sendMessage(conversation, message); + setIsLoading(false); + } + }, + [message, peerAddress, sendMessage], + ); + + return ( +

+ + +
+ ); +}; +``` + +### Optimistic sending with React + +When a user sends a message with XMTP, they might experience a slight delay between sending the message and seeing their sent message display in their app UI. + +This is because when a user sends a message, they typically have to wait for the XMTP network to finish processing the message before the app can display it in the UI. + +The local-first architecture of the React SDK automatically includes optimistic sending to immediately display the sent message in the sender’s UI while processing the message in the background. This provides the user with immediate feedback and enables them to continue messaging without having to wait for their previous message to finish processing. + +Messages that are in the sending state will have a `true` value for their `isSending` property. + +### Handle messages that fail to send with React + +If a message fails to complete the sending process, you must provide an error state that alerts the user and enables them to either resend the message or cancel sending the message. + +While in this unsent state, the message remains in its original location in the user’s conversation flow, with any newer sent and received messages displaying after it. -await sendMessage(message); +If the user chooses to resend the message, the message moves into the most recently sent message position in the conversation. Once it successfully sends, it remains in that position. + +If the user chooses to cancel sending the message, the message is removed from the conversation flow. + +Messages that fail to send will have the `hasSendError` property set to `true`. + +#### Resend a failed message + +Use the `resendMessage` function from the `useResendMessage` hook to resend a failed message. + +```tsx +const { resendMessage } = useResendMessage(); + +// resend the message +resendMessage(failedMessage); ``` @@ -129,15 +212,25 @@ for (conversation in client.conversations.list()) { ```tsx import { useMessages } from "@xmtp/react-sdk"; +import type { CachedConversation } from "@xmtp/react-sdk"; -const [conversation, setConversation] = useState(null); -const { messages } = useMessages(conversation); +export const Messages: React.FC<{ + conversation: CachedConversation; +}> = ({ conversation }) => { + const { error, messages, isLoading } = useMessages(conversation); -useEffect(() => { - if (messages) { - console.log("Loaded message history:", messages.length); + if (error) { + return "An error occurred while loading messages"; } -}, [messages]); + + if (isLoading) { + return "Loading messages..."; + } + + return ( + ... + ); +}; ``` diff --git a/docs/build/streams.md b/docs/build/streams.md index 677237d27..20f320796 100644 --- a/docs/build/streams.md +++ b/docs/build/streams.md @@ -73,25 +73,33 @@ client.conversations.stream().collect { ```tsx -//The `useStreamConversations` hook listens for new conversations in real-time and calls the passed callback when a new conversation is created. It also exposes an error state. - import { useCallback, useState } from "react"; import { useStreamConversations } from "@xmtp/react-sdk"; +import type { Conversation } from "@xmtp/react-sdk"; + +export const NewConversations: React.FC = () => { + // track streamed conversations + const [streamedConversations, setStreamedConversations] = useState< + Conversation[] + >([]); + + // callback to handle incoming conversations + const onConversation = useCallback( + (conversation: Conversation) => { + setStreamedConversations((prev) => [...prev, conversation]); + }, + [], + ); + const { error } = useStreamConversations(onConversation); -// track streamed conversations -const [streamedConversations, setStreamedConversations] = useState< - Conversation[] ->([]); - -// callback to handle incoming conversations -const onConversation = useCallback((conversation: Conversation) => { - setStreamedConversations((prev) => [...prev, conversation]); -}, []); -const { error } = useStreamConversations(onConversation); + if (error) { + return "An error occurred while streaming conversations"; + } -if (error) { - return "An error occurred while streaming conversations"; -} + return ( + ... + ); +}; ``` @@ -181,15 +189,40 @@ conversation.streamMessages().collect { ```tsx +// The useStreamMessages hook streams new conversation messages on mount +// and exposes an error state. import { useStreamMessages } from "@xmtp/react-sdk"; +import type { CachedConversation, DecodedMessage } from "@xmtp/react-sdk"; +import { useCallback, useEffect, useState } from "react"; + +export const StreamMessages: React.FC<{ + conversation: CachedConversation; +}> = ({ + conversation, +}) => { + // track streamed messages + const [streamedMessages, setStreamedMessages] = useState( + [], + ); -const onMessage = useCallback((message) => { - setHistory((prevMessages) => { - const msgsnew = [...prevMessages, message]; - return msgsnew; - }); -}, []); -useStreamMessages(conversation, onMessage); + // callback to handle incoming messages + const onMessage = useCallback( + (message: DecodedMessage) => { + setStreamedMessages((prev) => [...prev, message]); + }, + [streamedMessages], + ); + + useStreamMessages(conversation, onMessage); + + useEffect(() => { + setStreamedMessages([]); + }, [conversation]); + + return ( + ... + ); +}; ``` @@ -236,8 +269,13 @@ for await (const message of await xmtp.conversations.streamAllMessages()) { ```tsx +// The useStreamAllMessages hook streams new messages from all conversations +// on mount and exposes an error state. import { useStreamAllMessages } from "@xmtp/react-sdk"; +import type { DecodedMessage } from "@xmtp/react-sdk"; +import { useCallback, useState } from "react"; +export const StreamAllMessages: React.FC = () => { // track streamed messages const [streamedMessages, setStreamedMessages] = useState( [], diff --git a/docs/content-types/attachment.mdx b/docs/content-types/attachment.mdx index 8d0b8f3f7..3c3a31cbf 100644 --- a/docs/content-types/attachment.mdx +++ b/docs/content-types/attachment.mdx @@ -18,6 +18,12 @@ You are welcome to provide feedback on this implementation by commenting on the ::: +:::info Attachments with React + +To learn how to use the attachment content type with the React SDK, see [Handle content types with the React SDK](/docs/content-types/react-content-types). + +::: + ### Install the package diff --git a/docs/content-types/react-content-types.md b/docs/content-types/react-content-types.md new file mode 100644 index 000000000..05c8e94e9 --- /dev/null +++ b/docs/content-types/react-content-types.md @@ -0,0 +1,213 @@ +--- +sidebar_label: For React +sidebar_position: 1.5 +--- + +# Handle content types with the React SDK + +As the ecosystem of apps built with XMTP grows exponentially, so will the number of available content types. + +All apps built with an XMTP client SDK automatically support the plain text standard content type. However, there are other content types that you can choose to support. + +These include standards-track content types and custom content types. + +To learn more about content types, see [Content types with XMTP](https://xmtp.org/docs/concepts/content-types). + +## Standards-track content types + +Standards-track content types are proposals being actively reviewed for adoption as standard content types through the XMTP Improvement Proposal (XIP) process. Once a content type has been adopted as a standard, it is included in the XMTP client SDKs. Apps can use an SDK to automatically handle the new standard content types. + +Here are some examples of standards-track content types that you can review, test, and adopt in your app today: + +### Remote attachments + +This content type supports sending file attachments that are stored off-network. Use it to enable your app to send and receive message attachments. + +- [XIP proposal discussion](https://github.com/xmtp/XIPs/blob/main/XIPs/xip-17-remote-attachment-content-type-proposal.md) + +- [Source code](https://github.com/xmtp/xmtp-js-content-types/tree/main/packages/content-type-remote-attachment) + +### Replies + +This content type supports direct replies to messages. + +- [XIP idea discussion](https://github.com/orgs/xmtp/discussions/35) + +- [Source code](https://github.com/xmtp/xmtp-js-content-types/tree/main/packages/content-type-reply) + +### Reactions + +This content type supports reactions to messages. + +- [XIP idea discussion](https://github.com/orgs/xmtp/discussions/36) + +- [Source code](https://github.com/xmtp/xmtp-js-content-types/tree/main/packages/content-type-reaction) + +### Read receipts + +This content type supports read receipts to messages + +- [XIP idea discussion](https://github.com/orgs/xmtp/discussions/43) + +- [Source code](https://github.com/xmtp/xmtp-js-content-types/tree/main/packages/content-type-read-receipt) + +## Integrate standards-track content types with the React SDK + +The React SDK supports all current standards-track content types, but only text messages are enabled out of the box. Adding support for other standards-track content types requires a bit of configuration. + +```tsx +import { + XMTPProvider, + attachmentContentTypeConfig, + reactionContentTypeConfig, + readReceiptContentTypeConfig, + replyContentTypeConfig, +} from "@xmtp/react-sdk"; + +const contentTypeConfigs = [ + attachmentContentTypeConfig, + reactionContentTypeConfig, + readReceiptContentTypeConfig, + replyContentTypeConfig, +]; + +createRoot(document.getElementById("root") as HTMLElement).render( + + + + + , +); +``` + +## Custom content types + +On the other hand, custom content types are those that an app chooses to use in its implementation, but which are not standards and are not being actively reviewed as standards-track content types. + +When your app encounters a custom content type, you can: + +- Choose to adopt the custom content type if you think it is a good fit for your app. +- Update your app to gracefully handle the unsupported content type. +- Ignore it + +### Integrate custom content types with the React SDK + +> **Note** +> This part of the React SDK is still under active development and may change in the future. + +To support a custom content type, you must create a content type configuration to integrate with the [local-first architecture](https://github.com/xmtp/xmtp-web/blob/main/packages/react-sdk/README.md#local-first-architecture). There are five possible options in a content type configuration, and two are required. They are outlined below. + +**Namespace (required)** + +This must be specified and unique to all other content type namespaces. + +**Message processors (required)** + +Processing a message as it arrives from the XMTP network is a key aspect of the local-first architecture. It determines if and how a message is cached locally. + +**Codecs (required)** + +All custom content types require at least one codec. + +**Schema (optional)** + +When working with some content types, you may want to cache data in a separate table. This option allows you to specify a new Dexie table schema. + +**Validators (optional)** + +Content validators help to ensure that custom content type messages are in the correct format and can be processed properly. + +**Example configuration** + +```tsx +import type { ContentCodec } from "@xmtp/xmtp-js"; + +const MyContentType = new ContentTypeId({ + authorityId: "mydomain.com", + typeId: "myContentType", + versionMajor: 1, + versionMinor: 0, +}); + +class MyContentTypeCodec implements ContentCodec { ... }; + +export const myCustomContentTypeConfiguration = { + namespace: "MyContentType", + codecs: [new MyContentTypeCodec()], + processors: { + [MyContentType.toString()]: [processMyContentType], + }, + validators: { + [MyContentType.toString()]: validateMyContentType, + }, +}; +``` + +### Send custom content type messages + +The `useSendMessage` hook supports custom content types. Pass in the content type as the third parameter as shown in the example below. + +```tsx +import { useCallback, useState } from "react"; +import { useSendMessage } from "@xmtp/react-sdk"; +import type { Conversation } from "@xmtp/react-sdk"; +import type { Reaction } from "@xmtp/content-type-reaction"; +import { ContentTypeReaction } from "@xmtp/content-type-reaction"; + +export const SendCustomContentTypeMessage: React.FC<{ + conversation: CachedConversation; +}> = ({ conversation }) => { + const [isSending, setIsSending] = useState(false); + const sendMessage = useSendMessage(); + + const handleSendMessage = useCallback( + async (e: React.FormEvent) => { + e.preventDefault(); + setIsLoading(true); + // send custom content type + await sendMessage( + conversation, + { + action: "added", + content: "👍", + reference: "", + schema: "unicode", + } as Reaction, + ContentTypeReaction, + ); + setIsLoading(false); + }, + [message, peerAddress, sendMessage], + ); + + return ( +
+ +
+ ); +}; +``` + +## Handle unsupported content types + +Messages that contain unsupported content types are stored in the local cache, but are not processed. The `content` property of an unsupported message will be `undefined`. Each time a client is initialized, any messages that were previously unprocessed because their content type was unsupported at the time, will attempt to be reprocessed. + +If you wish to display an unsupported content type, there’s a `contentFallback` property that may include a useful string. However, it is recommended that you manually process unsupported content types. + +**Example** + +```ts +import { ContentTypeId } from "@xmtp/xmtp-js"; +import { ContentTypeAttachment } from "@xmtp/content-type-remote-attachment"; + +const MessageContent = ({ message }) => { + if ( + message.content === undefined && + ContentTypeId.fromString(message.contentType).sameAs(ContentTypeAttachment) + ) { + return "This message contains an attachment, which is not supported by this client."; + } +}; +``` diff --git a/docs/content-types/reaction.mdx b/docs/content-types/reaction.mdx index 1a5b20d81..d9e6d8997 100644 --- a/docs/content-types/reaction.mdx +++ b/docs/content-types/reaction.mdx @@ -18,6 +18,12 @@ You are welcome to provide feedback on this implementation by commenting on the ::: +:::info Reactions with React + +To learn how to use the reaction content type with the React SDK, see [Handle content types with the React SDK](/docs/content-types/react-content-types). + +::: + ### Install the package diff --git a/docs/content-types/read-receipt.mdx b/docs/content-types/read-receipt.mdx index 32735228e..1bd786881 100644 --- a/docs/content-types/read-receipt.mdx +++ b/docs/content-types/read-receipt.mdx @@ -18,6 +18,12 @@ You are welcome to provide feedback on this implementation by commenting on the ::: +:::info Read receipts with React + +To learn how to use the read receipt content type with the React SDK, see [Handle content types with the React SDK](/docs/content-types/react-content-types). + +::: + ### Install the package diff --git a/docs/content-types/remote-attachment.mdx b/docs/content-types/remote-attachment.mdx index 96d675f9e..1599bc731 100644 --- a/docs/content-types/remote-attachment.mdx +++ b/docs/content-types/remote-attachment.mdx @@ -18,6 +18,12 @@ You are welcome to provide feedback on this implementation by commenting on the ::: +:::info Remote attachments with React + +To learn how to use the remote attachment content type with the React SDK, see [Handle content types with the React SDK](/docs/content-types/react-content-types). + +::: + ### Install the package diff --git a/docs/content-types/reply.mdx b/docs/content-types/reply.mdx index 017e40b49..3a4a8abf1 100644 --- a/docs/content-types/reply.mdx +++ b/docs/content-types/reply.mdx @@ -18,6 +18,12 @@ You are welcome to provide feedback on this implementation by commenting on the ::: +:::info Replies with React + +To learn how to use the reply content type with the React SDK, see [Handle content types with the React SDK](/docs/content-types/react-content-types). + +::: + ### Install the package Use the following commands to install the package: diff --git a/docs/launch/performance.md b/docs/launch/performance.md index cd3f227ac..fe07ed1a4 100644 --- a/docs/launch/performance.md +++ b/docs/launch/performance.md @@ -14,19 +14,7 @@ Follow these guidelines to optimize your app’s performance. To learn about tes ## Use a local cache -If you're building a production-grade app, be sure to use an architecture that includes a local cache backed by an XMTP SDK. - - - -Use the XMTP SDK to initially retrieve existing message data from the XMTP network and place it in the local cache. Asynchronously load new and updated message data as needed. - -Build your app to get message data from the local cache. - -For example, use the XMTP SDK to get conversation lists from the XMTP network. Store the conversation lists in the local cache. Build your app to get conversation lists from the local cache. - -When building native iOS and Android mobile apps, you can use the device's encrypted container as the local cache to store decrypted data. - -When building web apps, you can use the browser `localStorage` as the local cache to store **encrypted** data, decrypting data each time before display. +To learn more, see [Use local-first architecture](/docs/build/local-first). ## Cache the conversation list @@ -39,7 +27,6 @@ To learn more, see [Cache the conversation list](/docs/build/conversations#cache Serialize securely stored `DecodedMessage` histories, avoiding the need to download and decrypt the same message on every session. - Use the JavaScript client SDK (`xmtp-js`) to [serialize securely stored decoded message histories](https://github.com/xmtp/xmtp-js/releases/tag/v8.0.0) -- With the React client SDK (`react-sdk`), use message caching with the `useCachedMessages` hook ## Page through messages @@ -91,6 +78,23 @@ conversation.send( ) ``` + + + +Message content can be optionally compressed using the `compression` option. The value of the option is the name of the compression algorithm to use. Currently supported are `gzip` and `deflate`. Compression is applied to the bytes produced by the content codec. + +Content will be decompressed transparently on the receiving end. Note that `Client` enforces maximum content size. The default limit can be overridden through the `ClientOptions`. Consequently, a message that would expand beyond that limit on the receiving end will fail to decode. + +```tsx +import { Compression, ContentTypeText } from '@xmtp/react-sdk' + +const sendMessage = useSendMessage(); + +await sendMessage(conversation, '#'.repeat(1000), ContentTypeText, { + compression: Compression.COMPRESSION_DEFLATE, +}) +``` + From bfba0efbae76fedea583902a630ab8732c8bed22 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Mon, 21 Aug 2023 16:09:31 -0700 Subject: [PATCH 2/8] updates to local db doc --- docs/launch/local-db.md | 68 ++++++++++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 25 deletions(-) diff --git a/docs/launch/local-db.md b/docs/launch/local-db.md index a89d56998..b806263dd 100644 --- a/docs/launch/local-db.md +++ b/docs/launch/local-db.md @@ -1,37 +1,49 @@ --- sidebar_label: Local DB sidebar_position: 1 -description: Managing Local Data with Dexie in a React Application +description: Manage local data with Dexie in a web app built with the xmtp-js SDK --- -# Managing Local Data with Dexie in a React Application +# Manage local data with Dexie in a web app built with xmtp-js -The performance of a web application can be significantly improved by leveraging local data storage. Particularly in the context of loading messages, using a local database can result in a 10x performance increase compared to solely relying on a network-based data source. + -This guide provides a walkthrough on managing local data storage in a React application using the Dexie.js library. Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. + + + + +The performance of a web app can be significantly improved by leveraging local data storage. Particularly in the context of loading messages, using a local database can result in a 10x performance increase compared to solely relying on a network-based data source. + +This guide provides a walkthrough on managing local data storage in a web application built with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js) and using the Dexie.js library. Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. import ReactPlayer from 'react-player' -#### Experimental Playground 🎲 +#### Experimental playground 🎲 + + For hands-on experience, check out the React Playground. -[GitHub repo](https://github.com/xmtp/xmtp-react-playground) | [Live Version](https://xmtp.github.io/xmtp-react-playground/#/new). +[GitHub repo](https://github.com/xmtp/xmtp-react-playground) | [Live version](https://xmtp.github.io/xmtp-react-playground/#/new) -## Step 1: Installing Libraries +## Step 1: Install libraries To start, install the necessary libraries: + + ```bash npm install dexie dexie-react-hooks ``` -## Step 2: Defining the Database Schema +## Step 2: Define the database schema Create a **`DB.ts`** file and define your database schema. Here's an example of a potential database schema: + + :::success This file defines the local database schema for our app. Any time we show any @@ -150,11 +162,11 @@ export default db; In this schema, we define interfaces for different types of data we want to store: conversations, messages, message attachments, and message reactions. We then create a class for the database that extends Dexie, and within that class, we define the tables and their structure. -## Step 3: Database Operations +## Step 3: Perform database operations After defining the schema, you can perform various database operations such as adding, updating, and retrieving data. -### Adding Messages +### Add messages When a new message is sent, it's first saved to the local database before being sent to the network. @@ -177,7 +189,7 @@ const message: Message = { message.id = await db.messages.add(message); ``` -### Updating Messages +### Update messages After a message is sent to the network and you receive the decoded message back, update the original message in the database with the ID of the message on the network and set **`isSending`** to false. @@ -190,7 +202,7 @@ await db.messages.update(message.id!, { }); ``` -### Checking for Existing Messages +### Check for existing messages Before saving a received message, check if it already exists in the database. If the message doesn't exist, save it; otherwise, skip the saving process. @@ -202,7 +214,7 @@ const existing = await db.messages .first(); ``` -### Finding a Conversation +### Find a conversation When you need to find a specific conversation in the **`conversations`** table, search by the `topic` field. @@ -214,7 +226,7 @@ return await db.conversations .first(); ``` -### Updating a Conversation +### Update a conversation When a new message is received, update the `updatedAt` timestamp of the related conversation. @@ -228,7 +240,7 @@ if (conversation && conversation.updatedAt < updatedAt) { } ``` -### Adding Conversations +### Add conversations When a new conversation is started, it's first saved to the local database. @@ -248,7 +260,7 @@ const conversation: Conversation = { conversation.id = await db.conversations.add(conversation); ``` -### Checking for Existing Conversations +### Check for existing conversations Before saving a new conversation, check if it already exists in the database. If the conversation doesn't exist, save it; otherwise, return the existing one. @@ -260,11 +272,13 @@ const existing = await db.conversations .first(); ``` -## Step 4: Load Initial Data +## Step 4: Load initial data To load initial data when the application starts, use the **`useConversations`** function. This function fetches conversations from an XMTP client, saves these conversations to the local database (if they're not already stored), and returns an array of all conversations. -### Use Effect Hook to Fetch and Save Conversations +### Use useEffect hook to fetch and save conversations + + Start by using React's **`useEffect`** hook to run an asynchronous operation when the component mounts. This operation should fetch the list of conversations from the client, and for each conversation, save it to the local database and fetch and save the latest message for the conversation: @@ -288,7 +302,7 @@ useEffect(() => { }, []); ``` -### Define Functions to Save Conversations and Messages +### Define functions to save conversations and messages Next, define two functions: **`saveConversation`** and **`saveMessage`**. These functions should take an XMTP conversation or message as an argument, check if it already exists in the local database, and if it doesn't, save it to the database: @@ -329,7 +343,9 @@ async function saveMessage( } ``` -### Use Effect Hook to Stream Conversations +### Use useEffect hook to stream conversations + + Use another **`useEffect`** hook to listen for new conversations in real-time. As new conversations come in, save them to the local database: @@ -344,7 +360,7 @@ useEffect(() => { }, []); ``` -### Fetch Conversations from Local DB +### Fetch conversations from local DB Finally, return the conversations from the local database: @@ -356,11 +372,13 @@ return ( ); ``` + + This hook, **`useLiveQuery`**, automatically re-renders the component whenever the data in the local database changes. It is used to fetch all conversations from the database, sort them in reverse order by their updated time, and return the result. If the query returns nothing, an empty array is returned by default. By loading initial data, you ensure that your application loads instantly on each refresh without crashes and slow loading spinners. -## Step 5: Preventing Race Conditions +## Step 5: Prevent race conditions Race conditions can occur when multiple operations that read from and write to the same database area are executed in close sequence, leading to inconsistent data. To prevent race conditions, use a mutex (short for "mutual exclusion object"), which ensures that only one operation can happen at a time. @@ -383,7 +401,7 @@ const conversationMutex = new Mutex(); Now, we can use these mutexes to ensure that only one operation happens at a time. Here are some examples of how to use a mutex: -### When Updating a Conversation +### When updating a conversation Wrap the database operation within the **`runExclusive`** method of the mutex instance. This guarantees that no other operation can happen until the current operation is finished: @@ -397,7 +415,7 @@ if (conversation && conversation.updatedAt < updatedAt) { } ``` -### When Saving a Conversation +### When saving a conversation The same applies when saving a new conversation. The operation is wrapped in the **`runExclusive`** method: @@ -428,4 +446,4 @@ Using a mutex in this way helps prevent race conditions and maintain the integri Managing local data storage in a React application can be complex. However, with Dexie.js and the right strategies for handling database operations, it can be much more manageable. Always remember to handle potential errors and race conditions to ensure the integrity of your data. Now that you've learned these steps, consider trying them out in your own projects. Happy coding! -- For more information on using Dexie.js, check out the **[official documentation](https://dexie.org/docs/Tutorial/Getting-started)**. +For more information on using Dexie.js, check out the **[official documentation](https://dexie.org/docs/Tutorial/Getting-started)**. From b9ac1267589c3655fa8a39f552074fd649194b5d Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 06:20:16 -0700 Subject: [PATCH 3/8] inc ry's feedback <3 --- docs/build/conversations.md | 1 + docs/build/local-first.md | 311 ++++++++++++++++++++++++- docs/launch/local-db.md | 449 ------------------------------------ 3 files changed, 311 insertions(+), 450 deletions(-) delete mode 100644 docs/launch/local-db.md diff --git a/docs/build/conversations.md b/docs/build/conversations.md index 2d6e68a15..90d105d12 100644 --- a/docs/build/conversations.md +++ b/docs/build/conversations.md @@ -281,6 +281,7 @@ for (conversation in allConversations) { ```tsx export const ListConversations: React.FC = () => { + const { initialize } = useClient(); const { conversations, error, isLoading } = useConversations(); if (error) { diff --git a/docs/build/local-first.md b/docs/build/local-first.md index fcf19db02..eca501e7c 100644 --- a/docs/build/local-first.md +++ b/docs/build/local-first.md @@ -1,7 +1,7 @@ --- sidebar_label: Local-first cache sidebar_position: 1.5 -description: "Get started building apps with XMTP." +description: "If you're building a production-grade app, be sure to use a local-first architecture to help you build a performant app." --- # Use local-first architecture @@ -23,3 +23,312 @@ import localfirst from '/docs/build/img/local-first-arch.jpeg'; - When building native iOS and Android mobile apps, you can use the device's encrypted container as the local cache to store decrypted data. For more performance best practices, see [Optimize performance of your app](/docs/launch/performance) + +## Manage local data with Dexie in a web app built with `xmtp-js` + +The performance of a web app can be significantly improved by leveraging local data storage. Particularly in the context of loading messages, using a local cache can result in a 10x performance increase compared to solely relying on a network-based data source. + +This guide provides a walkthrough on managing local data storage in a web app built with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js) and using the Dexie.js library. Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. + +import ReactPlayer from 'react-player' + +#### Experimental playground 🎲 + +For a hands-on experience, check out the React Playground, built with the xmtp-js SDK: + +[GitHub repo](https://github.com/xmtp/xmtp-react-playground) | [Live version](https://xmtp.github.io/xmtp-react-playground/#/new) + + + +### Step 1: Install libraries + +To start, install the necessary libraries: + +```bash +npm install dexie dexie-react-hooks +``` + +### Step 2: Define the database schema + +Create a `DB.ts` file and define your database schema. Here's an example of a potential database schema: + +:::tip + +This file defines the local database schema for our app. Any time we show any +data in the UI, it should come from the database. + +::: + +```tsx +import Dexie from "dexie"; + +// Define a conversation interface +export interface Conversation { + id?: number; + topic: string; + title: string | undefined; + createdAt: Date; + updatedAt: Date; + isGroup: boolean; + peerAddress: string; + groupMembers?: string[] | undefined; +} + +// Define a message interface +export interface Message { + id?: number; + inReplyToID: string; + conversationTopic: string; + xmtpID: string; + senderAddress: string; + sentByMe: boolean; + sentAt: Date; + contentType: { + authorityId: string; + typeId: string; + versionMajor: number; + versionMinor: number; + }; + content: any; + metadata?: { [key: string]: [value: string] }; + isSending: boolean; +} + +// Define a message attachment interface +export interface MessageAttachment { + id?: number; + messageID: number; + filename: string; + mimeType: string; + data: Uint8Array; +} + +// Define a message reaction interface +export interface MessageReaction { + id?: number; + reactor: string; + messageXMTPID: string; + name: string; +} + +// Create a class for the database +class DB extends Dexie { + // Define tables for the database + conversations!: Dexie.Table; + messages!: Dexie.Table; + attachments!: Dexie.Table; + reactions!: Dexie.Table; + + constructor() { + super("DB"); + this.version(2).stores({ + // Define the structure and indexes for each table + conversations: ` + ++id, + topic, + title, + createdAt, + updatedAt, + isGroup, + groupMembers, + peerAddress + `, + messages: ` + ++id, + [conversationTopic+inReplyToID], + inReplyToID, + conversationTopic, + xmtpID, + senderAddress, + sentByMe, + sentAt, + contentType, + content + `, + attachments: ` + ++id, + messageID, + filename, + mimeType, + data + `, + reactions: ` + ++id, + [messageXMTPID+reactor+name], + messageXMTPID, + reactor, + name + `, + }); + } +} + +// Initialize the database and export it +const db = new DB(); +export default db; +``` + +In this schema, we define interfaces for different types of data we want to store: conversations, messages, message attachments, and message reactions. We then create a class for the database that extends Dexie, and within that class, we define the tables and their structure. + +### Step 3: Perform database operations + +After defining the schema, you can perform various database operations such as adding, updating, and retrieving data. + +#### Add messages + +When a new message is sent, it's first saved to the local database before being sent to the network. + +```jsx +// Create a new message +const message: Message = { + //Properties + conversationTopic: stripTopicName(conversation.topic), + inReplyToID: "", + xmtpID: "PENDING-" + new Date().toString(), + senderAddress: client.address, + sentByMe: true, + sentAt: new Date(), + contentType: { ...contentType }, + content: content, + isSending: true, +}; + +// Save the message to the database and get its ID +message.id = await db.messages.add(message); +``` + +#### Update messages + +After a message is sent to the network and you receive the decoded message back, update the original message in the database with the ID of the message on the network and set `isSending` to false. + +```jsx +// Update the message in the database +await db.messages.update(message.id!, { + xmtpID: decodedMessage.id, + sentAt: decodedMessage.sent, + isSending: false, +}); +``` + +#### Check for existing messages + +Before saving a received message, check if it already exists in the database. If the message doesn't exist, save it; otherwise, skip the saving process. + +```jsx +// Check if the message already exists in the database +const existing = await db.messages + .where("xmtpID") + .equals(decodedMessage.id) + .first(); +``` + +#### Find a conversation + +When you need to find a specific conversation in the `conversations` table, search by the `topic` field. + +```jsx +// Find a conversation by topic +return await db.conversations + .where("topic") + .equals(stripTopicName(topic)) + .first(); +``` + +#### Update a conversation + +When a new message is received, update the `updatedAt` timestamp of the related conversation. + +```jsx +// Check if the conversation needs to be updated +if (conversation && conversation.updatedAt < updatedAt) { + // If it does, update the updatedAt timestamp + await conversationMutex.runExclusive(async () => { + await db.conversations.update(conversation, { updatedAt }); + }); +} +``` + +#### Add conversations + +When a new conversation is started, it's first saved to the local database. + +```jsx +// Create a new conversation +const conversation: Conversation = { + /* conversation properties */ + topic: stripTopicName(xmtpConversation.topic), + title: undefined, + createdAt: xmtpConversation.createdAt, + updatedAt: xmtpConversation.createdAt, + isGroup: xmtpConversation.isGroup, + peerAddress: xmtpConversation.peerAddress, +}; + +// Save the conversation to the database and get its ID +conversation.id = await db.conversations.add(conversation); +``` + +#### Check for existing conversations + +Before saving a new conversation, check if it already exists in the database. If the conversation doesn't exist, save it; otherwise, return the existing one. + +```jsx +// Check if the conversation already exists in the database +const existing = await db.conversations + .where("topic") + .equals(stripTopicName(xmtpConversation.topic)) + .first(); +``` + +### Step 4: Load initial data + + + +To load initial data when the application starts, use the `useConversations` function. This function fetches conversations from an XMTP client, saves these conversations to the local database (if they're not already stored), and returns an array of all conversations. + +#### Define functions to save conversations and messages + +Next, define two functions: `saveConversation` and `saveMessage`. These functions should take an XMTP conversation or message as an argument, check if it already exists in the local database, and if it doesn't, save it to the database: + +```jsx +async function saveConversation(xmtpConversation: ConversationType) { + const existing = await db.conversations + .where("topic") + .equals(stripTopicName(xmtpConversation.topic)) + .first(); + if (!existing) { + const conversation: Conversation = { + /* conversation properties */ + }; + conversation.id = await db.conversations.add(conversation); + return conversation; + } + return existing; +} + +async function saveMessage( + client: XMTP.Client, + conversation: Conversation, + xmtpMessage: XMTP.Message, +) { + const decodedMessage = await client.messages.decode(xmtpMessage); + const existing = await db.messages + .where("xmtpID") + .equals(decodedMessage.id) + .first(); + if (!existing) { + const message: Message = { + /* message properties */ + }; + message.id = await db.messages.add(message); + return message; + } + return existing; +} +``` + +### Conclusion + +Managing local data storage in a web app can be complex. However, with Dexie.js and the right strategies for handling database operations, it can be much more manageable. Always remember to handle potential errors and race conditions to ensure the integrity of your data. Now that you've learned these steps, consider trying them out in your own projects. Happy coding! + +For more information about using Dexie.js, check out the **[official documentation](https://dexie.org/docs/Tutorial/Getting-started)**. diff --git a/docs/launch/local-db.md b/docs/launch/local-db.md deleted file mode 100644 index b806263dd..000000000 --- a/docs/launch/local-db.md +++ /dev/null @@ -1,449 +0,0 @@ ---- -sidebar_label: Local DB -sidebar_position: 1 -description: Manage local data with Dexie in a web app built with the xmtp-js SDK ---- - -# Manage local data with Dexie in a web app built with xmtp-js - - - - - - - -The performance of a web app can be significantly improved by leveraging local data storage. Particularly in the context of loading messages, using a local database can result in a 10x performance increase compared to solely relying on a network-based data source. - -This guide provides a walkthrough on managing local data storage in a web application built with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js) and using the Dexie.js library. Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. - -import ReactPlayer from 'react-player' - -#### Experimental playground 🎲 - - - -For hands-on experience, check out the React Playground. - -[GitHub repo](https://github.com/xmtp/xmtp-react-playground) | [Live version](https://xmtp.github.io/xmtp-react-playground/#/new) - - - -## Step 1: Install libraries - -To start, install the necessary libraries: - - - -```bash -npm install dexie dexie-react-hooks -``` - -## Step 2: Define the database schema - -Create a **`DB.ts`** file and define your database schema. Here's an example of a potential database schema: - - - -:::success - -This file defines the local database schema for our app. Any time we show any -data in the UI, it should come from the database. - -::: - -```tsx -import Dexie from "dexie"; - -// Define a conversation interface -export interface Conversation { - id?: number; - topic: string; - title: string | undefined; - createdAt: Date; - updatedAt: Date; - isGroup: boolean; - peerAddress: string; - groupMembers?: string[] | undefined; -} - -// Define a message interface -export interface Message { - id?: number; - inReplyToID: string; - conversationTopic: string; - xmtpID: string; - senderAddress: string; - sentByMe: boolean; - sentAt: Date; - contentType: { - authorityId: string; - typeId: string; - versionMajor: number; - versionMinor: number; - }; - content: any; - metadata?: { [key: string]: [value: string] }; - isSending: boolean; -} - -// Define a message attachment interface -export interface MessageAttachment { - id?: number; - messageID: number; - filename: string; - mimeType: string; - data: Uint8Array; -} - -// Define a message reaction interface -export interface MessageReaction { - id?: number; - reactor: string; - messageXMTPID: string; - name: string; -} - -// Create a class for the database -class DB extends Dexie { - // Define tables for the database - conversations!: Dexie.Table; - messages!: Dexie.Table; - attachments!: Dexie.Table; - reactions!: Dexie.Table; - - constructor() { - super("DB"); - this.version(2).stores({ - // Define the structure and indexes for each table - conversations: ` - ++id, - topic, - title, - createdAt, - updatedAt, - isGroup, - groupMembers, - peerAddress - `, - messages: ` - ++id, - [conversationTopic+inReplyToID], - inReplyToID, - conversationTopic, - xmtpID, - senderAddress, - sentByMe, - sentAt, - contentType, - content - `, - attachments: ` - ++id, - messageID, - filename, - mimeType, - data - `, - reactions: ` - ++id, - [messageXMTPID+reactor+name], - messageXMTPID, - reactor, - name - `, - }); - } -} - -// Initialize the database and export it -const db = new DB(); -export default db; -``` - -In this schema, we define interfaces for different types of data we want to store: conversations, messages, message attachments, and message reactions. We then create a class for the database that extends Dexie, and within that class, we define the tables and their structure. - -## Step 3: Perform database operations - -After defining the schema, you can perform various database operations such as adding, updating, and retrieving data. - -### Add messages - -When a new message is sent, it's first saved to the local database before being sent to the network. - -```jsx -// Create a new message -const message: Message = { - //Properties - conversationTopic: stripTopicName(conversation.topic), - inReplyToID: "", - xmtpID: "PENDING-" + new Date().toString(), - senderAddress: client.address, - sentByMe: true, - sentAt: new Date(), - contentType: { ...contentType }, - content: content, - isSending: true, -}; - -// Save the message to the database and get its ID -message.id = await db.messages.add(message); -``` - -### Update messages - -After a message is sent to the network and you receive the decoded message back, update the original message in the database with the ID of the message on the network and set **`isSending`** to false. - -```jsx -// Update the message in the database -await db.messages.update(message.id!, { - xmtpID: decodedMessage.id, - sentAt: decodedMessage.sent, - isSending: false, -}); -``` - -### Check for existing messages - -Before saving a received message, check if it already exists in the database. If the message doesn't exist, save it; otherwise, skip the saving process. - -```jsx -// Check if the message already exists in the database -const existing = await db.messages - .where("xmtpID") - .equals(decodedMessage.id) - .first(); -``` - -### Find a conversation - -When you need to find a specific conversation in the **`conversations`** table, search by the `topic` field. - -```jsx -// Find a conversation by topic -return await db.conversations - .where("topic") - .equals(stripTopicName(topic)) - .first(); -``` - -### Update a conversation - -When a new message is received, update the `updatedAt` timestamp of the related conversation. - -```jsx -// Check if the conversation needs to be updated -if (conversation && conversation.updatedAt < updatedAt) { - // If it does, update the updatedAt timestamp - await conversationMutex.runExclusive(async () => { - await db.conversations.update(conversation, { updatedAt }); - }); -} -``` - -### Add conversations - -When a new conversation is started, it's first saved to the local database. - -```jsx -// Create a new conversation -const conversation: Conversation = { - /* conversation properties */ - topic: stripTopicName(xmtpConversation.topic), - title: undefined, - createdAt: xmtpConversation.createdAt, - updatedAt: xmtpConversation.createdAt, - isGroup: xmtpConversation.isGroup, - peerAddress: xmtpConversation.peerAddress, -}; - -// Save the conversation to the database and get its ID -conversation.id = await db.conversations.add(conversation); -``` - -### Check for existing conversations - -Before saving a new conversation, check if it already exists in the database. If the conversation doesn't exist, save it; otherwise, return the existing one. - -```jsx -// Check if the conversation already exists in the database -const existing = await db.conversations - .where("topic") - .equals(stripTopicName(xmtpConversation.topic)) - .first(); -``` - -## Step 4: Load initial data - -To load initial data when the application starts, use the **`useConversations`** function. This function fetches conversations from an XMTP client, saves these conversations to the local database (if they're not already stored), and returns an array of all conversations. - -### Use useEffect hook to fetch and save conversations - - - -Start by using React's **`useEffect`** hook to run an asynchronous operation when the component mounts. This operation should fetch the list of conversations from the client, and for each conversation, save it to the local database and fetch and save the latest message for the conversation: - -```jsx -useEffect(() => { - (async () => { - if (!client) return; - for (const xmtpConversation of await client.conversations.list()) { - const conversation = await saveConversation(xmtpConversation); - const latestMessage = ( - await xmtpConversation.messages({ - direction: XMTP.SortDirection.SORT_DIRECTION_DESCENDING, - limit: 1, - }) - )[0]; - if (latestMessage) { - await saveMessage(client, conversation, latestMessage); - } - } - })(); -}, []); -``` - -### Define functions to save conversations and messages - -Next, define two functions: **`saveConversation`** and **`saveMessage`**. These functions should take an XMTP conversation or message as an argument, check if it already exists in the local database, and if it doesn't, save it to the database: - -```jsx -async function saveConversation(xmtpConversation: ConversationType) { - const existing = await db.conversations - .where("topic") - .equals(stripTopicName(xmtpConversation.topic)) - .first(); - if (!existing) { - const conversation: Conversation = { - /* conversation properties */ - }; - conversation.id = await db.conversations.add(conversation); - return conversation; - } - return existing; -} - -async function saveMessage( - client: XMTP.Client, - conversation: Conversation, - xmtpMessage: XMTP.Message, -) { - const decodedMessage = await client.messages.decode(xmtpMessage); - const existing = await db.messages - .where("xmtpID") - .equals(decodedMessage.id) - .first(); - if (!existing) { - const message: Message = { - /* message properties */ - }; - message.id = await db.messages.add(message); - return message; - } - return existing; -} -``` - -### Use useEffect hook to stream conversations - - - -Use another **`useEffect`** hook to listen for new conversations in real-time. As new conversations come in, save them to the local database: - -```jsx -useEffect(() => { - (async () => { - if (!client) return; - for await (const conversation of await client.conversations.stream()) { - await saveConversation(conversation); - } - })(); -}, []); -``` - -### Fetch conversations from local DB - -Finally, return the conversations from the local database: - -```jsx -return ( - useLiveQuery(async () => { - return await db.conversations.reverse().sortBy("updatedAt"); - }) || [] -); -``` - - - -This hook, **`useLiveQuery`**, automatically re-renders the component whenever the data in the local database changes. It is used to fetch all conversations from the database, sort them in reverse order by their updated time, and return the result. If the query returns nothing, an empty array is returned by default. - -By loading initial data, you ensure that your application loads instantly on each refresh without crashes and slow loading spinners. - -## Step 5: Prevent race conditions - -Race conditions can occur when multiple operations that read from and write to the same database area are executed in close sequence, leading to inconsistent data. To prevent race conditions, use a mutex (short for "mutual exclusion object"), which ensures that only one operation can happen at a time. - -First, install the necessary library: - -```bash -npm install async-mutex -``` - -Then, import and initialize a mutex in your script: - -```jsx -// Import the Mutex class from the async-mutex library -import { Mutex } from "async-mutex"; - -// Initialize a mutex for messages and conversations -const messageMutex = new Mutex(); -const conversationMutex = new Mutex(); -``` - -Now, we can use these mutexes to ensure that only one operation happens at a time. Here are some examples of how to use a mutex: - -### When updating a conversation - -Wrap the database operation within the **`runExclusive`** method of the mutex instance. This guarantees that no other operation can happen until the current operation is finished: - -```jsx -// Check if the conversation needs to be updated -if (conversation && conversation.updatedAt < updatedAt) { - // If it does, update the updatedAt timestamp - await conversationMutex.runExclusive(async () => { - await db.conversations.update(conversation, { updatedAt }); - }); -} -``` - -### When saving a conversation - -The same applies when saving a new conversation. The operation is wrapped in the **`runExclusive`** method: - -```jsx -// Save the conversation to the database -return await conversationMutex.runExclusive(async () => { - // Check if the conversation already exists in the database - const existing = await db.conversations - .where("topic") - .equals(stripTopicName(xmtpConversation.topic)) - .first(); - - // If it doesn't exist, create a new conversation and save it to the database - if (!existing) { - const conversation: Conversation = { - /* conversation properties */ - }; - conversation.id = await db.conversations.add(conversation); - } - - return existing || conversation; -}); -``` - -Using a mutex in this way helps prevent race conditions and maintain the integrity of your data. - -## Conclusion - -Managing local data storage in a React application can be complex. However, with Dexie.js and the right strategies for handling database operations, it can be much more manageable. Always remember to handle potential errors and race conditions to ensure the integrity of your data. Now that you've learned these steps, consider trying them out in your own projects. Happy coding! - -For more information on using Dexie.js, check out the **[official documentation](https://dexie.org/docs/Tutorial/Getting-started)**. From b4a12edbfefcebc3736a9bbc86f61f3c37b2c1e1 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 06:40:56 -0700 Subject: [PATCH 4/8] update changelog --- docs/build/local-first.md | 9 +++++---- docs/changelog.md | 9 +++++++++ 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/docs/build/local-first.md b/docs/build/local-first.md index eca501e7c..0eeff8fd2 100644 --- a/docs/build/local-first.md +++ b/docs/build/local-first.md @@ -18,17 +18,17 @@ import localfirst from '/docs/build/img/local-first-arch.jpeg'; - When building a web app with the [React SDK](https://github.com/xmtp/xmtp-web/tree/main/packages/react-sdk), the local-first architecture is automatically provided by the SDK. -- When building a web app with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js), you can use the browser `localStorage` as the local cache to store encrypted data, decrypting data each time before display. +- When building a web app with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js), you can use the browser `localStorage` as the local cache to store encrypted data, decrypting data each time before display. You might also consider [using Dexie to manage your web app's local data](#manage-local-data-with-dexie-in-a-web-app-built-with-xmtp-js). - When building native iOS and Android mobile apps, you can use the device's encrypted container as the local cache to store decrypted data. For more performance best practices, see [Optimize performance of your app](/docs/launch/performance) -## Manage local data with Dexie in a web app built with `xmtp-js` +## Manage local data with Dexie in a web app built with xmtp-js The performance of a web app can be significantly improved by leveraging local data storage. Particularly in the context of loading messages, using a local cache can result in a 10x performance increase compared to solely relying on a network-based data source. -This guide provides a walkthrough on managing local data storage in a web app built with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js) and using the Dexie.js library. Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. +This guide provides a walkthrough on managing local data storage using the Dexie.js library in a web app built with the [xmtp-js SDK](https://github.com/xmtp/xmtp-js). Dexie.js is a minimalistic wrapper for IndexedDB, which is a low-level API for client-side storage of significant amounts of structured data. import ReactPlayer from 'react-player' @@ -39,6 +39,7 @@ For a hands-on experience, check out the React Playground, built with the xmtp-j [GitHub repo](https://github.com/xmtp/xmtp-react-playground) | [Live version](https://xmtp.github.io/xmtp-react-playground/#/new) +
### Step 1: Install libraries @@ -331,4 +332,4 @@ async function saveMessage( Managing local data storage in a web app can be complex. However, with Dexie.js and the right strategies for handling database operations, it can be much more manageable. Always remember to handle potential errors and race conditions to ensure the integrity of your data. Now that you've learned these steps, consider trying them out in your own projects. Happy coding! -For more information about using Dexie.js, check out the **[official documentation](https://dexie.org/docs/Tutorial/Getting-started)**. +To learn more aboutDexie.js, see [Getting Started with Dexie.js](https://dexie.org/docs/Tutorial/Getting-started). diff --git a/docs/changelog.md b/docs/changelog.md index 0e54f7491..d2a253638 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -10,6 +10,15 @@ This changelog provides information about release milestones for XMTP SDKs, deve --- +#### Aug 2023 + +## [React client SDK](https://github.com/xmtp/xmtp-web/tree/main/packages/react-sdk) v1.0.0 is Production Ready + +This release delivers local-first architecture, optimistic sending, and support for standards-track content types via configuration. **[Read the release notes](https://github.com/xmtp/xmtp-web/releases/tag/%40xmtp%2Freact-sdk%401.0.0 +)** (Aug 22) + +--- + #### July 2023 ## [React Native client SDK](https://github.com/xmtp/xmtp-react-native) is in Beta (xmtp-react-native) From 427bbbdee4a7c735adc8e05d59b97246c6cc24ec Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 06:57:35 -0700 Subject: [PATCH 5/8] fix local first diagram --- docs/build/img/local-first-arch.jpeg | Bin 55043 -> 54782 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/docs/build/img/local-first-arch.jpeg b/docs/build/img/local-first-arch.jpeg index a3ea3327bff61c16b1d2babff5fb0a97a89bf25b..c9e411ad1c5cedc22d5b9a5046c9ee5f5bd77166 100644 GIT binary patch literal 54782 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 From fd81f83427bf10f5585ebc951ef4b8396001ffcf Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 07:07:08 -0700 Subject: [PATCH 6/8] fix code location --- docs/build/conversations.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/build/conversations.md b/docs/build/conversations.md index 90d105d12..6ace28905 100644 --- a/docs/build/conversations.md +++ b/docs/build/conversations.md @@ -281,7 +281,6 @@ for (conversation in allConversations) { ```tsx export const ListConversations: React.FC = () => { - const { initialize } = useClient(); const { conversations, error, isLoading } = useConversations(); if (error) { @@ -345,7 +344,8 @@ val client.importConversation(conversations) -```jsx +```tsx +const { initialize } = useClient(); const options = { persistConversations: false, }; From f9e4c72234b86506c99008fb5e6188e54e46a436 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 07:14:23 -0700 Subject: [PATCH 7/8] update callout style --- docs/content-types/react-content-types.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/content-types/react-content-types.md b/docs/content-types/react-content-types.md index 05c8e94e9..8c2037730 100644 --- a/docs/content-types/react-content-types.md +++ b/docs/content-types/react-content-types.md @@ -92,8 +92,11 @@ When your app encounters a custom content type, you can: ### Integrate custom content types with the React SDK -> **Note** -> This part of the React SDK is still under active development and may change in the future. +:::caution + +This part of the React SDK is still under active development and may change in the future. + +::: To support a custom content type, you must create a content type configuration to integrate with the [local-first architecture](https://github.com/xmtp/xmtp-web/blob/main/packages/react-sdk/README.md#local-first-architecture). There are five possible options in a content type configuration, and two are required. They are outlined below. From 984dc33330c10783486d6e592f8b3e346caef592 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa <5481259+jhaaaa@users.noreply.github.com> Date: Tue, 22 Aug 2023 08:04:15 -0700 Subject: [PATCH 8/8] edits from ry <3 --- docs/build/attachments.md | 4 +--- docs/build/local-first.md | 12 +--------- docs/build/messages.md | 27 ----------------------- docs/content-types/react-content-types.md | 2 +- docs/content-types/remote-attachment.mdx | 4 +--- 5 files changed, 4 insertions(+), 45 deletions(-) diff --git a/docs/build/attachments.md b/docs/build/attachments.md index b9c906529..681e7a8e8 100644 --- a/docs/build/attachments.md +++ b/docs/build/attachments.md @@ -46,11 +46,9 @@ xmtp.registerCodec(new RemoteAttachmentCodec()); ### Create an attachment object - + ```tsx -const arrayBuffer = await file.arrayBuffer(); - // Local file details const attachment = { filename: filename, diff --git a/docs/build/local-first.md b/docs/build/local-first.md index 0eeff8fd2..70ed95ac1 100644 --- a/docs/build/local-first.md +++ b/docs/build/local-first.md @@ -70,9 +70,6 @@ export interface Conversation { title: string | undefined; createdAt: Date; updatedAt: Date; - isGroup: boolean; - peerAddress: string; - groupMembers?: string[] | undefined; } // Define a message interface @@ -130,9 +127,6 @@ class DB extends Dexie { title, createdAt, updatedAt, - isGroup, - groupMembers, - peerAddress `, messages: ` ++id, @@ -243,9 +237,7 @@ When a new message is received, update the `updatedAt` timestamp of the related // Check if the conversation needs to be updated if (conversation && conversation.updatedAt < updatedAt) { // If it does, update the updatedAt timestamp - await conversationMutex.runExclusive(async () => { - await db.conversations.update(conversation, { updatedAt }); - }); + await db.conversations.update(conversation, { updatedAt }); } ``` @@ -261,8 +253,6 @@ const conversation: Conversation = { title: undefined, createdAt: xmtpConversation.createdAt, updatedAt: xmtpConversation.createdAt, - isGroup: xmtpConversation.isGroup, - peerAddress: xmtpConversation.peerAddress, }; // Save the conversation to the database and get its ID diff --git a/docs/build/messages.md b/docs/build/messages.md index 3bc9ce40e..6db3ee0ea 100644 --- a/docs/build/messages.md +++ b/docs/build/messages.md @@ -309,33 +309,6 @@ val messages = conversation.messages(limit = 25) val nextPage = conversation.messages(limit = 25, before = messages[0].sent) ``` - - - -```tsx -import { useMessages } from "@xmtp/react-sdk"; - -const { error, isLoading, messages, next } = useMessages( - conversation, - options: { - limit: 20, - }, -); -const handleClick = useCallback(() => { - // fetch next page of messages - next(); -}, [next]); - - -return ( - - - -); -``` - diff --git a/docs/content-types/react-content-types.md b/docs/content-types/react-content-types.md index 8c2037730..eb81ced90 100644 --- a/docs/content-types/react-content-types.md +++ b/docs/content-types/react-content-types.md @@ -1,5 +1,5 @@ --- -sidebar_label: For React +sidebar_label: React SDK sidebar_position: 1.5 --- diff --git a/docs/content-types/remote-attachment.mdx b/docs/content-types/remote-attachment.mdx index 1599bc731..6a4c9b81a 100644 --- a/docs/content-types/remote-attachment.mdx +++ b/docs/content-types/remote-attachment.mdx @@ -59,11 +59,9 @@ xmtp.registerCodec(new RemoteAttachmentCodec()); ### Create an attachment object - + ```tsx -const arrayBuffer = await file.arrayBuffer(); - // Local file details const attachment = { filename: filename,