Effector Vue Bindings

Common errors

• SyntaxError: The requested module 'vue' does not provide an export named 'default'

  cause Incorrect module resolution for Vue's ESM exports within `effector-vue`'s internal structure or the consuming project's bundler configuration.
  fix Check 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'

  cause Peer dependencies `effector` or `vue` are not installed or do not meet the specified version range.
  fix Install `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

  cause Attempting to access a reactive property `value` on a non-reactive or `undefined` result from `useUnit`, or not unwrapping `ref`s correctly.
  fix Ensure 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)

  cause When using `createGate` or `useGate`, the component might not be correctly registered or its props might not align with the Gate's expectations.
  fix Ensure `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.

Warnings

• breaking Effector 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.
  Fix: Migrate usage of `forward` and `guard` to `sample` or other appropriate Effector operators. The official Effector ESLint plugin can assist with auto-fixing.
• gotcha Direct 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.
  Fix: Always dispatch an event (e.g., `event(newValue)`) that a store's `.on()` or `.watch()` handler listens to, or use effects, to update store values.
• 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.
  Fix: Ensure you import hooks like `useUnit` from `effector-vue/composition` and the `VueEffector` plugin from `effector-vue/options-vue3`.
• gotcha The `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.
  Fix: Plan to update import paths for `useUnit` and other composition API hooks from `effector-vue/composition` to `effector-vue` when `effector@24` is released.
• gotcha Some 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.
  Fix: This 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.

Install

• npm install effector-vue npm
• yarn add effector-vue yarn
• pnpm add effector-vue pnpm

Imports

• useUnit
  wrong:

  import { useUnit } from 'effector-vue';

  correct:

  import { useUnit } from 'effector-vue/composition';

  The `useUnit` hook, part of the Composition API, is specifically exported from `effector-vue/composition`. Direct import from `effector-vue` will not work.
• VueEffector
  wrong:

  import { VueEffector } from 'effector-vue';

  correct:

  import { VueEffector } from 'effector-vue/options-vue3';

  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
  wrong:

  import { createStore } from 'effector-vue';

  correct:

  import { createStore } from 'effector';

  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.

Quickstart

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');
}