TeamPlay

    Installation

    npm
    yarn
    pnpm
    bun
    deno
    npm install teamplay

    TeamPlay can run in three different modes. Pick the one that matches your needs for persistence and synchronization:

    Modes

    • In-memory Mode (default): in-memory only, no server, no persistence across reloads.
    • Offline Mode: client-only with local persistence (browser or React Native), no server.
    • Server Sync Mode: real-time synchronization with a backend server.

    In-memory Mode

    By default, TeamPlay runs in in-memory mode. It keeps everything in memory, so your data is not persisted between page reloads. If you want a client-only setup with local persistence, use the Offline Mode.

    Offline Mode

    Offline Mode persists data locally (browser or React Native) without a server. Use the offline connector:

    import connect from 'teamplay/connect-offline'
await connect({
  idFields: ['_id']
})

    See Offline Mode for details and React Native setup.

    Server Sync Mode

    To sync data with a server, connect from the client somewhere early in your app startup:

    import connect from 'teamplay/connect'

await connect({
  idFields: ['_id']
})

    idFields defaults to ['_id']. Legacy applications that still read doc.id can opt into dual identity fields with idFields: ['_id', 'id']; TeamPlay will inject and protect both top-level fields.

    On the server, create the TeamPlay backend and attach its WebSocket upgrade handler to your Node HTTP server:

    import { createBackend, initConnection } from 'teamplay/server'

const backend = createBackend()
const { upgrade } = initConnection(backend)
server.on('upgrade', upgrade) // Node's 'http' server instance

    Production Setup

    For development, no extra database setup is needed. If MONGO_URL is not set, TeamPlay stores server data in an SQLite file named local.db in the root of your project.

    You can still write MongoDB-style queries and aggregations in this local setup. TeamPlay emulates that query behavior with mingo.

    For production, configure the services your deployment needs:

    • MONGO_URL: use MongoDB instead of the local SQLite file.
    • REDIS_URL: required when you run multiple server instances, so real-time updates can be coordinated through Redis.
    Note

    TeamPlay's createBackend() is a wrapper around creating a ShareDB backend. If you need lower-level control, you can create a ShareDB backend yourself and pass it to initConnection(). ShareDB is re-exported from teamplay/server, so you can import it as import { ShareDB } from 'teamplay/server'.

    Optional ORM Setup

    TeamPlay works without an ORM setup: you can use signals, subscriptions, and real-time sync directly. When your app starts to have named collections such as users, games, orders, or events, the ORM gives you a conventional place to define document schemas, model methods, access rules, and server aggregations.

    To use the full ORM features, follow the ORM Quick Start. It shows the extra setup for the models/ folder, the Babel plugin, and the shared models.setup.ts file used by both client and server.

    Note

    StartupJS apps can skip the manual ORM setup. StartupJS configures model loading and initializes TeamPlay models automatically.

    Now that you have TeamPlay installed and configured, you're ready to start using it in your application!