@jamsocket/server

JavaScript/TypeScript library for spawning session backends server-side.

Installation

npm install @jamsocket/server

Example

Here's an example of how different parts of Jamsocket's client libraries work together.

server.tsx

import Jamsocket from '@jamsocket/server'
 
const jamsocket = Jamsocket.init({
   account: '[YOUR ACCOUNT]',
   token: '[YOUR TOKEN]',
   service: '[YOUR SERVICE]',
   // during develpment, you can simply pass { dev: true }
})
 
const spawnResult = await jamsocket.spawn() // returns an instance of SpawnResult

client.tsx

import {
  SessionBackendProvider, SocketIOProvider,
  useEventListener, useSend, useReady
} from '@jamsocket/socketio'
 
function Root() {
  return(
    <SessionBackendProvider spawnResult={spawnResult}>
      <SocketIOProvider url={spawnResult.url}>
        <MyComponent />
      </SocketIOProvider>
    </SessionBackendProvider>
  )
}
 
function MyComponent() {
  const ready = useReady()
  const sendEvent = useSend()
 
  useEffect(() => {
    if (ready) {
      sendEvent('some-event', someValue)
    }
  }, [ready])
 
  useEventListener('another-event', (args) => {
    // do something when receiving an event message from your session backend...
  })
}

Library Reference

@jamsocket/server

`init()`

Create a Jamsocket instance using the init function from @jamsocket/server folder.

In local development, you can simply set dev to true.

import Jamsocket from '@jamsocket/server'
const jamsocket = Jamsocket.init({ dev: true })

In production, provide your account, token, and service information.

import Jamsocket from '@jamsocket/server'
const jamsocket = Jamsocket.init({
  account: '[YOUR ACCOUNT]',
  token: '[YOUR TOKEN]',
  service: '[YOUR SERVICE]',
})

`spawn()`

The returned Jamsocket instance from init includes a spawn function that you can use to spawn a session backend. You can optionally include a lock, environment variables, and a grace period when you spawn.

💡

Backends should only be spawned server-side, since the Jamsocket Auth Token must be kept secret.

import Jamsocket from '@jamsocket/server'
const jamsocket = Jamsocket.init({
  account: '[YOUR ACCOUNT]',
  token: '[YOUR TOKEN]',
  service: '[YOUR SERVICE]',
})
 
const spawnResult = await jamsocket.spawn({
  lock: 'my-lock', // optional
  env: { MY_ENV_VAR: 'foo' }, // optional
  gracePeriodSeconds: 300, // optional
})

Types

type JamsocketInitOptions =
  | {
      account: string
      token: string
      service: string
      apiUrl?: string
    }
  | {
      dev: true
      port?: number
    }
 
type JamsocketSpawnOptions = {
  lock?: string
  env?: Record<string, string>
  gracePeriodSeconds?: number
}
 
type SpawnResult = {
  url: string
  name: string
  readyUrl: string
  statusUrl: string
  spawned: boolean
}

Troubleshooting @jamsocket/client