automerge-repo-solid-primitives

SolidJS primitives for Automerge Repo

Helpers for using <img alt="" src=.assets/automerge.png width=22 height=22> Automerge with <img alt="" src=.assets/solid.png width=22 height=22> SolidJS .

[!note]

This library targets @automerge/automerge-repo@2 which is currently in Alpha

Changes adapting to breaking changes will be reflected as patch bumps in this library, until @automerge/automerge-repo@2 is stable.

pnpm add @automerge/automerge-repo@next
pnpm add automerge-repo-solid-primitives@next

useDocument ✨

Get a fine-grained live view of an automerge document from its URL.

When the handle receives changes, it converts the incoming automerge patch ops to precise solid store updates, giving you fine-grained reactivity that's consistent across space and time.

Returns [doc, handle].

useDocument<T>(
    () => AutomergeURL,
    options?: {repo: Repo}
): [Doc<T>, DocHandle<T>]

// example
const [url, setURL] = createSignal<AutomergeUrl>(props.url)
const [doc, handle] = useDocument(url, {repo})

const inc = () => handle()?.change(d => d.count++)
return <button onclick={inc}>{doc()?.count}</button>

The {repo} option can be left out if you are using RepoContext.

createDocumentProjection

Get a fine-grained live view from a signal automerge DocHandle.

Underlying primitive for useDocument.

Works with useHandle.

createDocumentProjection<T>(() => AutomergeUrl): Doc<T>

// example
const handle = repo.find(url)
const doc = makeDocumentProjection<{items: {title: string}[]}>(handle)

// subscribes fine-grained to doc.items[1].title
return <h1>{doc.items[1].title}</h1>

makeDocumentProjection

Just like createDocumentProjection, but without a reactive input.

Underlying primitive for createDocumentProjection.

makeDocumentProjection<T>(handle: Handle<T>): Doc<T>

// example
const handle = repo.find(url)
const doc = makeDocumentProjection<{items: {title: string}[]}>(handle)

// subscribes fine-grained to doc.items[1].title
return <h1>{doc.items[1].title}</h1>

useDocHandle

Get a DocHandle from the repo as a resource.

Perfect for handing to createDocumentProjection.

useDocHandle<T>(
    () => AnyDocumentId,
    options?: {repo: Repo}
): Resource<Handle<T>>

const handle = useDocHandle(id, {repo})
// or
const handle = useDocHandle(id)

The repo option can be left out if you are using RepoContext.

context

If you prefer the context pattern for some reason, you can pass the repo higher up in your app with RepoContext

RepoContext

A convenience context for Automerge-Repo Solid apps. Optional: if you prefer you can pass a repo as an option to useDocHandle and useDocument.

<RepoContext.Provider repo={Repo}>
	<App />
</RepoContext.Provider>

useRepo

Get the repo from the context.

useRepo(): Repo

e.g.

const repo = useRepo()