Y-Sweet Quickstart

There are two ways to start a Y-Sweet project:

Using create-y-sweet-app, which sets up everything automatically for you.
Manually installing the dependencies yourself.

Automatic Installation

We recommend creeating your app using create-y-sweet-app. To get started, run:

npx create-y-sweet-app@latest

You’ll be given the following prompts:

What do you want to call your app? (my-y-sweet-app)
What framework do you want to use?

❯ nextjs
  remix

Do you want to install dependencies with npm? (Y/n)
Do you want to initialize a Git repository? (Y/n)

Once you’re finished, create-y-sweet-app will create a project in the given folder.

Manual Installation

You can also create a Y-Sweet project by manually installing the dependencies yourself.

On the client, create a `YSweetProvider`.

First, we need to create a Yjs document and YSweetProvider. For React apps, we can use the @y-sweet/react NPM package, or use @y-sweet/client for any front-end framework.

With the Y-Sweet React library, we’ll start by wrapping our application with a YDocProvider, which takes a docId and authEndpoint. For now, we’ll use /api/auth as the authEndpoint, but we’ll implement the endpoint itself in the next step.

  npm add yjs @y-sweet/react

App.tsx

  import { YDocProvider } from '@y-sweet/react'
 
  export function App() {
    const docId = 'my-doc-id'
    return (
      <YDocProvider docId={docId} authEndpoint="/api/auth">
        <MyCollaborativeApp />
      </YDocProvider>
    )
  }

The YDocProvider lets us use Y-Sweet’s React hooks in our application.

MyCollaborativeApp.tsx

  'use client'
 
  import { useMap } from '@y-sweet/react'
 
  export function MyCollaborativeApp() {
    const sharedToggle = useMap('toggle')
    const isOn = sharedToggle.get('is-on') ?? false
 
    return (
      <button onClick={() => sharedToggle.set('is-on', !isOn)}>
        {isOn ? 'on' : 'off'}
      </button>
    )
  }

On the server, implement the auth endpoint

Next, implement the authEndpoint, which needs to authenticate the user and call getOrCreateDocAndToken() to generate a client token with the Y-Sweet SDK. This can be done in a few lines using React Server Actions (e.g., NextJS). You can also easily implement this using a server framework like ExpressJS or with your meta-framework’s API routes.

When using NextJS with Server Actions, you can pass a server action as the YDocProvider’s authEndpoint prop.

  npm add @y-sweet/sdk

App.tsx

  import { DocumentManager } from '@y-sweet/sdk'
  import { YDocProvider } from '@y-sweet/react'
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  export function App() {
    const docId = 'my-doc-id'
 
    async function getClientToken() {
      'use server'
      // In a production app, this is where you'd authenticate the user
      // and check that they are authorized to access the doc.
      return await manager.getOrCreateDocAndToken(docId)
    }
 
    return (
      <YDocProvider docId={docId} authEndpoint={getClientToken}>
        <MyCollaborativeApp />
      </YDocProvider>
    )
  }

To implement the auth endpoint using a NextJS API Route, create a route that matches the endpoint you provided as the authEndpoint prop. In our example, that’s app/api/auth/route.ts. The endpoint must accept a POST request, create a client token using the docId provided in the body of the request, and return the client token as the body of the response.

  npm add @y-sweet/sdk

app/api/auth/route.ts

  import { DocumentManager } from '@y-sweet/sdk'
  import { NextResponse } from 'next/server'
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  export async function POST(request: Request) {
    // In a production app, this is where you'd authenticate the user
    // and check that they are authorized to access the doc.
    const { docId } = await request.json()
    const clientToken = await manager.getOrCreateDocAndToken(docId)
    return NextResponse.json(clientToken)
  }

To implement the auth endpoint using ExpressJS, add a route that accepts a POST request, creates a client token using the docId provided in the body of the request, and returns the client token as the body of the response.

  npm add @y-sweet/sdk

  import express from 'express'
  import cors from 'cors'
  import { DocumentManager } from '@y-sweet/sdk'
 
  const app = express()
  app.use(cors())
  app.use(express.json())
 
  const manager = new DocumentManager(process.env.CONNECTION_STRING)
 
  app.post('/api/auth', async (req, res) => {
    const docId = req.body?.docId ?? null
    // In a production app, this is where you'd authenticate the user
    // and check that they are authorized to access the doc.
    const clientToken = await manager.getOrCreateDocAndToken(docId)
    res.send(clientToken)
  })
 
  app.listen(8080)

Generate a Connection String

Finally, let’s generate a connection string that we can pass to our backend as the CONNECTION_STRING environment variable.

Create a Y-Sweet service in the Jamsocket dashboard. Then go to your new service’s page and click “New connection string”. Provide a description, click “Create”, and copy the connection string.

If you’re developing with NextJS, you can set the CONNECTION_STRING environment variable in a .env.local file. Or you can prefix your dev command with connection string, e.g. CONNECTION_STRING=yss://... npm run dev.

In a production environment, you can typically use your platform’s dashboard to set environment variables for your application. Check out Vercel’s and Netlify’s docs on environment variables for more information.

Next steps

Build a To-Do List from scratch.
Learn more about the auth endpoint.
Learn more about the connection string.

Overview Color Grid (Next.js)