@solid-primitives/rootless

@solid-primitives/rootless

A collection of helpers that aim to simplify using reactive primitives outside of reactive roots, and managing disposal of reactive roots.

• createSubRoot - Creates a reactive sub root, that will be automatically disposed when it's owner does.
• createCallback - A wrapper for creating callbacks with runWithOwner.
• createDisposable - For disposing computations early – before the root cleanup.
• createSingletonRoot - Share "global primitives" across multiple reactive scopes.
• createRootPool - Creates a pool of reactive roots, that can be reused.

Installation

npm install @solid-primitives/rootless
# or
pnpm add @solid-primitives/rootless
# or
yarn add @solid-primitives/rootless

createSubRoot

Previously createSubRoot

Creates a reactive root branch, that will be automatically disposed when it's owner does.

How to use it

Use it for nested roots (literally nested, or provided manually to dependency array) that should be disposed before or with their owner.

import { createSubRoot } from "@solid-primitives/rootless";

createRoot(dispose => {
  createSubRoot(disposeBranch => {
    // computations will be disposed with branch
    createEffect(() => {...});

    // disposes only the branch
    disposeBranch();
  });

  // disposes the outer root, AND all the nested branches
  dispose();
});

Definition

function createSubRoot<T>(fn: (dispose: VoidFunction) => T, ...owners: (Owner | null)[]): T;

createCallback

A wrapper for creating callbacks with runWithOwner. It gives you the option to use reactive primitives after root setup and outside of effects.

Why?

All of the callback-based (in opposite to effect-based) events is Solid don't have a root, because the root is changed synchronously after initialization finishes. So normally that would prevent you from using reactive primitives there.

runWithOwner attatches whatever computations created inside, to the owner passed to it.

How to use it

// in component body
const handleClick = createCallback(() => {
   // the effect will be created normally, attached to the component's reactive root
   createEffect(() => {...})
})

// in jsx
<button onClick={handleClick} />

Definition

function createCallback<T extends AnyFunction>(callback: T, owner?: Owner | null): T;

createDisposable

Previously runWithSubRoot

For disposing computations early – before the root cleanup.

How to use it

Executes provided function in a createSubRoot (auto-disposing root), and returns a dispose function, to dispose computations used inside before automatic cleanup.

const dispose = createDisposable(dispose => {
   createEffect(() => {...})
});

// dispose later (if not, will dispose automatically)
dispose()

Definition

export function createDisposable(
  fn: (dispose: VoidFunction) => void,
  ...owners: (Owner | null)[]
): VoidFunction;

createSingletonRoot

Creates a reactive root that is shared across every instance it was used in. Shared root gets created when the returned function gets first called, and disposed when last reactive context listening to it gets disposed. Only to be recreated again when a new listener appears.

Designed to make "global primitives" shareable, without instanciating them (recreating, state, computations, event listeners, etc.) every time they're used. For example a createLocationState primitive would work the same for every instance and provide the same data, so reinitializeing it every time is wastefull.

How to use it

createSingletonRoot primitive takes a single argument:

• factory - a function where can you initialize some reactive primitives, returned value will be shared across instances.

And returns a function registering reactive owner as one of the listeners, returns the value factory function returned.

import { createSingletonRoot } from "@solid-primitives/rootless";

const useState = createSingletonRoot(() => {
   return createMemo(() => {...})
});

// later in a component:
const state = useState();
state()

// in another component
// previously created primitive would get reused
const state = useState();
...

Type Definition

function createSingletonRoot<T>(factory: (dispose: Fn) => T): () => T;

createHydratableSingletonRoot

A experimental version of createSingletonRoot that will deopt of creating a singleton root if used in SSR or during hydration.

The reason for this is that createSingletonRoot will create a root that will be shared across all instances of the primitive, and this could mean state leaking between different requests. And during hydration, if you were to update the shared state before the hydration is finished, it could cause a mismatch between the server and client.

The API is experimental, and likely to change or be merged into createSingletonRoot in the future.

createRootPool

Creates a pool of roots, that can be reused. Useful for creating components that are mounted and unmounted frequently. When the root is created, it will call the factory function. Roots are created by calling the returned function, after cleanup they won't be disposed but instead put back into the pool to be reused. Next time the function is called, it will reuse the root from the pool and update it with the new data.

How to use it

createRootPool primitive takes two arguments:

• factory - A function that will be called when a new root is created.
• options - Options for the root pool.
  • limit - Pool limit, defaults to 100. Roots that are not used will be disposed when the limit is reached.

Returns a function that creates and reuses roots.

import { createRootPool } from "@solid-primitives/rootless";

const useCounter = createRootPool((arg, active, dispose) => {
  const [count, setCount] = createSignal(arg());

  createEffect(() => {
    if (!active()) return;
    // so some side effect
    console.log("count", count());
  });

  return <button onClick={() => setCount(count() + 1)}>Count: {count()}</button>;
});

return <Show when={frequentlyChangedCondidion()}>{useCounter(1)}</Show>;

Usage with <For>

createRootPool can be combined with <For> (or any other control-flow component) to reuse already created HTML Elements while getting the same benefits of stable connection between rendered elements and the reference to the source item.

const pool = createRootPool(item => <MyListItem item={item()}>)

return <For each={items()}>{item => pool(item)}</For>

Warning Using createRootPool with <For> creates an un-keyed control-flow — meaning that a single element can be reused by more than one item (not at the same time). Which can cause styles, animations, and other side effects to leak between items. It's meant to be used only as a performance optimization, and only when you're sure that the side effects won't leak between items.

Changelog

See CHANGELOG.md

Similar packages

Other packages similar to @solid-primitives/rootless

solid-js

Solid's core package provides createRoot and the underlying reactive primitives. It offers lower-level ownership and disposal controls; rootless utilities are intended to make primitives easier to use when an owner may not already exist.

@solid-primitives/utils

A collection of general-purpose helpers used when building Solid primitives. It overlaps in its support for primitive authors, but is broader and does not focus specifically on allowing primitives to work without an existing reactive owner.

@solid-primitives/memo

Provides memoization-related reactive utilities for Solid. It is similar in that it supplies reusable reactive building blocks, but concentrates on memoization rather than rootless usage.