Vue 3, XState, and CSS Starter Kit

This starter kit uses Vue 3, XState for state management, and pure CSS for styling.

How to use this starter kit

npm create @this-dot/starter -- --kit vue3-xstate-css

_{(use any of npm / yarn / pnpm)}

For more setup options, check out our setup instructions in the wiki.

Tech Stack

• Vue 3
• XState
• CSS

Included Tooling

• Vite - build / bundle tool
• Vue Router - navigation
• Cypress - component / unit testing
• Storybook - documents component designs
• ESLint - code consistency and best practices
• Prettier - code formatting

Type Support for .vue Imports in TS

This project is setup to handle TypeScript files. However, TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need TypeScript Vue Plugin (Volar) to make the TypeScript language service aware of .vue types.

Getting Started

Prerequisites

• Node.js 16.8 or later installed

Development

Once you've generated your new starter kit following the instructions above:

• cd into your project directory and run npm install to install the dependencies.
• Run npm run dev to start the development server.
• Click the http://localhost:5173 link from within your terminal. This will open that link in a tab to view the application, and also launch the XState inspector for you in a second tab.

Available commands

• npm run dev starts the local development server

• npm run dev:debug starts the local dev server and launches the XState visualizer

• npm run build-only handles compiling and minifying your files

• npm run type-check type checks your files

• npm run build combines the previous two commands to type-check your files then compile and minify them for production

• npm run preview will run the site locally based on your production built files generated by the build commands

• npm run test:unit runs Cypress component tests in a headless state, as they would run in a CI environment

• npm run test:unit:dev runs Cypress component tests in a headed state, so you can walk through individual tests

• npm run lint checks your files for common coding errors

• npm run format formats all of your files

• npm run storybook runs Storybook locally

• npm run build-storybook builds a version of your Storybook stories that you can host somewhere

Project Details

Project Structure

The main folder you'll interact with is the src folder. This is split into a few different folders to help keep concerns organized.

• assets: for global CSS or images that will need to be bundled with your code
• components: small, reusable pieces of code that don't need any specific store logic
• machines: to hold our state machines
• router: routing configuration
• stories: Storybook stories
• tests: Cypress component tests
• utils: any reusable helper functions you might need to create
• views: the actual "views" or pages you assemble, which will combine pieces from all the previous folders

Using XState

State vs Context

You'll notice that within both of our example machines, we're using a context object. You can read more specifics about how this works in the XState documentation on context, but in general the context stores data that might be quantitative in nature (like numbers, strings, or objects).

TS Support in Machines

XState offers us a schema option in our machines to allow us to type our state charts. We can use this to help strongly type our context and events. This will give us better tips when using our machine and help ensure we know what types of values we're expecting when we use them.

Machine Configuration

The createMachine call that we use to build machines accepts two objects.

The first object is always present, and specifies the name of our machine, it's initial state, any local context it needs, and the states our machine can be in. Eventually our states will need to define actions, services, or guards. These can be written directly within the state itself, or they can be passed to the optional second object in the createMachine function, and then referenced in the state by their name.

You'll see both options in this kit - the counterMachine has it's actions defined separately, and the greetMachine has the actions inline in the state but the service defined separately. Either option is valid. You might start with your actions inlined to ensure they work, and then separate them out to make them easier to read and debug.

Vue 3 Benefits

A key benefit of using Vue 3 is getting to work with the new provide and inject functions. These allow us to set up our own dependency system, so instead of having to deal with prop drilling and passing values along components that don't need them, we can provide that value in a parent component and then inject it into the component that needs it, bypassing all the others.

You can see an example of this with the GreetView component. We needed a way to provide an initial query value, but didn't want to have to set up a prop within the router or drill it down through the home component. So we set up the provide function in the main.ts file, which makes it globally available in our app to any component that needs it. The provide function takes two arguments, a key and a value. Then, our GreetView component can inject that value and make use of it. We're also able to set a default value in case the provided key doesn't have a value.

Cypress Testing

The only specific setup thing we needed to do to enable component testing was to add the mount command to Cypress. They have packages available for multiple common frameworks which will provide the functionality for you - all we have to do is go into our cypress/support/component.ts file, import the mount function, and then tell Cypress to add that command.

To enable our tests to also be able to access our provided value in the GreetView component, we've customized the provided mount function so that we provide an initial value. Then, for each test that needs to mount the component, we can either provide it with nothing (thus allowing our default value to be tested) or give it a custom message just for our tests to ensure everything works as expected.

Deployment

Deploying to a hosting service like Netlify or Vercel is as straight forward as hooking up your repository to the service and letting the service auto detect the configuration for you.

The main question they're likely to ask is what command to run to build your site, which for this kit is the build-only command (or build if you want it to run type checking first).