doc: improve confetti tutorial

Author: harlan-zw

docs/content/docs/1.getting-started/3.confetti-tutorial.md

@@ -88,7 +88,9 @@ useScriptNpm({
   file: 'dist/js-confetti.browser.js',
   version: '0.12.0',
   // tell useScript how to resolve the third-party script
-  use: () => typeof window.JSConfetti !== 'undefined' && new window.JSConfetti()
+  use() {
+    return { JSConfetti: window.JSConfetti }
+  },
 })
 </script>
 ```
@@ -97,35 +99,44 @@ useScriptNpm({
 
 Now that we have a way to resolve the third-party script API, we can start using it.
 
-To use the API we have a couple of options proxied functions or awaiting the script load.
+The `js-confetti` library requires us to instantiate a new instance of the `JSConfetti` class everytime it's used,
+the most compatible way to handle this is to for the script to load explicitly.
 
-See the [Understanding proxied functions](/docs/guides/script-loading#Understanding-proxied-functions) section for more information.
+However, we can also make use of [proxied functions](/docs/guides/script-loading#Understanding-proxied-functions) if we prefer an easier to use API. Note that this will break
+when switching between pages as `new window.JSConfetti()` needs to be called between pages.
 
 ::code-group
 
-```vue [Proxy Usage]
+```vue [Explicit script Load]
 <script setup lang="ts">
-const { addConfetti } = useScriptNpm({
+const { $script } = useScriptNpm({
   packageName: 'js-confetti',
   file: 'dist/js-confetti.browser.js',
   version: '0.12.0',
-  use: () => typeof window.JSConfetti !== 'undefined' && new window.JSConfetti()
+  use() {
+    return { JSConfetti: window.JSConfetti }
+  },
+})
+onMounted(() => {
+  $script.then(({ JSConfetti }) => {
+    // using the real API instance
+    const confetti = new JSConfetti()
+    confetti.addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
+  })
 })
-// using the proxied function that will be called when the script is loaded
-addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
 </script>
 ```
 
-```vue [Await Load]
+```vue [Proxy Functions]
 <script setup lang="ts">
-const { $script } = useScriptNpm({
+const { addConfetti } = useScriptNpm({
   packageName: 'js-confetti',
   file: 'dist/js-confetti.browser.js',
   version: '0.12.0',
   use: () => typeof window.JSConfetti !== 'undefined' && new window.JSConfetti()
 })
-$script.then(({ addConfetti }) => {
-  // using the real API instance
+onMounted(() => {
+  // just works
   addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
 })
 </script>
@@ -144,23 +155,34 @@ You can use the generic from the `useScriptNpm` composable to add types to the s
 ```vue [app.vue]
 <script setup lang="ts">
 export interface JSConfettiApi {
-  addConfetti: (options?: { emojis: string[] }) => void
+  JSConfetti: { 
+    new (): {
+      addConfetti: (options?: { emojis: string[] }) => void
+    } 
+  }
 }
 
 declare global {
-  interface Window {
-    JSConfetti: { new (): JSConfettiApi }
-  }
+  interface Window extends JSConfettiApi {}
 }
 
-const { addConfetti } = useScriptNpm<JSConfettiApi>({
+const { $script } = useScriptNpm<JSConfettiApi>({
   packageName: 'js-confetti',
   file: 'dist/js-confetti.browser.js',
   version: '0.12.0',
-  use: () => typeof window.JSConfetti !== 'undefined' && new window.JSConfetti()
+  scriptOptions: {
+    use() {
+      return { JSConfetti: window.JSConfetti }
+    },
+  },
+})
+onMounted(() => {
+  $script.then(({ JSConfetti }) => {
+    const confetti = new JSConfetti()
+    // fully typed!
+    confetti.addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
+  })
 })
-// fully typed!
-addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
 </script>
 ```
 
@@ -173,15 +195,19 @@ In this example we'll combine the [useScriptTriggerElement](/docs/api/use-script
 ```vue [app.vue]
 <script setup lang="ts">
 const mouseOverEl = ref<HTMLElement>()
-const { addConfetti } = useScriptNpm<{ addConfetti: (options?: { emojis: string[] }) => void }>({
-  packageName: 'js-confetti',
-  file: 'dist/js-confetti.browser.js',
-  version: '0.12.0',
+const { $script } = useScriptNpm({
+  // ..
   scriptOptions: {
     trigger: useScriptTriggerElement({ trigger: 'mouseover', el: mouseOverEl })
   }
 })
-addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
+// ..
+onMounted(() => {
+  $script.then(({ JSConfetti }) => {
+    const confetti = new JSConfetti()
+    confetti.addConfetti({ emojis: ['L', 'O', 'A', 'D', 'E', 'D'] })
+  })
+})
 </script>
 
 <template>
@@ -199,15 +225,13 @@ To bundle the script, you can use the `bundle` option.
 
 ```vue [app.vue]
 <script setup lang="ts">
-const { addConfetti } = useScriptNpm<{ addConfetti: (options?: { emojis: string[] }) => void }>({
-  packageName: 'js-confetti',
-  file: 'dist/js-confetti.browser.js',
-  version: '0.12.0',
+const { $script } = useScriptNpm({
+  // ...
   scriptOptions: {
     bundle: true
   }
 })
-addConfetti({ emojis: ['🌈', '⚡️', '💥', '✨', '💫', '🌸'] })
+// ..
 </script>
 ```
 
@@ -217,6 +241,4 @@ You should see the script loaded in from your apps server.
 
 In this tutorial, you learned how to load the `js-confetti` script using the `useScriptNpm` registry script.
 
-To learn more about the specific concepts you explored, check out the following documentation:
-- [Script Loading Concepts](/docs/guides/script-loading)
-- [Bundling](/docs/guides/bundling)
+To learn more about the specific concepts you explored, check out the documentation for [Key concepts](/docs/guides/key-concepts).

playground/pages/npm/js-confetti.vue

@@ -1,21 +1,41 @@
 <script lang="ts" setup>
-import { ref, useScriptTriggerElement, useScriptNpm } from '#imports'
+import { ref, useScriptTriggerElement, useScriptNpm, onMounted } from '#imports'
 
 const mouseOverEl = ref()
-const { addConfetti } = useScriptNpm<JSConfettiApi>({
+export interface JSConfettiApi {
+  JSConfetti: {
+    new (): {
+      addConfetti: (options?: { emojis: string[] }) => void
+    }
+  }
+}
+
+declare global {
+  interface Window extends JSConfettiApi {}
+}
+
+const { $script } = useScriptNpm<JSConfettiApi>({
   packageName: 'js-confetti',
   file: 'dist/js-confetti.browser.js',
   version: '0.12.0',
   scriptOptions: {
     trigger: useScriptTriggerElement({ trigger: 'mouseover', el: mouseOverEl }),
-    bundle: true,
     use() {
-      return typeof window.JSConfetti !== 'undefined' && new window.JSConfetti()
+      return { JSConfetti: window.JSConfetti }
     },
   },
 })
 
-addConfetti({ emojis: ['L', 'O', 'A', 'D', 'E', 'D'] })
+function addConfetti(options: { emojis: string[] }) {
+  $script.then(({ JSConfetti }) => {
+    const confetti = new JSConfetti()
+    confetti.addConfetti(options)
+  })
+}
+
+onMounted(() => {
+  addConfetti({ emojis: ['L', 'O', 'A', 'D', 'E', 'D'] })
+})
 </script>
 
 <template>