Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
useUnit
✓ import { useUnit } from 'effector-vue/composition';
✗ import { useUnit } from 'effector-vue';
The `useUnit` hook, part of the Composition API, is specifically exported from `effector-vue/composition`. Direct import from `effector-vue` will not work.
VueEffector
✓ import { VueEffector } from 'effector-vue/options-vue3';
✗ import { VueEffector } from 'effector-vue';
For Vue's Options API, the `VueEffector` plugin is imported from `effector-vue/options-vue3`. This allows integration into the Vue instance via `app.use()`.
createStore
✓ import { createStore } from 'effector';
✗ import { createStore } from 'effector-vue';
Core Effector units like `createStore` and `createEvent` are imported directly from the `effector` package, not `effector-vue`. The bindings only provide hooks and integration for Vue components.
This quickstart demonstrates basic reactive state management using `effector-vue` with Vue 3's Composition API. It sets up an Effector store and event, then uses `useUnit` to bind them to a Vue component, showcasing how input changes update derived state.
import {createStore, createEvent} from 'effector'
import {useUnit} from 'effector-vue/composition'
import { defineComponent, h } from 'vue';
export const inputText = createEvent<string>()
export const $text = createStore<string>('').on(inputText, (_, text) => text)
export const $size = $text.map(text => text.length)
const App = defineComponent({
setup() {
const text = useUnit($text)
const size = useUnit($size)
const handleTextChange = useUnit(inputText)
return () =>
h('form', [
h('input', {
type: 'text',
onInput: (e: Event) => handleTextChange((e.target as HTMLInputElement).value),
value: text.value
}),
h('p', `Length: ${size.value}`)
])
}
});
// To run in a browser or test environment (example setup)
if (typeof window !== 'undefined') {
import { createApp } from 'vue';
const app = createApp(App);
app.mount('#app');
}
Debug
Known issues
breakingEffector 23 deprecated several operators like `forward` and `guard` in favor of `sample`. While `effector-vue` itself might not directly use these, applications using older Effector patterns may see deprecation warnings.fixMigrate usage of `forward` and `guard` to `sample` or other appropriate Effector operators. The official Effector ESLint plugin can assist with auto-fixing.
affects: >=23.0.0 of effector (peer dep)
gotchaDirect mutation of Effector stores (e.g., `$store.value = newValue`) is not supported and will not trigger updates. Effector stores are immutable, and state changes must always occur through events or effects.fixAlways dispatch an event (e.g., `event(newValue)`) that a store's `.on()` or `.watch()` handler listens to, or use effects, to update store values.
affects: >=23.0.0
gotcha`effector-vue` provides separate entry points for the Composition API (`effector-vue/composition`) and Options API (`effector-vue/options-vue3`). Incorrectly importing from the root `effector-vue` or the wrong subpath can lead to runtime errors.fixEnsure you import hooks like `useUnit` from `effector-vue/composition` and the `VueEffector` plugin from `effector-vue/options-vue3`.
affects: >=23.0.0
gotchaThe `effector-vue/composition` module is slated for deprecation in `effector@24` and removal in `effector@25`, with hooks moving to the main `effector-vue` module.fixPlan to update import paths for `useUnit` and other composition API hooks from `effector-vue/composition` to `effector-vue` when `effector@24` is released.
affects: Current (23.x), will be affected by future `effector` versions
gotchaSome users have reported `SyntaxError: The requested module 'vue' does not provide an export named 'default'` when importing `effector-vue` in Vue 3 projects, related to how Vue is imported within the library's barrel file.fixThis often points to issues with module resolution or bundling configurations that incorrectly handle Vue's ESM exports. Ensure your build tools are correctly configured for Vue 3's ESM, or try explicit subpath imports for Vue if you encounter this.
affects: >=23.1.0
Errors
Common errors & fixes
SyntaxError: The requested module 'vue' does not provide an export named 'default'
Incorrect module resolution for Vue's ESM exports within `effector-vue`'s internal structure or the consuming project's bundler configuration.
fixCheck your bundler (Webpack, Vite, Rollup) configuration to ensure proper handling of Vue 3's ESM exports. Sometimes this can be resolved by upgrading bundler versions or ensuring explicit ESM-friendly settings.
Cannot find module 'effector' or 'vue'
Peer dependencies `effector` or `vue` are not installed or do not meet the specified version range.
fixInstall `effector` and `vue` (and `@vue/reactivity`, `@vue/runtime-core`) using your package manager: `npm install effector vue @vue/reactivity @vue/runtime-core` or `yarn add effector vue @vue/reactivity @vue/runtime-core`.
TypeError: Cannot read properties of undefined (reading 'value') when accessing state from useUnit
Attempting to access a reactive property `value` on a non-reactive or `undefined` result from `useUnit`, or not unwrapping `ref`s correctly.
fixEnsure the Effector unit passed to `useUnit` is a valid store or event. Remember that `useUnit` for stores returns a `Ref` in Vue 3, so access its value with `.value` in `<script setup>` or in a `render` function if it's not automatically unwrapped.
[Vue warn]: Failed to resolve component: <ComponentName> (or similar errors related to Gate components)
When using `createGate` or `useGate`, the component might not be correctly registered or its props might not align with the Gate's expectations.
fixEnsure `createGate` is defined correctly. If using `useGate`, ensure it's called within a component's `setup` function. Double-check that component props passed to the Gate align with its defined type signature.
Audit
Dependencies
vuerequiredVue.js framework, peer dependency for the bindings.
effectorrequiredCore state management library, peer dependency.
@vue/reactivityrequiredVue's reactivity system, a peer dependency for integration.
@vue/runtime-corerequiredVue's core runtime utilities, a peer dependency.