Vue 2 docs not clear nor complete

[allestaire]

I've check this documentation but it seems like not too clear for as wanted a to go example in setting it up The documentation only shows how to setup states but Im wondering why not include on how to include services, guards and so when creating state

https://xstate.js.org/docs/recipes/vue.html

Though upon checking the createMachine docs it provides options But not seeing clear information in making through on non-composition-api.

In composition-api version is easy and clear. createMachine then userMachine which dev can inject services, actions, and guards in to.

Can you provide other example which we can see on how do we inject those options? Or are there already existing example but hidden or not accessible on the site?

[allestaire]

Found this docs https://xstate.js.org/docs/guides/communication.html#configuring-services

Now Im guessing the docs it misinformed but it is right at some point, if the dev doest work with services, actions and guards The I guess the createMachine should be placed on the created hook.

[mattpocock]

@allestaire Yep, good shout - the recipes/vue docs need updating.

Do these docs help?

https://xstate.js.org/docs/packages/xstate-vue/

[allestaire]

@allestaire Yep, good shout - the recipes/vue docs need updating.

Do these docs help?

https://xstate.js.org/docs/packages/xstate-vue/

Sorry, but the docs you shared seems like specific for composition-api only.

There are still old projects that uses or may not use xstate and as for me xstate is a great package for long forms and it helps me alot. This helps me to manage codes, easy maintained, easy tracking, less component variable. Totally a life saver.

But if I want to implement this, of course I'll go to the site and find the east setup for such version.

By the way, thanks to this great package 😄 👍

[Andarist]

For Vue 2 there is this alternative package: https://www.npmjs.com/package/xstate-vue2 . We probably should call this out in the docs.

[amypellegrini]

I created an example repository of how basic usage looks like, I'll be expanding it to include more detail and use cases:

https://github.com/amypellegrini/xstate-vue-example/blob/main/src/App.vue

It's worth noticing that the setup code in the Packages section of the docs is now deprecated according to latest Vue.

Using this code:

export default {
  setup() {
    const { state, send } = useMachine(toggleMachine);
    return {
      state,
      send
    };
  }
};

Triggers the linter rule vue/no-export-in-script-setup.

The good news (if I understand correctly) is that now this is no longer needed, and you can declare and use the constants directly:

<script setup>
import { useMachine } from '@xstate/vue'
import { createMachine } from 'xstate'
const toggleMachine = createMachine({
  id: 'toggle',
  initial: 'inactive',
  states: {
    inactive: {
      on: { TOGGLE: 'active' }
    },
    active: {
      on: { TOGGLE: 'inactive' }
    }
  }
})
const { state, send } = useMachine(toggleMachine)
</script>

<template>
  <button @click="send('TOGGLE')">state is: {{ state.value }}</button>
</template>

I verified this works with the following packages:

    "@xstate/vue": "^2.0.0",
    "vue": "^3.2.47",
    "xstate": "^4.37.2"

I'll be adding more examples with usages of services, actions, and guards. Once we figure this out I'll send PRs with updates for the docs.

[amypellegrini]

Ok, I bootstrapped another example for Vue 2:

https://github.com/amypellegrini/xstate-vue2-example

Interestingly enough, the same lint rule applies even for Vue version 2:

https://eslint.vuejs.org/rules/no-export-in-script-setup.html

Which makes everything more confusing and harder to understand, at least for me (not being familiar with Vue nor its composition API).

So far I see the need for distinct usage examples of Vue 2 and Vue 3, with and without composition API for Vue 3.

Topic aside, I'm trying to also understand the format and expectations around recipes and packages sections of the Xstate docs. As far as I can see, recipes are general example guidelines and context, while the packages section offers more formal documentation on the packages.

[davidkpiano]

Topic aside, I'm trying to also understand the format and expectations around recipes and packages sections of the Xstate docs. As far as I can see, recipes are general example guidelines and context, while the packages section offers more formal documentation on the packages.

Sorry for the confusion; recipes were originally "how to use XState with X" before we added official integrations.

[amypellegrini]

Thanks @davidkpiano for the clarification.

I opened a draft PR and I'll be adding changes over the next few days:

https://github.com/statelyai/xstate/pull/4009

Now that I understand better I think there are two main use cases to consider:

• Using Xstate interpret and inject it into the app (without any plugin);
• Using the useMachine hook provided by either @xstate/vue or xstate-vue2.

It looks like for Vue 3 the recommended usage is via hook, so it makes sense to include examples with interpret only as reference for legacy applications using Vue 2 that for whatever reason can't use the xstate-vue2 plugin.