Vue Global Config

Common errors

• TypeError: app.use expects an install function or an object with an install method

  cause Attempting to pass a raw Vue component directly to `app.use()` (or `Vue.use()` in Vue 2) instead of the plugin returned by `createGlobalConfig`.
  fix Wrap your component and global configuration with `createGlobalConfig`: `app.use(createGlobalConfig(YourComponent, { ... }))`.

• Property 'someProp' was accessed during render but is not defined on instance.

  cause A global prop was defined but the target component does not declare it in its `props` option, or there's a mismatch in naming convention (e.g., camelCase vs. kebab-case).
  fix Ensure the target component explicitly declares all global props it intends to consume in its `props` option. Check `options.camelizePropNames` in `createGlobalConfig` options for naming consistency.

• The @vnode-mounted hook is deprecated in Vue 3.4 and later and will not function as expected.

  cause Using the `@vnode-mounted` or `@vnodeMounted` hook syntax for global component hooks in a Vue 3.4+ environment.
  fix Update your global configuration to remove these deprecated hooks, as they are no longer supported in Vue 3.4 and later.

Warnings

• breaking The support for `@vnode-mounted` and `@vnodeMounted` hooks was removed in Vue 3.4. Applications upgrading to Vue 3.4 or later using these specific global hooks will need to refactor them.
  Fix: Remove or replace `@vnode-mounted` and `@vnodeMounted` hook definitions in your global configuration when targeting Vue 3.4+.
• breaking The global `props` option structure changed significantly. `props` were moved into `options.props`, and a new `options.camelizePropNames` option was introduced to control prop name camelization.
  Fix: Update your global configuration object: move any top-level `props` definitions to `options.props` and review the `options.camelizePropNames` behavior for prop name resolution.
• gotcha The README examples for `app.use(YourComponent, config)` are misleading. The `createGlobalConfig` function must be explicitly called to generate the plugin, i.e., `app.use(createGlobalConfig(YourComponent, config))`.
  Fix: Always wrap your component and global configuration with `createGlobalConfig()` when using the `app.use()` or `Vue.use()` plugin approach.
• gotcha Vue 2 and Vue 3 use different naming conventions for component lifecycle hooks and event listeners. For instance, Vue 2 uses `@hook:mounted` while Vue 3 uses `@vue:mounted` for component hooks.
  Fix: Ensure you use the correct hook/listener syntax for your target Vue version. For Vue 2: `@hook:lifecycleEvent` and kebab-case for event listeners. For Vue 3: `@vue:lifecycleEvent` and camelCase or kebab-case for event listeners, depending on configuration.

Install

• npm install vue-global-config npm
• yarn add vue-global-config yarn
• pnpm add vue-global-config pnpm

Imports

• createGlobalConfig
  wrong:

  const createGlobalConfig = require('vue-global-config');

  correct:

  import { createGlobalConfig } from 'vue-global-config';

  This function is used to create the Vue plugin that applies global configuration to a specific component. Use it with `app.use()` in Vue 3 or `Vue.use()` in Vue 2. The package is primarily ESM-first.
• ConfigProvider
  wrong:

  const { ConfigProvider } = require('vue-global-config');

  correct:

  import { ConfigProvider } from 'vue-global-config';

  This is a Vue component that allows declarative configuration within your template, similar to built-in Vue components or other UI frameworks' config providers.
• ConfigOptions

  import type { ConfigOptions } from 'vue-global-config';

  Type definition for the configuration object passed to `createGlobalConfig` or `ConfigProvider`.

Quickstart

Demonstrates applying global props, attributes, listeners, hooks, and a scoped slot to a `MyButton` component using `createGlobalConfig` in a Vue 3 application. It includes both default and overridden component usage.

import { createApp, h, defineComponent } from 'vue';
import { createGlobalConfig } from 'vue-global-config';

// Define a sample Vue component that can receive global configurations
const MyButton = defineComponent({
  props: { title: String, data: Array },
  emits: ['leftCheckChange'],
  mounted() {
    console.log('Component Mounted:', this.title);
    // Trigger a global listener via emit
    this.$emit('leftCheckChange');
  },
  render() {
    // Access default slot, potentially from global configuration
    const defaultSlot = this.$slots.default ? this.$slots.default({ option: { label: 'Default Slot Item' } }) : 'Default Content';
    return h('button', 
      { 
        // Global attributes can be accessed via $attrs
        onClick: () => console.log('Button clicked'),
        'data-custom': this.$attrs['data-custom'] 
      },
      [
        // Render global prop if available, otherwise fallback
        h('span', this.title || 'No Title'),
        // Render global data if available
        this.data?.map(item => h('li', item.label)),
        h('div', defaultSlot)
      ]
    );
  },
});

const app = createApp({
  template: `
    <div id="app">
      <!-- MyButton without local props, relying on global config -->
      <MyButton />
      <!-- MyButton with local prop, overriding global config for 'title' -->
      <MyButton title="Override Title" />
    </div>
  `,
});

// Apply global configuration to MyButton using the createGlobalConfig plugin
app.use(createGlobalConfig(MyButton, {
  // Global Prop: 'title' will be passed as a prop to MyButton instances
  'title': 'Global Button Title',

  // Global Attr: 'data-custom' will be available via $attrs on MyButton instances
  'data-custom': 'Global Custom Data',
  
  // Global Listener: '@leftCheckChange' will be triggered when MyButton emits it
  '@leftCheckChange': function () {
    console.log('Global LeftCheckChange triggered by MyButton');
  },

  // Global Hook: '@vue:mounted' will run when any MyButton instance mounts
  '@vue:mounted': function () {
    console.log('Global Mounted hook for MyButton');
  },

  // Global Scoped Slot: A default scoped slot provided globally
  '#default': ({ option }) => h('em', undefined, `${option.label} (From Global Scoped Slot)`)
}));

app.mount('#app');