Solid Automerge

Solid primitives for Automerge .

pnpm add solid-js @automerge/automerge-repo solid-automerge

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>

useDocSignal

A light coarse-grained primitive when you care only that a doc has changed, and not how. Returns [doc, handle].

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

// example
const [url, setURL] = createSignal<AutomergeUrl>(props.url)
const [doc, handle] = useDocSignal(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.

createDocSignal

A light coarse-grained primitive when you care only that a doc has changed, and not how. Takes a signal DocHandle.

Underlying primitive for useDocSignal.

Works with useDocHandle.

createDocSignal<T>(() => DocHandle<T>): Accessor<Doc<T>>

makeDocSignal

Just like createDocSignal, but without a reactive input.

Underlying primitive for createDocSignal.

makeDocSignal<T>(handle: DocHandle<T>): Accessor<Doc<T>>

// example
const handle = repo.find(url)
const doc = makeDocSignal<{count: number}>(handle)

return <span>{doc()?.count}</span>

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()