{"id":12546,"library":"vue-plugin-load-script","title":"Vue Plugin Load Script","description":"vue-plugin-load-script is a Vue plugin designed for dynamically injecting and removing remote JavaScript files into a web application. It is fully compatible with Vue 3, with the current stable version being 2.1.1. For Vue 2 compatibility, users need to install version 1.x.x. The plugin offers both Composition API (`loadScript`, `unloadScript`) and Options API (`this.$loadScript`, `this.$unloadScript`) interfaces, providing flexibility for different project architectures. Its primary utility lies in integrating third-party SDKs or external libraries like Google Maps, Stripe.js, or analytics scripts that require dynamic loading after the initial application render. The project maintains an active status with updates typically tied to Vue major version releases or critical bug fixes, rather than a fixed release schedule. A key differentiator is its straightforward API for managing the lifecycle of external scripts within a Vue application.","status":"active","version":"2.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/tserkov/vue-plugin-load-script","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-plugin-load-script","lang":"bash","label":"npm"},{"cmd":"yarn add vue-plugin-load-script","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-plugin-load-script","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is a default export, intended for global plugin registration via `app.use()` in Vue 3 applications. It is not a named export.","wrong":"import { LoadScript } from 'vue-plugin-load-script';","symbol":"LoadScript","correct":"import LoadScript from 'vue-plugin-load-script';"},{"note":"This is a named export for use with Vue 3's Composition API. It should be imported directly and used as a function within `setup()` or other composables.","wrong":"import loadScript from 'vue-plugin-load-script';","symbol":"loadScript","correct":"import { loadScript } from 'vue-plugin-load-script';"},{"note":"A named export for the Composition API, used to remove scripts previously loaded with `loadScript`. It requires the exact same URL that was used for loading.","wrong":"import unloadScript from 'vue-plugin-load-script';","symbol":"unloadScript","correct":"import { unloadScript } from 'vue-plugin-load-script';"}],"quickstart":{"code":"import { createApp, defineComponent, onMounted } from 'vue';\nimport LoadScript, { loadScript } from 'vue-plugin-load-script';\n\nconst RootComponent = defineComponent({\n  template: `\n    <div id=\"app\">\n      <h1>Script Loader Example</h1>\n      <p>Check console for script load status.</p>\n      <div id=\"map\" style=\"height: 300px; width: 100%;\"></div>\n    </div>\n  `,\n  setup() {\n    // Replace with your actual Google Maps API key or use environment variable\n    const GOOGLE_MAPS_API_KEY = process.env.VUE_APP_GOOGLE_MAPS_API_KEY ?? 'YOUR_API_KEY_HERE';\n    const googleMapsUrl = `https://maps.googleapis.com/maps/api/js?key=${GOOGLE_MAPS_API_KEY}&callback=initMap`;\n\n    // Define a global callback function required by Google Maps API\n    (window as any).initMap = () => {\n      console.log('Google Maps API script loaded and initMap callback executed!');\n      // Example: Initialize a basic map\n      const mapElement = document.getElementById('map');\n      if (mapElement && (window as any).google?.maps?.Map) {\n        new (window as any).google.maps.Map(mapElement, {\n          center: { lat: -34.397, lng: 150.644 },\n          zoom: 8,\n        });\n        console.log('Google Map initialized.');\n      }\n    };\n\n    onMounted(async () => {\n      console.log('Attempting to load Google Maps script...');\n      try {\n        await loadScript(googleMapsUrl);\n        console.log('Google Maps script load promise resolved.');\n        // initMap will be called automatically by the Google Maps script once loaded\n      } catch (error) {\n        console.error('Failed to load Google Maps script:', error);\n      }\n    });\n\n    return {};\n  },\n});\n\nconst app = createApp(RootComponent);\napp.use(LoadScript); // Register the plugin globally for Options API access ($loadScript)\n\napp.mount('#app');","lang":"typescript","description":"This quickstart demonstrates how to globally register the plugin for Options API usage and then dynamically load an external script (e.g., Google Maps API) using the Composition API's `loadScript` function within a component's `onMounted` hook."},"warnings":[{"fix":"For Vue 2 projects, install `vue-plugin-load-script@^1.x.x`. For Vue 3 projects, ensure you are on `vue-plugin-load-script@^2.x.x` and have Vue 3 installed.","message":"Version 2.x.x and above of `vue-plugin-load-script` are exclusively designed for Vue 3. Projects using Vue 2 must use version 1.x.x.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Always store the script URL in a constant or variable and reuse it for both `loadScript` and `unloadScript` calls to ensure consistency.","message":"When using `unloadScript` or `this.$unloadScript`, the URL passed must be an exact match (case-sensitive and including query parameters) to the URL originally used to load the script. Any deviation will prevent the script from being found and unloaded.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always include `.catch()` or `try/catch` blocks when calling `loadScript` to handle potential errors gracefully and provide user feedback. Verify script URLs and ensure they are publicly accessible.","message":"Script loading failures can occur due to network issues, invalid URLs, CORS restrictions, or if the script itself encounters an error. The `loadScript` promise will reject in these scenarios.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For Composition API, import and use the named exports `loadScript` and `unloadScript` directly: `import { loadScript, unloadScript } from 'vue-plugin-load-script';`. For Options API, ensure the plugin is registered with `app.use(LoadScript)`.","message":"The `this.$loadScript` and `this.$unloadScript` methods are only available within the context of a Vue component using the Options API, or if the plugin is globally registered. They cannot be directly accessed in Vue 3's Composition API `setup()` function without explicitly using `getCurrentInstance()` and `proxy`.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For Vue 2 projects, install `vue-plugin-load-script@^1.x.x`. For Vue 3, ensure you are creating your app with `createApp` from 'vue'.","cause":"Attempting to use `app.use` with a Vue 2 application setup while `vue-plugin-load-script` version 2+ is installed.","error":"TypeError: app.use is not a function"},{"fix":"Add `import { loadScript } from 'vue-plugin-load-script';` to your script where `loadScript` is used.","cause":"Using `loadScript` (Composition API style) without importing it as a named export from the package.","error":"ReferenceError: loadScript is not defined"},{"fix":"Within `setup()`, use the named import `loadScript`: `import { loadScript } from 'vue-plugin-load-script';` then call `loadScript(...)`. If in an Options API component, ensure the plugin is registered with `app.use(LoadScript)`.","cause":"Attempting to use `this.$loadScript` within a Vue 3 Composition API `setup()` function or outside of a component context where the plugin instance isn't available.","error":"TypeError: this.$loadScript is not a function"},{"fix":"Verify the URL used for `unloadScript` is identical, including query parameters, to the URL used for `loadScript`. Store the URL in a constant to prevent inconsistencies.","cause":"The URL passed to `unloadScript` (or `this.$unloadScript`) does not exactly match a previously loaded script's URL.","error":"Error: Script couldn't be found to unload; make sure it was loaded and that you passed the same URL"}],"ecosystem":"npm"}