solid-liveblocks
v0.1.11
Published
A set of Solid hooks and providers to use Liveblocks declaratively. Liveblocks is the all-in-one toolkit to build collaborative products like Figma, Notion, and more.
Downloads
7
Maintainers
Readme
solid-liveblocks
Intro
This is a set of Solid hooks and providers to use Liveblocks declaratively. It is essentially a port of the React version and while, due to Solid's reactivity model, it wasn't completely necessary to port all the hooks over, I did so anyway (for the most part) so the API would be as similar as possible.
On that note, you can refer to the React Liveblocks docs for more information on the different use cases of the API. Note though, that there is one main difference, which is that for most hooks a Solid signal is returned, which means you must invoke it to get the current value:
const me = useSelf()
createEffect(() => console.log('Me: ', me()))
Getting started
First, install the package:
npm i solid-liveblocks @liveblocks/client
Then, you can basically follow the same instructions outlined in the Liveblocks React getting started docs:
For example, use createClient
to create your Liveblocks client and createRoomContext
to connect to a Liveblocks room:
// liveblocks.config.ts
import { createClient } from '@liveblocks/client'
import { createRoomContext } from 'solid-liveblocks'
const client = createClient({
publicApiKey: 'pk_prod_xxxxxxxxxxxxxxxxxxxxxxxx',
})
export const { RoomProvider } = createRoomContext(client)
Then you can use the provider in your app:
import { RoomProvider } from './liveblocks.config'
function Index() {
return (
<RoomProvider id="example-room-id" initialPresence={{}}>
{/* Components that are inside RoomProvider can use our hooks */}
</RoomProvider>
)
}
You can check out this Stackblitz demo for a rewrite of the Liveblocks Solid cursors example. Start it up in more than one client and watch those colorful cursors go!
Suspense
The same export pattern implemented by Liveblocks for their Suspense hooks was followed here as well. So, you can access all Suspense aware hooks by grabbing them from the nested suspense
object returned by createRoomContext
, like so:
export const {
suspense: {
RoomProvider,
useSelf,
useStorage,
// ...
},
} = createRoomContext(client)
However, due to the fundamental difference in how Solid renders and thus how it also handles async operations, the actual implementation of each Suspense aware hook is a bit different than its Liveblocks counterpart.
Specifically, you'll notice that what's returned is a Solid resource, which is Solid's primitive for handling async operations. This in turn means the value returned from the hoook has a few special properties that you can use to determine the state of the promise:
state: 'unresolved' | 'pending' | 'ready' | 'refreshing' | 'errored'
loading: boolean
error: any
latest: T | undefined
Note that these values are Solid's and may change. Please refer to the link above for the most up to date documentation.
Further, since it is a Solid resource, you can use it within a Solid Suspense
component and Suspense will trigger automatically without any further work on your part. As a simple example:
function ColorList() {
const colors = useStorage((root) => root.colors)
return (
<Suspense fallback={<p>Loading...</p>}>
<For each={colors()}>{(color) => <li>{color}</li>}</For>
</Suspense>
)
}
Take care that if you need to use the data from one resource as the input to another, you should ensure to use Solid's untrack
where appropriate so as to not cause any infinite loops. For example, say you want to grab the first connected "other" user's id via useOthersConnectionIds
and then supply it to useOther
. The following pattern has worked for me:
const ids = useOthersConnectionIds()
// Create a memo that returns a signal to our selected other user state.
const countSignal = createMemo(() => {
const id = ids()?.[0]
// Note here that we return `untrack(() => useOther(...))`, i.e. we supply our hook wrapped
// in a function to `untrack` rather than calling it directly. This is important, as it prevents
// infinite loops (setting & getting the `useOther` signal) while also maintaining reactivity.
if (id) return untrack(() => useOther(id, (user) => user.presence.count))
})
// The above memo returns a signal to the resource, so for convenience we can create another memo
// to return the actual resource itself.
const count = createMemo(() => countSignal()?.())
// And finally do something with the data, e.g. broadcast an event.
createEffect(() => {
if (count() > 5) {
broadcast({ type: 'GT-5', data: { msg: 'Other user has count greater than 5' } })
}
})
SSR
All non Suspense hooks are compatible with SSR out of the box. The approach for Suspense aware hooks is similar to that of the official Liveblocks recommendation, which is to use a helper component, ClientSideSuspense
, that acts as a drop in for Solid's Suspense
and ensures only the fallback is ever rendered on the server:
import { ClientSideSuspense } from 'solid-liveblocks'
export default function Page() {
return (
<RoomProvider /* ... */>
<ClientSideSuspense fallback={<p>Loading...</p>}>{() => <App />}</ClientSideSuspense>
</RoomProvider>
)
}
Note that if you attempt to use a Suspense aware hook without ClientSideSuspense
via SSR, an error will be thrown on the server.
Contributing
If you come across any problems or see areas for improvement, feel free to create an issue. If you have new code to propose, first ensure all current tests pass with your changes. You can do so by executing the following:
npm test
License
Licensed under the MIT License, Copyright © 2023-present tmns.
See LICENSE for more information.