Vue CLI Pinia Plugin

Common errors

• command not found: vue

  cause Vue CLI is not installed globally or not in your system's PATH.
  fix Install Vue CLI globally: `npm install -g @vue/cli` or `yarn global add @vue/cli`.

• Error: The plugin `vue-cli-plugin-pinia` has already been applied.

  cause You are trying to add the plugin to a project where it has already been installed.
  fix This message indicates the plugin is already set up. No action is required unless you intended to re-install for an upgrade (which is usually handled by `npm update` or `yarn upgrade`).

• Module not found: Error: Can't resolve 'pinia'

  cause Pinia dependency might not be correctly installed or its module resolution is failing after adding the plugin.
  fix Run `npm install` or `yarn install` to ensure all dependencies are present. If the issue persists, manually install Pinia: `npm install pinia` or `yarn add pinia`.

Warnings

• breaking Vue CLI itself is in maintenance mode. For new projects, the official recommendation is to use `create-vue` which scaffolds Vite-based applications. This plugin is primarily for existing Vue CLI projects.
  Fix: For new projects, use `npm init vue@latest` or `yarn create vue` instead of `vue create`.
• gotcha The plugin automatically injects the `@vue/composition-api` plugin only for Vue 2 projects with versions less than 2.7.0. If you are using Vue 2.7.0+, the Composition API is built-in and the injection is skipped. Ensure your Vue 2 setup aligns with this behavior.
  Fix: No direct fix needed, but be aware of the dependency management. If manually using `@vue/composition-api` in Vue 2.7+, it might lead to conflicts.
• gotcha This plugin primarily handles the initial setup of Pinia. Subsequent updates to Pinia itself or its API may introduce breaking changes that are independent of the plugin but will affect your application.
  Fix: Always check Pinia's official release notes when upgrading Pinia versions (e.g., from v1 to v2), and adjust your Pinia stores and usage patterns accordingly.

Install

• npm install vue-cli-plugin-pinia npm
• yarn add vue-cli-plugin-pinia yarn
• pnpm add vue-cli-plugin-pinia pnpm

Imports

• createPinia
  wrong:

  const { createPinia } = require('pinia')

  correct:

  import { createPinia } from 'pinia'

  Used to create the Pinia store instance for your Vue application. Pinia is ESM-first.
• defineStore
  wrong:

  import defineStore from 'pinia'

  correct:

  import { defineStore } from 'pinia'

  The primary function for defining new Pinia stores in a declarative way.
• storeToRefs
  wrong:

  import { toRefs } from 'vue'

  correct:

  import { storeToRefs } from 'pinia'

  A Pinia utility to convert state properties from a store into reactive references, useful for destructuring in template-bound components.

Quickstart

Demonstrates how to add the plugin to a Vue CLI project and then create and use a basic Pinia store.

vue add vue-cli-plugin-pinia

// src/main.ts (or main.js)
import { createApp } from 'vue';
import { createPinia } from 'pinia';
import App from './App.vue';

const app = createApp(App);
const pinia = createPinia();

app.use(pinia);
app.mount('#app');

// src/stores/counter.ts (example store)
import { defineStore } from 'pinia';

export const useCounterStore = defineStore('counter', {
  state: () => ({
    count: 0,
    name: 'MyCounter',
  }),
  getters: {
    doubleCount: (state) => state.count * 2,
  },
  actions: {
    increment() {
      this.count++;
    },
  },
});

// src/components/CounterDisplay.vue (example usage in a component)
<template>
  <div>
    <p>Count: {{ counter.count }}</p>
    <p>Double Count: {{ counter.doubleCount }}</p>
    <button @click="counter.increment()">Increment</button>
  </div>
</template>

<script setup lang="ts">
import { useCounterStore } from '../stores/counter';
// import { storeToRefs } from 'pinia'; // Use storeToRefs if you need to destructure state properties reactively

const counter = useCounterStore();
</script>