Using the SDK (document management API)

Here’s how access control works in y-sweet:

1. Your server (i.e. your Next.js server component) connects to y-sweet using an API key and asks for a client token for a specific document.
2. Your server then passes that client token to the client, often as props to a client-side React component.
3. Your client then connects to y-sweet using the client token.

#1 and #2 happen via the document management API. #3 happens on the client, using either the @y-sweet/react package or vanilla JS y-websocket (opens in a new tab) client library.

The client token contains all the information needed for the client to connect to a y-sweet document, so the client doesn’t need any configuration. But you do need to tell your server how to talk to y-sweet, by passing a server token.

A server token combines a URL and a secret key. It can be represented either as a JSON object with url and token as keys, or as a JSONified string of the same. This makes it easy to store the server token in a secret store, and pass it to your server code as an environment variable.

Installing the SDK

In an existing npm app, install @y-sweet/sdk as follows:

npm i @y-sweet/sdk

Example

import { YDocProvider } from '@y-sweet/react'
import { getOrCreateDoc } from '@y-sweet/sdk'
 
type HomeProps = {
    searchParams: Record<string, string>
}
 
export default async function Home({ searchParams }: HomeProps) {
    const clientToken = await getOrCreateDoc(searchParams.doc, process.env.CONNECTION_STRING)
 
    return (
        <YDocProvider clientToken={clientToken} setQueryParam="doc">
            // Call your collaborative interface here
        </YDocProvider>
    )
}