@sigrea/vue

@sigrea/vue adapts @sigrea/core molecule modules and signals for Vue 3's Composition API. It aligns lifecycle scopes with component lifecycles, preserves deep reactivity, and provides composables for


`

$3

`ts
// CounterMolecule.ts
import { molecule, readonly, signal } from "@sigrea/core";

type CounterProps = {
initialCount: number;
initialStep: number;
};

export const CounterMolecule = molecule((props: CounterProps) => {
const count = signal(props.initialCount);
const step = signal(props.initialStep);

function setStep(next: number) {
step.value = next;
}

function increment() {
count.value += step.value;
}

function reset() {
count.value = props.initialCount;
}

return {
count: readonly(count),
step: readonly(step),
setStep,
increment,
reset,
};
});
`

`vue




`

$3

`vue



`

useMutableSignal expects a writable signal produced by signal(). Passing a readonly signal throws at runtime so incorrect bindings fail fast.

$3

`vue



`

API Reference

$3

`ts
function useSignal(
signal: Signal | ReadonlySignal
): DeepReadonly>
`

Subscribes to a signal or computed value and returns a readonly Vue ref that updates when the signal changes. The subscription is cleaned up when the component unmounts.

$3

`ts
function useComputed(source: Computed): DeepReadonly>
`

Subscribes to a computed value and returns a readonly Vue ref that updates when the computed value changes. The subscription is cleaned up when the component unmounts.

$3

`ts
function useDeepSignal(signal: DeepSignal): ShallowRef
`

Subscribes to a deep signal and returns a mutable Vue ref. Updates to the deep signal trigger reactivity, and the subscription is cleaned up when the component unmounts. Templates unwrap the ref automatically, so accessing nested properties requires no .value. In script blocks, use state.value to access the underlying object.

$3

`ts
function useMutableSignal(signal: Signal): WritableComputedRef
`

Wraps a Sigrea signal as a Vue WritableComputedRef for two-way bindings like v-model. Expects a writable signal created by signal(). Passing a readonly signal throws at runtime.

$3

`ts
function useMolecule(
molecule: MoleculeFactory,
...args: MoleculeArgs
): MoleculeInstance
`

Mounts a molecule factory and returns its MoleculeInstance. Sigrea augments the molecule with lifecycle metadata: onMount callbacks run after the component mounts, and onUnmount callbacks run before it unmounts.

KeepAlive Support

When used inside Vue's , molecule side effects are automatically managed for optimal resource efficiency:

- On deactivation (onDeactivated): watch effects and ongoing work are paused via unmountMolecule. The molecule instance itself remains alive, preserving its internal state.
- On reactivation (onActivated): Side effects resume via mountMolecule, allowing watches and subscriptions to pick up where they left off.
- On final unmount: The molecule is fully disposed via disposeMolecule, releasing all resources.

This design prevents unnecessary computation and subscriptions while components are cached but invisible, reducing CPU and memory usage without losing state.

Props Handling

Props are treated as an initial snapshot. Updating component props does not recreate the molecule instance or update the snapshot; model dynamic values via signals or explicit molecule methods (for example, setStep).

Testing

`ts
// tests/Counter.test.ts
import { mount } from "@vue/test-utils";
import Counter from "../components/Counter.vue";

it("increments and displays the updated count", async () => {
const wrapper = mount(Counter, {
props: { initialCount: 10 },
});

await wrapper.find("button").trigger("click");

expect(wrapper.text()).toContain("11");
});
`

Handling Scope Cleanup Errors

For global error handling configuration, see @sigrea/core - Handling Scope Cleanup Errors.

In Vue apps, configure the handler in your application entry point before mounting:

`ts
// main.ts
import { setScopeCleanupErrorHandler } from "@sigrea/core";
import { createApp } from "vue";
import App from "./App.vue";

setScopeCleanupErrorHandler((error, context) => {
console.error(Cleanup failed:, error);

// Forward to monitoring service
if (typeof Sentry !== "undefined") {
Sentry.captureException(error, {
tags: { scopeId: context.scopeId, phase: context.phase },
});
}
});

createApp(App).mount("#app");
`

Development

This repo targets Node.js 20 or later.

If you use mise:

- mise trust -y — trust mise.toml (first run only).
- mise run ci — run CI-equivalent checks locally.
- mise run notes — preview release notes (optional).

You can also run pnpm scripts directly:

- pnpm install — install dependencies.
- pnpm test — run the Vitest suite once (no watch).
- pnpm typecheck — run TypeScript type checking.
- pnpm test:coverage — collect coverage.
- pnpm build — compile via unbuild to produce dual CJS/ESM bundles.
- pnpm cicheck — run CI checks locally.
- pnpm dev` — launch the playground counter demo.

See CONTRIBUTING.md for workflow details.

License

MIT — see LICENSE.