@liveblocks/node
provides you with Node.js APIs for
authenticating Liveblocks users and for
implementing webhook handlers. This library is only intended
for use in your Node.js back end.
The Liveblocks
client is new in 1.2, and offers access to our REST API.
To authorize your users with Liveblocks, you have the choice between two different APIs.
Liveblocks.prepareSession
is recommended for most
applications.Liveblocks.identifyUser
is best if you’re using fine-grained
permissions with our REST API.The purpose of this API is to help you implement your custom authentication back
end (i.e. the server part of the diagram). You use the
liveblocks.prepareSession()
API if you’d like to issue
access tokens from your back end.
To implement your back end, follow these steps:
Session
The userId
(required) is an identifier to uniquely identifies
your user with Liveblocks. This value will be used when counting
unique MAUs in your Liveblocks dashboard.
The userInfo
(optional) is any custom JSON value, which can be
attached to static metadata to this user’s session. This will be
publicly visible to all other people in the room. Useful for
metadata like the user’s full name, or their avatar URL.
Finally, authorize the session. This step makes the HTTP call to the Liveblocks servers. Liveblocks will return a signed access token that you can return to your client.
Here’s a real-world example of access tokens in a Next.js route handler/endpoint. You can find examples for other frameworks in our authentication section.
The purpose of this API is to help you implement your custom authentication back
end (i.e. the server part of the diagram). You use the
liveblocks.identifyUser()
API if you’d like to issue
ID tokens from your back end. An ID token
does not grant any permissions in the token directly. Instead, it only securely
identifies your user, and then uses any permissions set via the Permissions
REST API to decide whether to allow the user on a room-by-room basis.
Use this approach if you’d like Liveblocks to be the source of truth for your user’s permissions.
Implement your back end endpoint as follows:
userId
(required) is a string identifier to uniquely identify your user with
Liveblocks. This value will be used when counting unique MAUs in your Liveblocks
dashboard. You can refer to these user IDs in the Permissions REST API when
assigning group permissions.
groupIds
(optional) can be used to specify which groups this user belongs to.
These are arbitrary identifiers that make sense to your app, and that you can
refer to in the Permissions REST API when assigning group permissions.
userInfo
(optional) is any custom JSON value, which you can use to attach
static metadata to this user’s session. This will be publicly visible to all
other people in the room. Useful for metadata like the user’s full name, or
their avatar URL.
Here’s a real-world example of ID tokens in a Next.js route handler/endpoint. You can find examples for other frameworks in our authentication section.
Returns a list of rooms that are in the current project. The project is
determined by the secret key you’re using. Rooms are sorted by creation time,
with the newest room at index 0
. This is a wrapper around the
Get Rooms API and returns
the same response.
A number of options are also available, enabling you to filter for certain rooms.
You can use nextPage
to paginate rooms. In this example, when getNextPage
is
called, the next set of rooms is added to pages
.
Programmatically creates a new room from a room ID. The defaultAccesses
option
is required. Setting defaultAccesses
to ["room:write"]
creates a public
room, whereas setting it to []
will create a private room that needs
ID token permission to enter. This is a
wrapper around the
Create Room API and returns
the same response.
A number of room creation options are available, allowing you to set permissions and attach custom metadata.
Group and user permissions are only used with ID token authorization, learn more about managing permission with ID tokens.
Returns a room. Throws an error if the room isn’t found. This is a wrapper around the Get Room API and returns the same response.
Updates properties on a room. Throws an error if the room isn’t found. This is a wrapper around the Update Room API and returns the same response.
Permissions and metadata properties can be updated on the room. Note that you
need only pass the properties you’re updating. Setting a property to null
will
delete the property.
Group and user permissions are only used with ID token authorization, learn more about managing permission with ID tokens.
Deletes a room. Throws an error if the room isn’t found. This is a wrapper around the Delete Room API and returns no response.
Returns a list of users that are currently present in the room. Throws an error if the room isn’t found. This is a wrapper around the Get Active Users API and returns the same response.
Using UserMeta["info"]
from your config file as a generic adds typing to the
returned activeUsers
.
Broadcasts a custom event to the room. Throws an error if the room isn’t found. This is a wrapper around the Broadcast Event API and returns no response.
You can respond to custom events on the front end with
useBroadcastEvent
and
room.subscribe("event")
.
When receiving an event sent with Liveblocks.broadcastEvent
, user
will be
null
and connectionId
will be -1
.
Returns the contents of a room’s Storage tree. By default, returns Storage in LSON format. Throws an error if the room isn’t found. This is a wrapper around the Get Storage Document API and returns the same response.
LSON is a custom Liveblocks format that preserves information about the
conflict-free data types used. By default, getStorageDocument
returns Storage
in this format. This is the same as using "plain-json"
in the second argument.
You can also retrieve Storage as JSON by passing "json"
into the second
argument.
Initializes a room’s Storage tree with given LSON data. To use this, the room must have already been created and have empty Storage. Throws an error if the room isn’t found. Calling this will disconnect all active users from the room. This is a wrapper around the Initialize Storage Document API and returns the same response.
LSON is a custom Liveblocks format that preserves information about conflict-free data types. Here’s an example of initializing a simple Storage value.
Using the toPlainLson
helper provided by @liveblocks/client
, you can more
easily create LSON.
Deletes a room’s Storage data. Calling this will disconnect all active users from the room. Throws an error if the room isn’t found. This is a wrapper around the Delete Storage Document API and returns no response.
Returns a JSON representation of a room’s Yjs document. Throws an error if the room isn’t found. This is a wrapper around the Get Yjs Document API and returns the same response.
A number of options are available.
Send a Yjs binary update to a room’s Yjs document. You can use this to update or initialize the room’s Yjs document. Throws an error if the room isn’t found. This is a wrapper around the Send a Binary Yjs Update API and returns no response.
Here’s an example of how to update a room’s Yjs document with your changes.
To create a new room and initialize its Yjs document, call
liveblocks.createRoom
before sending the binary update.
Note that each text and code editor handles binary updates in a different way. For example, this is how to create a binary update with Slate.
Read the Yjs documentation to learn more about creating binary updates.
Return a room’s Yjs document as a single binary update. You can use this to get a copy of your Yjs document in your back end. Throws an error if the room isn’t found. This is a wrapper around the Get Yjs Document Encoded as a Binary Yjs Update API and returns the same response.
Read the Yjs documentation to learn more about using binary updates.
Creates a schema that can be used to enforce a room’s Storage data structure. The schema consists of a unique name, and a body which specifies the data shape of the room in Liveblocks schema syntax. This is a wrapper around the Create Schema API and returns the same response.
Read the schema validation page to learn more.
Returns a schema from its ID. A schema’s ID is a combination of its name and
version, for example the ID for version 1
of my-schema-name
is
my-schema-name@1
. This is a wrapper around the
Get Schema API
and returns the same response.
Read the schema validation page to learn more.
Updates a schema’s body and increments its version. A schema’s body specifies
the data shape of the room in Liveblocks
schema syntax. Find the schema by its
ID, a combination of its name and version, for example the ID for version 1
of
my-schema-name
is my-schema-name@1
. This is a wrapper around the
Update Schema API
and returns the same response.
Read the schema validation page to learn more.
Deletes a schema. This is only allowed if the schema is not attached to a room.
Find the schema by its ID, a combination of its name and version, for example
the ID for version 1
of my-schema-name
is my-schema-name@1
. This is a
wrapper around the
Delete Schema API and
returns no response.
Read the schema validation page to learn more.
Returns the schema attached to a room. Throws an error if the room isn’t found. This is a wrapper around the Get Schema By Room API and returns the same response.
Read the schema validation page to learn more.
Attaches a schema to a room, and instantly enables runtime schema validation in
it. Attach the schema by its ID, a combination of its name and version, for
example the ID for version 1
of my-schema-name
is my-schema-name@1
. This
is a wrapper around the
Attach Schema to a Room API
and returns the same response.
If the current contents of the room’s Storage do not match the schema, attaching will fail and the error message will give details on why the schema failed to attach. It’ll also throw an error if the room isn’t found.
Read the schema validation page to learn more.
Returns a list of threads found inside a room. Throws an error if the room isn’t found. This is a wrapper around the Get Room Threads API and returns the same response.
Returns a thread. Throws an error if the room or thread isn’t found. This is a wrapper around the Get Thread API and returns the same response.
Returns a list of participants found inside a thread. A participant is a user who has commented or been mentioned in the thread. Throws an error if the room or thread isn’t found. This is a wrapper around the Get Thread Participants API and returns the same response.
Returns a comment. Throws an error if the room, thread, or comment isn’t found. This is a wrapper around the Get Comment API and returns the same response.
Errors in our API methods, such as network failures, invalid arguments, or
server-side issues, are reported through the LiveblocksError
class. This
custom error class extends the standard JavaScript
Error
and includes a status
property, which provides the HTTP status code for the
error, such as 404 for not found or 500 for server errors.
Example of handling errors in a typical API call:
Returns an array of each user’s ID that has been mentioned in a CommentBody
(found under comment.body
).
This is most commonly used in combination with the
Comments API functions, for
example getComment
.
Here’s an example with a custom CommentBody
.
Used to convert a CommentBody
(found under comment.body
) into either a plain
string, Markdown, HTML, or a custom format.
This is most commonly used in combination with the
Comments API functions, for
example getComment
.
A number of options are also available.
Here are a number of different formatting examples derived from the same
CommentBody
.
The WebhookHandler
class is a helper to handle webhook requests from
Liveblocks.
It’s initialized with a signing secret that you can find in your project’s webhook page.
Verifies the request and returns the event. Note that rawBody
takes the body
as a string
.
Some frameworks parse request bodies into objects, which means using
JSON.stringify
may be necessary.
The purpose of authorize()
was to help you implement your custom
authentication back end. It generates old-style single-room tokens.
Please refer to our upgrade guide if you're
using the authorize
function in your back end. You should adopt
Liveblocks.prepareSession
or
Liveblocks.identifyUser
APIs instead.