Giter VIP home page Giter VIP logo

partykit's Introduction

image

npm beta Discord License

PartyKit is a platform designed for creating real-time collaborative applications.

Whether you wish to augment your existing applications or make new ones from scratch, PartyKit makes the task easier with minimal coding effort.

Quick start

You can create a PartyKit project by running:

npm create partykit@latest

This will ask a few questions about your project and create a new directory with a PartyKit application, that includes as server and a client. From inside the directory, you can then run npm run dev to start the development server. When you'reready, you can deploy your application on to the PartyKit cloud with npm run deploy.

From scratch

The fundamental components of a PartyKit application are the server and the client. The server is a JavaScript module exporting an object that defines how your server behaves, primarily in response to WebSocket events. The client connects to this server and listens for these events.

For a quick demonstration, we will create a server that sends a welcome message to the client upon connection to a room. Then, we will set up a client to listen for this message.

First, install PartyKit through npm:

npm install partykit@beta partysocket@beta

Then, let's create our server:

// server.ts
export default {
  // This function is called when a client connects to the server.
  async onConnect(connection, room, context) {
    // You can send messages to the client using the connection object
    connection.send("hello from room: " + room.id);
    console.log(`Connection URL: ${context.request.url}`);

    // You can also listen for messages from the client
    connection.addEventListener("message", (evt) => {
      console.log(evt.data, connection.id); // "hello from client (id)"

      // You can also broadcast messages to all clients in the room
      room.broadcast(
        `message from client: ${evt.data} (id: ${connection.id}")`,
        // You can exclude any clients from the broadcast
        [connection.id] // in this case, we exclude the client that sent the message
      );
    });
  },
  // optionally, you can respond to HTTP requests as well
  async onRequest(request, room) {
    return new Response("hello from room: " + room.id);
  },
};

To start the server for local development, run:

npx partykit dev server.ts

When you're ready to go live, deploy your application to the cloud using:

npx partykit deploy server.ts --name my-party

You can add further configuration including passing variables, substituting expressions, and more with a partykit.json file. For example:

{
  "name": "my-cool-partykit-project",
  "main": "server.ts", // path to the server file
  "vars": {
    // variables to pass to the server
    // these can be accessed in the server under `room.env`
    "MY_VAR": "my-value" // access with `room.env.MY_VAR`
    // You can also pass vars with the CLI --var flag
    // For example, `npx partykit dev server.ts --var MY_VAR=my-value`
  },
  "define": {
    // substitute expressions
    // for example, you can use this to pass the room name to the server
    "process.env.MAGIC_NUMBER": "42" // all instances of `process.env.MAGIC_NUMBER` in the server will be replaced with `42`
    // You can also pass defines with the CLI --define flag
    // For example, `npx partykit dev server.ts --define process.env.MAGIC_NUMBER=42`
  }
}

See more details in the reference docs.

Next, connect your application to this server with a simple client:

// Import PartySocket - a lightweight abstraction over WebSocket
// that handles resilence, reconnection, and message buffering
import PartySocket from "partysocket";

const socket = new PartySocket({
  host: "localhost:1999", // for local development
  // host: "my-party.username.partykit.dev", // for production
  room: "my-room",
});

socket.addEventListener("message", (evt) => {
  console.log(evt.data); // "hello from room: my-room"
});

// You can also send messages to the server
socket.send("hello from client");

Configure your bundler/server of choice to serve the client code (like vite, next.js etc). Alternately, use PartyKit's inbuild serving/bundling capabilities.

Serve and bundle Static assets

You can serve static assets (like html, css, js, images) from PartyKit. Keep them in a directory (say ./public), and pass --serve public to the dev/deploy commands. These assets will be served from the root of your domain. You can also compile and bundle your client code with configuration. For example, in your partykit.json file:

{
  // ...
  "serve": {
    "path": "public",
    "build": "path/to/client.ts"
  }
}

See additional configuration that you can pass to serve and serve.build in the reference docs.

Libraries

y-partykit

y-partykit is an addon library for partykit designed to host backends for Yjs, a high-performance library of data structures for building collaborative software. You can set up a Yjs backend with just a few lines of code:

// server.ts
import { onConnect } from "y-partykit";

export default {
  async onConnect(conn, room, context) {
    return onConnect(conn, room);
  },
};

You can pass additional options for more complex backends:

// server.ts
import { onConnect } from "y-partykit";

export default {
  async onConnect(conn, room, context) {
    return await onConnect(conn, room, {
      // experimental: persist the document to partykit's room storage
      persist: true,

      // Or, you can load/save to your own database or storage
      load() {
        // load a document from a database, or some remote resource
        // and return a Y.Doc instance here (or null if no document exists)
      },
      callback: {
        async handler(yDoc) {
          // called every few seconds after edits
          // you can use this to write to a database
          // or some external storage
        },
        // control how often handler is called with these options
        debounceWait: 10000, // default: 2000 ms
        debounceMaxWait: 20000, // default: 10000 ms
        timeout: 5000, // default: 5000 ms
      },
    });
  },
};

Then, use the provider to connect to this server from your client:

import YPartyKitProvider from "y-partykit/provider";
import * as Y from "yjs";

const yDoc = new Y.Doc();

const provider = new YPartyKitProvider(
  "localhost:1999",
  "my-document-name",
  yDoc
);

You can add additional options to the provider:

// ...
const provider = new YPartyKitProvider(
  "localhost:1999",
  "my-document-name",
  yDoc,
  {
    connect: false, // don't connect immediately, use provider.connect() when required
    params: { token: "my-secret-token" }, // adds to the query string of the websocket connection
    awareness: new awarenessProtocol.Awareness(yDoc), // use your own Yjs awareness instance
  }
);

Refer to the official Yjs documentation for more information. Examples provided in the Yjs documentation should work seamlessly with y-partykit (ensure to replace y-websocket with y-partykit/provider).

Contributing

We encourage contributions to PartyKit. If you're interested in contributing or need help or have questions, please join us in our Discord.

License

PartyKit is MIT licensed.

partykit's People

Contributors

threepointone avatar jevakallio avatar mellson avatar sylwiavargas avatar iojcde avatar dependabot[bot] avatar anmolm96 avatar andarist avatar tom-sherman avatar trysound avatar aweary avatar ericlewis avatar joshuakgoldberg avatar yousefed avatar turkerdev avatar

Stargazers

Wade avatar Ramy al-Sharif avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.