Vue Global API

0.4.1 · active · verified Sun Apr 19

vue-global-api is a utility package for Vue 3 that makes Composition API functions globally available within `<script setup>` contexts, removing the need for explicit imports of `ref`, `computed`, `watch`, and other common APIs from 'vue'. This aims to reduce boilerplate and streamline the development experience, aligning with the macro-like availability of `defineProps` and `defineEmits`. The current stable version is `0.4.1`, and it's maintained by Anthony Fu, a prominent Vue core team member. While Vue itself doesn't have a fixed release cycle for minor versions (typically 3-6 months), this package tends to follow its development. Key differentiators include its granular control over which APIs are global via sub-module imports (e.g., `vue-global-api/ref` or `vue-global-api/reactivity`), and its specific ESLint configuration to prevent 'no-undef' errors. It is designed for bundler-based Vue applications and offers an alternative to importing APIs from 'vue' in every single-file component.

Common errors

```
ESLint: 'ref' is not defined. (no-undef)
```
cause ESLint is not aware that `ref` (or other global APIs) are globally available through `vue-global-api`.

fix Add `'vue-global-api'` to the `extends` array in your `.eslintrc.js` (or `.eslintrc.cjs`) configuration file. For example: `extends: ['plugin:vue/vue3-recommended', 'vue-global-api']`.
```
TypeError: ref is not a function
```
cause The `vue-global-api` package was either not imported, or it was imported *after* a component that attempted to use a global API.

fix Ensure `import 'vue-global-api'` is present in your application's entry file (e.g., `main.ts`) and that it executes *before* any Vue components are initialized. Verify Vue 3 is correctly installed and configured.
```
Module not found: Error: Can't resolve 'vue-global-api'
```
cause The `vue-global-api` package is not installed or incorrectly referenced in `package.json`.

fix Install the package using `npm install vue-global-api` or `yarn add vue-global-api`. Check `package.json` to confirm it's listed in `dependencies`.

Warnings

gotcha Failing to configure ESLint will result in 'no-undef' errors for globally exposed APIs.
Fix: Extend your ESLint configuration with `'vue-global-api'` (or specific sub-configs like `'vue-global-api/reactivity'`). Refer to the package's documentation for exact syntax.
gotcha The global registration import (`import 'vue-global-api'`) must occur *before* any Vue components are processed that utilize these global APIs.
Fix: Ensure the `import 'vue-global-api'` statement is placed early in your main entry file (e.g., `main.ts` or `main.js`), typically right after Vue's `createApp` import.
gotcha This package is not designed for direct CDN usage. For browser environments without a bundler, the recommended approach is to manually assign Vue's global object to `window` (e.g., `Object.assign(window, Vue)`).
Fix: If using a CDN, avoid this package and instead use `Object.assign(window, Vue)` after loading the Vue global build. This package is specifically for module-based bundler environments.
gotcha Do not attempt to import named exports directly from `vue-global-api` or its submodules (e.g., `import { ref } from 'vue-global-api'`). The package works by side-effect global registration.
Fix: Use the side-effect import syntax: `import 'vue-global-api'` or `import 'vue-global-api/ref'`.

Install

npm install vue-global-api npm
yarn add vue-global-api yarn
pnpm add vue-global-api pnpm

Imports

Global Registration
wrong:
```
import { ref } from 'vue-global-api'
```
correct:
```
import 'vue-global-api'
```
This is a side-effect import that globally registers all common Composition APIs. It must be imported in your main entry file (e.g., `main.ts`) before any Vue components are used. Do not try to import named exports from the root package.
Specific API Registration
wrong:
```
const ref = require('vue-global-api/ref')
```
correct:
```
import 'vue-global-api/ref'
```
For fine-grained control, you can import individual APIs as side effects. This is primarily an ESM-only library, used in modern Vue setups (Vite, webpack with ESM support).
Collection Registration
wrong:
```
import { watch } from 'vue-global-api/reactivity'
```
correct:
```
import 'vue-global-api/reactivity'
```
Collections like 'reactivity' (for `ref`, `computed`, `watch`) or 'lifecycle' (for `onMounted`, etc.) can also be imported as side effects. Like other imports from this package, they don't export values directly, but rather register them globally.

Quickstart

This quickstart demonstrates the core usage of `vue-global-api` by registering all common Composition APIs globally in `main.ts` and then using them directly in a Vue component without explicit imports. It also includes the necessary ESLint configuration.

/* main.ts */
import { createApp } from 'vue'
import App from './App.vue'

// Globally register all common Vue Composition APIs
// This must be imported BEFORE any Vue components that use these globals
import 'vue-global-api'

createApp(App).mount('#app')

/* App.vue */
<script setup lang="ts">
// No need to import ref, computed, watch, etc.
// They are globally available thanks to 'vue-global-api'
const counter = ref(0)

const doubled = computed(() => counter.value * 2)

watch(doubled, (v) => {
  console.log('Doubled value changed:', v)
})

function increment() {
  counter.value++
}
</script>

<template>
  <div>
    <h1>Counter: {{ counter }}</h1>
    <h2>Doubled: {{ doubled }}</h2>
    <button @click="increment">Increment</button>
  </div>
</template>

<style scoped>
/* Your styles here */
</style>

/* .eslintrc.js (or .eslintrc.cjs) */
module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-recommended',
    'vue-global-api' // Extend the ESLint config for global APIs
    // Or for fine-grain control:
    // 'vue-global-api/reactivity'
  ]
  // ... other ESLint configurations
}

view raw JSON →