ETHNYC Learnings And Action Items

[neekolas]

XMTP just wrapped another ETHGlobal Hackathon, with 27 teams using XMTP in their submissions. You can read more about these amazing apps here.

Every hackathon is a stress test for our SDKs and developer documentation. We need to take developers from having never used XMTP to launching a novel application on our protocol in a matter of hours.

The majority of the feedback for our docs and developer experience was positive. "Everything just worked". "So easy to use". "Your docs are amazing". While that feedback feels nice, it's not very actionable. In this post I want to focus on the times we fell short and hindered developer's success instead of accelerating it.

xmtp-js issues

Viem/Wagmi

By far the most common support request at our booth was around Viem and Wagmi. Today Viem/Wagmi is the most popular set of tools for developers to connect to wallets from the browser, but xmtp-js only accepts ethers.Signer interface compatible objects in our Client.create method.

Our FAQ includes some code snippets on how to adapt Viem/Wagmi to work with xmtp-js. They are copied directly from Lenster's open source implementation, and include references to private Lenster functions that won't work when copied into your app. They also include footguns that will cause the application to crash if the value returned from the hook is used before wallet connection (the use of signature ?? null in signMessage is not a good idea for most applications).

The lack of Viem support has been a known issue for some time and has not been addressed.

Polyfill confusion

Many developers wondered why they had to include a polyfill for Buffer in their application and asked if we could just include the polyfill on their behalf.

RegisterCodecs confusion

In our documentation around custom content types we frequently use client.registerCodec instead of passing the codecs in during Client instantiation. With v11, we lose the benefits of typed clients with this method, and we should update all our docs to use the codecs property when creating the Client.

@xmtp/react-sdk issues

Hard to find documentation

A lot of developers came to our booth asking for more examples of how to use the React SDK. Many of them hadn't seen either xmtp-quickstart-hooks or our React Quickstart example, which are both helpful resources for hackers.

A number of developers complained that they found the documentation for the React Hooks sparse. We don't publish the Typedocs for the React hooks, so developers have to either copy/paste examples or wade into the source code to understand the full functionality of the package. Given we already create Typedocs in Github actions, I think it's just a question of publishing them somewhere more accessible and maybe adding more notes around intended usage.

Confusion with local first cache

Some developers were following our Local First Cache tutorial when ideally they would just be using our React hooks, which are much easier to work with. We do include a reference to the React hooks in the tutorial, but we aren't being particularly aggressive about routing developers to the React SDK

Out of date documentation

The Getting Started documentation for React contains a bug. The return type for startConversation has changed and it now returns an object instead of a conversation, which makes it difficult to use with useStreamMessages below.

React Playground issues

The React Playground had a bug that would cause it to fail when reading messages. We should have at least a baseline level of testing for the playground to ensure that bad changes are caught before getting merged

iOS issues

WalletConnect V2

The biggest blocker for devs using xmtp-ios is the lack of a solid example using WalletConnect V2. Given that v1 has been retired, there is no end-to-end working example app for iOS right now

General issues

There were a few more general things I noticed when working with developers across many different projects

1. We have so many repos it is hard to keep track of all of them, and developers are unsure which repos to pay attention to.
2. Inconsistency between formatting and lint rules between repos. Every repo has slightly different rules for code formatting, which means that code from one repo often cannot be copy/pasted into another. We should consolidate where it makes sense.
3. Inconsistent version dependencies. Some example projects have been upgraded to xmtp-js v11 and some are on v9 or v10. This causes confusion and bugs for developers trying to merge together multiple examples.
4. Inconsistent tsconfig between projects also can prevent code re-use and merging code between examples. Code that works with one tsconfig may not work with another.

Action items

• Consider consolidating secondary front-end repos (React Playground, Content Types, all examples) into the xmtp-web repo to take advantage of its well designed lint/tsconfig settings and release process.
• Consider moving bot-starter into the bot-kit-pro monorepo. We might want to rename the repo to xmtp-node-js or something more broad. It already includes some functions not directly in the scope of bot-kit-pro.
• Audit all documentation on xmtp.org and ensure that the code samples work with the latest version of our SDKs and tools
• Complete WalletConnect V2 integration into xmtp-ios
• Build and lint React Playground
• Add Viem support to xmtp-js
• Consider adding buffer polyfill into xmtp-js when needed
• Mark Local First Cache tutorial as deprecated and push developers to use React SDK
• Publish typedocs for React SDK and promote on xmtp.org
• Once the Viem support in xmtp-js lands we will need to update our documentation to remove references to the Lenster wrapper and instead show users how to pass in a Viem WalletClient

[jhaaaa]

Regarding Publish typedocs for React SDK and promote on xmtp.org - the TypeDocs are published here: https://xmtp.github.io/xmtp-web/modules.html and available through the React SDK README: https://github.com/xmtp/xmtp-web/tree/main/packages/react-sdk#reference-docs

Links to all reference docs were removed from xmtp.org. We'll bring them back! <3

[neekolas]

I totally missed that these were public. That's great.

[jhaaaa]

Here is a PR to address Mark Local First Cache tutorial as deprecated and push developers to use React SDK and Publish typedocs for React SDK and promote on xmtp.org: xmtp/xmtp-dot-org#577

Thank you again for such clear and actionable feedback! <3

[jhaaaa]

Related to Audit all documentation on xmtp.org and ensure that the code samples work with the latest version of our SDKs and tools, coincidentally, as a part of fixing some code tab issues, I just did an audit of missing code samples. I've pasted the info below. Would be great to tackle these as a part of the audit.

Missing code samples

In some cases, the samples just need to be created. But in other cases, the sample may not be applicable or the feature may not have been implemented for the SDK yet.

“Code sample coming soon”

No code sample - not sure if needed, not applicable, or not implemented yet?

React

• Use a read receipt
• Send a broadcast message

Kotlin

• Handle an unsupported content type error
• Listen for new messages in all conversations
• Use a read receipt
• Send a broadcast message

Swift

• Cache the conversation list
• Handle an unsupported content type error
• Send a reply
• Receive a reply
• Listen for new messages in all conversations
• Create a reaction - not implemented, yet - or no code sample?
• Receive a reaction
• Configure the read receipt content type
• Send a read receipt
• Receive a read receipt
• Use a read receipt
• Send a broadcast message

Dart

• Saving keys
• Cache the conversation list
• Serialize/Deserialize conversations
• Handle an unsupported content type error
• Decode a notification envelope
• Listen for new messages in all conversations
• Send a broadcast message

RN

• Cache the conversation list
• Serialize/Deserialize conversations
• Decode a notification envelope
• Handle an unsupported content type error

“Not applicable”

No code sample because feature does not apply to the SDK - correct?

JS

• Serialize/Deserialize conversations
• Decode a notification envelope

React

• Serialize/Deserialize conversations
• Decode a notification envelope

“X… haven’t been implemented yet”

No code sample because content type hasn’t been implemented for SDK yet - correct?

Dart

• Read receipts: import and register
• Read receipts: send a read receipt
• Read receipts: receive read receipt
• Read receipts: use read receipt

RN

• Read receipts: import and register
• Read receipts: send a read receipt
• Read receipts: receive read receipt
• Read receipts: use read receipt