PocketPages Realtime Plugin
Convience functions for PocketBase realtime messaging
Installation
npm install pocketpages-plugin-realtime
Setup
// +config.js
module.exports = {
plugins: ['pocketpages-plugin-realtime'],
}
Usage
Basic Example
In this basic example, we make an API call on an interval that causes SSE data to be sent from the server.
By default, messages are only sent to realtime clients that have subscribed to the topic.
<script src="https://unpkg.com/pocketbase/dist/pocketbase.umd.js"></script>
<script>
const pb = new PocketBase('http://127.0.0.1:8090')
// Subscribe to realtime updates
pb.realtime.subscribe('ping', (data) => {
console.log('Received:', data)
})
// Generate a ping every 5s
setInterval(() => {
fetch(`api/ping`)
}, 5000)
</script>
<!-- pages/api/ping.ejs -->
<script server>
context.realtime.send('ping', +new Date().toString())
</script>
With Custom Filter
By default, messages are only sent to clients subscribed to the topic. However, you can assign a custom filter for more advanced use cases.
Here is a filter that sends the message to all authenticated clients.
// pages/_private/sendAlert.js
const sendAlert = (context, message) => {
context.realtime.send(`alert`, message, {
filter: (clientId, client, topic, message) => {
return client.get('auth')?.id
},
})
}
Note: When you implement a custom filter, you must check
client.hasSubscription(topic)
yourself as needed.
Hypermedia (HTMX, Datastar)
For hypermedia frameworks, you may wish to send HTML. The easiest way to do that is by creating a partial and stringifying the result.
<!-- pages/api/chat.ejs -->
<script server>
const { message } = body()
realtime.send('chat', stringify(include('chat-msg.ejs', { message })))
</script>
API
The plugin extends the context API with a realtime
object:
realtime.getClientById(clientId)
Retrieves a specific realtime client by their ID.
- clientId (string): The unique identifier of the client
- returns (Client): The client object or undefined if not found
realtime.send(topic, message, options?)
Sends a message to all subscribed clients.
- topic (string): The subscription topic name
- message (string): The message to send
- options (object, optional): Configuration options
- filter (function, optional): Custom filter function to target specific clients
const DefaultSseFilter: RealtimeFilter = (
clientId: ClientId,
client: Client,
topic: string,
message: string
) => {
return client.hasSubscription(topic)
}