Vue Confetti Component

Common errors

• ReferenceError: window is not defined

  cause Attempting to use `vue-confetti` in a server-side rendering (SSR) environment without marking it as client-only.
  fix Ensure `vue-confetti` is loaded only on the client. In Nuxt, configure it in `nuxt.config.js` as `{ src: '~/plugins/vue-confetti.js', mode: 'client' }`.

• Property '$confetti' does not exist on type 'ComponentPublicInstance<...>' or similar TypeScript error.

  cause TypeScript does not automatically know about globally injected properties like `$confetti` unless explicitly declared.
  fix Extend Vue's `ComponentCustomProperties` interface via declaration merging. Create a `shims-vue-confetti.d.ts` file: ```typescript import 'vue'; declare module 'vue' { interface ComponentCustomProperties { $confetti: { start: (options?: any) => void; stop: () => void; update: (options?: any) => void; }; } } ``` Alternatively, cast `this` to `any` in component methods: `(this as any).$confetti.start()`.

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use ESM `import` syntax in a CommonJS-only environment (e.g., older Node.js or specific build configurations), or vice-versa with `require()` in an ESM module.
  fix Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` for Node.js) or use a bundler like Webpack/Vite that transpiles ESM to CJS if targeting older environments. For `vue-confetti`, stick to `import` statements as it's designed for modern module systems.

Warnings

• gotcha vue-confetti relies on browser globals (like `window`) and is not designed for server-side rendering (SSR). It will cause errors if rendered on the server without proper client-only configuration.
  Fix: For Nuxt.js, register the plugin with `mode: 'client'` in your `nuxt.config.js` or `nuxt.config.ts`. For other SSR setups, ensure the plugin is only loaded or initialized on the client side.
• gotcha The method of registering Vue plugins changed significantly between Vue 2 and Vue 3. Using `Vue.use()` for a Vue 3 application or `app.use()` for a Vue 2 application will result in errors.
  Fix: For Vue 2, use `import Vue from 'vue'; Vue.use(VueConfetti);`. For Vue 3, use `import { createApp } from 'vue'; const app = createApp(App); app.use(VueConfetti);`.
• gotcha Calling `$confetti.update()` only configures the confetti properties; it does not automatically start the confetti animation. Developers often expect `update` to also trigger the effect.
  Fix: Always call `$confetti.start()` explicitly after `$confetti.update()` if you intend to immediately begin a confetti shower with the new settings.

Install

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

Imports

• VueConfetti
  wrong:

  import { VueConfetti } from 'vue-confetti';

  correct:

  import VueConfetti from 'vue-confetti';

  This is the default export containing the plugin object. For Vue 2, use `Vue.use(VueConfetti)`. For Vue 3, use `app.use(VueConfetti)`.
• Vue.use() (Vue 2)
  wrong:

  Vue.use(VueConfetti); // Missing 'import Vue from "vue"'

  correct:

  import Vue from 'vue';
  import VueConfetti from 'vue-confetti';
  Vue.use(VueConfetti);

  The traditional way to register Vue 2 plugins globally on the Vue constructor.
• app.use() (Vue 3)
  wrong:

  Vue.use(VueConfetti); // For Vue 3, use `app.use()` on the app instance.

  correct:

  import { createApp } from 'vue';
  import VueConfetti from 'vue-confetti';
  const app = createApp(App);
  app.use(VueConfetti);

  The modern way to register Vue 3 plugins on a specific application instance.

Quickstart

This quickstart demonstrates how to install and use vue-confetti in a Vue 3 application with TypeScript, showcasing basic confetti triggering, stopping, and customized effects.

// main.ts or main.js
import { createApp } from 'vue';
import App from './App.vue';
import VueConfetti from 'vue-confetti';

const app = createApp(App);
app.use(VueConfetti);
app.mount('#app');

// App.vue
<template>
  <main>
    <h1>Confetti Time!</h1>
    <button @click="start">Start Confetti</button>
    <button @click="stop">Stop Confetti</button>
    <button @click="love">Show Some Love (Hearts & Circles)</button>
    <p>Click the buttons to trigger confetti effects.</p>
  </main>
</template>

<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  methods: {
    start(): void {
      // Basic confetti with default settings
      (this as any).$confetti.start();
    },
    stop(): void {
      (this as any).$confetti.stop();
    },
    love(): void {
      // Custom confetti with hearts and circles, then start and stop after 3s
      (this as any).$confetti.update({
        particles: [
          { type: 'heart', size: 12 },
          { type: 'circle', size: 8 }
        ],
        defaultColors: [
          'red', 'pink', '#FF69B4', '#E0BBE4', '#957DAD'
        ],
        particlesPerFrame: 5
      });
      (this as any).$confetti.start(); // Must call start() after update()
      setTimeout(() => (this as any).$confetti.stop(), 3000);
    }
  }
});
</script>

<style>
main {
  font-family: Avenir, Helvetica, Arial, sans-serif;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-align: center;
  color: #2c3e50;
  margin-top: 60px;
}
button {
  margin: 0 10px;
  padding: 10px 20px;
  font-size: 16px;
  cursor: pointer;
}
</style>