├── .editorconfig ├── .eslintignore ├── .eslintrc ├── .gitignore ├── .npmrc ├── .nuxtrc ├── CHANGELOG.md ├── LICENSE ├── README.md ├── docs ├── .eslintignore ├── .eslintrc.cjs ├── .gitignore ├── .npmrc ├── .nuxtrc ├── README.md ├── app.config.ts ├── content │ ├── 0.index.md │ ├── 1.getting-started │ │ ├── 1.setup.md │ │ ├── 2.configuration.md │ │ ├── 3.faq.md │ │ └── _dir.yml │ └── 2.components │ │ ├── 1.nuxt-particles.md │ │ └── _dir.yml ├── nuxt.config.ts ├── package.json ├── pnpm-lock.yaml ├── public │ ├── cover.png │ └── favicon.ico ├── renovate.json ├── tokens.config.ts └── tsconfig.json ├── package.json ├── playground ├── app.vue ├── nuxt.config.ts ├── package.json ├── server │ └── tsconfig.json └── tsconfig.json ├── pnpm-lock.yaml ├── renovate.json ├── src ├── module.ts └── runtime │ ├── components │ └── NuxtParticles.vue │ ├── lib │ └── loaders.ts │ └── plugins │ └── particle-loader.client.ts └── tsconfig.json /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*] 4 | indent_size = 2 5 | indent_style = space 6 | end_of_line = lf 7 | charset = utf-8 8 | trim_trailing_whitespace = true 9 | insert_final_newline = true 10 | 11 | [*.md] 12 | trim_trailing_whitespace = false 13 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | dist 2 | node_modules 3 | -------------------------------------------------------------------------------- /.eslintrc: -------------------------------------------------------------------------------- 1 | { 2 | "root": true, 3 | "extends": ["@nuxt/eslint-config"] 4 | } 5 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | node_modules 3 | 4 | # Logs 5 | *.log* 6 | 7 | # Temp directories 8 | .temp 9 | .tmp 10 | .cache 11 | 12 | # Yarn 13 | **/.yarn/cache 14 | **/.yarn/*state* 15 | 16 | # Generated dirs 17 | dist 18 | 19 | # Nuxt 20 | .nuxt 21 | .output 22 | .data 23 | .vercel_build_output 24 | .build-* 25 | .netlify 26 | 27 | # Env 28 | .env 29 | 30 | # Testing 31 | reports 32 | coverage 33 | *.lcov 34 | .nyc_output 35 | 36 | # VSCode 37 | .vscode/* 38 | !.vscode/settings.json 39 | !.vscode/tasks.json 40 | !.vscode/launch.json 41 | !.vscode/extensions.json 42 | !.vscode/*.code-snippets 43 | 44 | # Intellij idea 45 | *.iml 46 | .idea 47 | 48 | # OSX 49 | .DS_Store 50 | .AppleDouble 51 | .LSOverride 52 | .AppleDB 53 | .AppleDesktop 54 | Network Trash Folder 55 | Temporary Items 56 | .apdisk 57 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | shamefully-hoist=true -------------------------------------------------------------------------------- /.nuxtrc: -------------------------------------------------------------------------------- 1 | imports.autoImport=false 2 | typescript.includeWorkspace=true 3 | -------------------------------------------------------------------------------- /CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | 4 | ## v0.3.0 5 | 6 | [compare changes](https://github.com/Joepocalyptic/nuxt-particles/compare/v0.2.0...v0.3.0) 7 | 8 | ### 🩹 Fixes 9 | 10 | - Opt in to `import.meta.*` properties ([5e07c8a](https://github.com/Joepocalyptic/nuxt-particles/commit/5e07c8a)) 11 | - Use proper import ([6a7f898](https://github.com/Joepocalyptic/nuxt-particles/commit/6a7f898)) 12 | 13 | ### 🏡 Chore 14 | 15 | - Require Nuxt >= 3.7.0 ([7ab3d1a](https://github.com/Joepocalyptic/nuxt-particles/commit/7ab3d1a)) 16 | 17 | ### ❤️ Contributors 18 | 19 | - Joey Pereira ([@Joepocalyptic](http://github.com/Joepocalyptic)) 20 | - Daniel Roe ([@danielroe](http://github.com/danielroe)) 21 | 22 | ## v0.2.0 23 | 24 | [compare changes](https://github.com/Joepocalyptic/nuxt-particles/compare/v0.1.5...v0.2.0) 25 | 26 | ### 🚀 Enhancements 27 | 28 | - Use tsparticles v3 ([6286ded](https://github.com/Joepocalyptic/nuxt-particles/commit/6286ded)) 29 | 30 | ### 📖 Documentation 31 | 32 | - Fix package specifier ([239b091](https://github.com/Joepocalyptic/nuxt-particles/commit/239b091)) 33 | 34 | ### 🏡 Chore 35 | 36 | - Update README.md ([1be6b87](https://github.com/Joepocalyptic/nuxt-particles/commit/1be6b87)) 37 | 38 | ### ❤️ Contributors 39 | 40 | - Joey Pereira ([@Joepocalyptic](http://github.com/Joepocalyptic)) 41 | 42 | ## v0.1.5 43 | 44 | [compare changes](https://undefined/undefined/compare/v0.1.4...v0.1.5) 45 | 46 | ### 🏡 Chore 47 | 48 | - Add renovate.json (560a936) 49 | 50 | ### ❤️ Contributors 51 | 52 | - Joey Pereira 53 | 54 | ## v0.1.4 55 | 56 | [compare changes](https://undefined/undefined/compare/v0.1.3...v0.1.4) 57 | 58 | ### 🏡 Chore 59 | 60 | - Clean up docs (9f1c6da) 61 | 62 | ### ❤️ Contributors 63 | 64 | - Joey Pereira 65 | 66 | ## v0.1.3 67 | 68 | [compare changes](https://undefined/undefined/compare/v0.1.2...v0.1.3) 69 | 70 | ### 🏡 Chore 71 | 72 | - Clean up (6bfdec8) 73 | - Clean up (0826ac3) 74 | 75 | ### ❤️ Contributors 76 | 77 | - Joey Pereira 78 | 79 | ## v0.1.2 80 | 81 | [compare changes](https://undefined/undefined/compare/v0.1.1...v0.1.2) 82 | 83 | ### 🩹 Fixes 84 | 85 | - Update docs metadata (f6a32f9) 86 | 87 | ### 🏡 Chore 88 | 89 | - Fix docs prerendering (16462be) 90 | - Add license (95f8b8d) 91 | 92 | ### ❤️ Contributors 93 | 94 | - Joey Pereira 95 | 96 | ## v0.1.1 97 | 98 | 99 | ### 🏡 Chore 100 | 101 | - Initial commit (729e9b3) 102 | - Update README.md (8fc40c2) 103 | - Add defu dependency (a5a41a0) 104 | - Fix defu dependency (f6f6d32) 105 | 106 | ### ❤️ Contributors 107 | 108 | - Joey Pereira 109 | 110 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Joey Pereira 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Nuxt Particles 2 | 3 | [![npm version][npm-version-src]][npm-version-href] 4 | [![npm downloads][npm-downloads-src]][npm-downloads-href] 5 | [![License][license-src]][license-href] 6 | [![Nuxt][nuxt-src]][nuxt-href] 7 | 8 | Run lightweight, heavily customizable particle simulations in your Nuxt project with tsParticles. 9 | 10 | - [📖  Documentation](https://nuxt-particles.joeypereira.dev) 11 | - [✨  Release Notes](/CHANGELOG.md) 12 | - [🏀 Online playground](https://stackblitz.com/github/Joepocalyptic/nuxt-particles?file=playground%2Fapp.vue) 13 | 14 | ## Features 15 | 16 | - Built for **Nuxt 3** 17 | - **Lazy loading** by default 18 | - Built-in full, slim, and basic bundles, or 19 | - Use a custom bundle for extra performance 20 | - All with just **one component**! 21 | 22 | ## Quick Setup 23 | 24 | 1. Add the `nuxt-particles` dependency to your project 25 | 26 | ```bash 27 | # Using pnpm 28 | pnpm add -D nuxt-particles 29 | 30 | # Using yarn 31 | yarn add --dev nuxt-particles 32 | 33 | # Using npm 34 | npm install --save-dev nuxt-particles 35 | ``` 36 | 37 | 2. Add `nuxt-particles` to the `modules` section of `nuxt.config.ts` 38 | 39 | ```js 40 | export default defineNuxtConfig({ 41 | modules: [ 42 | 'nuxt-particles' 43 | ] 44 | }) 45 | ``` 46 | 47 | That's it! You can now use the <NuxtParticles> component in your application! ✨ 48 | 49 | Read the [documentation](https://nuxt-particles.joeypereira.dev) for more information, including 50 | configuration and optimization options. Documentation on how to configure the particles themselves 51 | is available on [tsparticles's website](https://particles.js.org/). 52 | 53 | Example: 54 | 55 | ```vue 56 | 71 | 72 | 85 | ``` 86 | 87 | ## Development 88 | 89 | ```bash 90 | # Install dependencies 91 | pnpm install 92 | 93 | # Generate type stubs 94 | pnpm run dev:prepare 95 | 96 | # Develop with the playground 97 | pnpm run dev 98 | 99 | # Build the playground 100 | pnpm run dev:build 101 | 102 | # Run ESLint 103 | pnpm run lint 104 | 105 | # Release new version 106 | pnpm run release 107 | ``` 108 | 109 | 110 | [npm-version-src]: https://img.shields.io/npm/v/nuxt-particles/latest.svg?style=flat&colorA=18181B&colorB=28CF8D 111 | [npm-version-href]: https://npmjs.com/package/nuxt-particles 112 | 113 | [npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-particles.svg?style=flat&colorA=18181B&colorB=28CF8D 114 | [npm-downloads-href]: https://npmjs.com/package/nuxt-particles 115 | 116 | [license-src]: https://img.shields.io/npm/l/nuxt-particles.svg?style=flat&colorA=18181B&colorB=28CF8D 117 | [license-href]: https://npmjs.com/package/nuxt-particles 118 | 119 | [nuxt-src]: https://img.shields.io/badge/Nuxt-18181B?logo=nuxt.js 120 | [nuxt-href]: https://nuxt.com 121 | -------------------------------------------------------------------------------- /docs/.eslintignore: -------------------------------------------------------------------------------- 1 | dist 2 | node_modules 3 | .output 4 | .nuxt -------------------------------------------------------------------------------- /docs/.eslintrc.cjs: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | root: true, 3 | extends: '@nuxt/eslint-config', 4 | rules: { 5 | 'vue/max-attributes-per-line': 'off', 6 | 'vue/multi-word-component-names': 'off' 7 | } 8 | } -------------------------------------------------------------------------------- /docs/.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | *.iml 3 | .idea 4 | *.log* 5 | .nuxt 6 | .vscode 7 | .DS_Store 8 | coverage 9 | dist 10 | sw.* 11 | .env 12 | .output 13 | -------------------------------------------------------------------------------- /docs/.npmrc: -------------------------------------------------------------------------------- 1 | shamefully-hoist=true 2 | strict-peer-dependencies=false 3 | -------------------------------------------------------------------------------- /docs/.nuxtrc: -------------------------------------------------------------------------------- 1 | imports.autoImport=true 2 | typescript.includeWorkspace=false 3 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Docus Starter 2 | 3 | Starter template for [Docus](https://docus.dev). 4 | 5 | ## Clone 6 | 7 | Clone the repository (using `nuxi`): 8 | 9 | ```bash 10 | npx nuxi init -t themes/docus 11 | ``` 12 | 13 | ## Setup 14 | 15 | Install dependencies: 16 | 17 | ```bash 18 | yarn install 19 | ``` 20 | 21 | ## Development 22 | 23 | ```bash 24 | yarn dev 25 | ``` 26 | 27 | ## Edge Side Rendering 28 | 29 | Can be deployed to Vercel Functions, Netlify Functions, AWS, and most Node-compatible environments. 30 | 31 | Look at all the available presets [here](https://v3.nuxtjs.org/guide/deploy/presets). 32 | 33 | ```bash 34 | yarn build 35 | ``` 36 | 37 | ## Static Generation 38 | 39 | Use the `generate` command to build your application. 40 | 41 | The HTML files will be generated in the .output/public directory and ready to be deployed to any static compatible hosting. 42 | 43 | ```bash 44 | yarn generate 45 | ``` 46 | 47 | ## Preview build 48 | 49 | You might want to preview the result of your build locally, to do so, run the following command: 50 | 51 | ```bash 52 | yarn preview 53 | ``` 54 | 55 | --- 56 | 57 | For a detailed explanation of how things work, check out [Docus](https://docus.dev). 58 | -------------------------------------------------------------------------------- /docs/app.config.ts: -------------------------------------------------------------------------------- 1 | export default defineAppConfig({ 2 | docus: { 3 | title: 'Nuxt Particles', 4 | description: 'The best place to start your documentation.', 5 | image: 'https://user-images.githubusercontent.com/904724/185365452-87b7ca7b-6030-4813-a2db-5e65c785bf88.png', 6 | socials: { 7 | github: 'Joepocalyptic/nuxt-particles', 8 | nuxt: { 9 | label: 'Nuxt', 10 | icon: 'simple-icons:nuxtdotjs', 11 | href: 'https://nuxt.com' 12 | } 13 | }, 14 | github: { 15 | dir: 'docs/content', 16 | branch: 'main', 17 | repo: 'nuxt-particles', 18 | owner: 'Joepocalyptic', 19 | edit: false 20 | }, 21 | aside: { 22 | level: 0, 23 | collapsed: false, 24 | exclude: [] 25 | }, 26 | main: { 27 | padded: true, 28 | fluid: false 29 | }, 30 | header: { 31 | logo: true, 32 | showLinkIcon: true, 33 | exclude: [], 34 | fluid: false 35 | } 36 | } 37 | }) 38 | -------------------------------------------------------------------------------- /docs/content/0.index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Home 3 | navigation: false 4 | layout: page 5 | main: 6 | fluid: false 7 | --- 8 | 9 | :ellipsis{right=0px width=75% blur=150px} 10 | 11 | ::block-hero 12 | --- 13 | cta: 14 | - Get started 15 | - /getting-started/setup 16 | secondary: 17 | - Star on GitHub → 18 | - https://github.com/Joepocalyptic/nuxt-particles 19 | --- 20 | 21 | #title 22 | Nuxt Particles 23 | 24 | #description 25 | Run lightweight, heavily customizable particle simulations in your Nuxt project with [tsParticles](https://particles.js.org). 26 | 27 | #extra 28 | ::list 29 | - Built for **Nuxt 3** 30 | - **Lazy loading** by default 31 | - Built-in full, slim, and basic bundles, or 32 | - Use a custom bundle for extra performance 33 | - All with just **one component**! 34 | :: 35 | 36 | #support 37 | ::terminal 38 | --- 39 | content: 40 | - pnpm i -D nuxt-particles 41 | - Add 'nuxt-particles' to your 'modules' array in 'nuxt.config.ts' 42 | - Profit! 43 | --- 44 | :: 45 | :: 46 | -------------------------------------------------------------------------------- /docs/content/1.getting-started/1.setup.md: -------------------------------------------------------------------------------- 1 | # Setup 2 | 3 | This module is plug-and-play with sensible defaults. Just install the package to get started. 4 | 5 | ## Installation 6 | 7 | 1. Install the `nuxt-particles` package: 8 | 9 | ::code-group 10 | 11 | ```bash [pnpm] 12 | pnpm add -D nuxt-particles 13 | ``` 14 | 15 | ```bash [yarn] 16 | yarn add -D nuxt-particles 17 | ``` 18 | 19 | ```bash [npm] 20 | npm install --save-dev nuxt-particles 21 | ``` 22 | 23 | :: 24 | 25 | 2. Add the `nuxt-particles` package to the `modules` array in your `nuxt.config.ts`: 26 | 27 | ```ts 28 | export default defineNuxtConfig({ 29 | modules: [ 30 | // ... 31 | 'nuxt-particles' 32 | ], 33 | // ... 34 | }) 35 | ``` 36 | 37 | ## Options 38 | 39 | You may configure the `nuxt-particles` module by adding a `particles` property to your `nuxt.config.ts`: 40 | 41 | ```ts 42 | export default defineNuxtConfig({ 43 | // ... 44 | particles: { 45 | mode: 'full', // 'full' | 'slim' | 'basic' | 'custom' 46 | lazy: true 47 | } 48 | }) 49 | ``` 50 | 51 | Learn more about the available options in the [Configuration](/getting-started/configuration) section. 52 | 53 | ::alert{type="success"} 54 | ✨ You're all set! Start using the [<NuxtParticles>](/components/nuxt-particles) component in your application. 55 | :: 56 | -------------------------------------------------------------------------------- /docs/content/1.getting-started/2.configuration.md: -------------------------------------------------------------------------------- 1 | # Configuration 2 | 3 | This module provides a few options to customize its behavior. 4 | 5 | ## Lazy-loading 6 | 7 | By default, `nuxt-particles` lazy-loads the [tsParticles](https://particles.js.org) library. This means that the library 8 | will only be loaded the first time the [``](/components/nuxt-particles) component is used in your application. 9 | 10 | You may disable this behavior by setting the `lazy` option to `false`: 11 | 12 | ```ts 13 | export default defineNuxtConfig({ 14 | // ... 15 | particles: { 16 | lazy: false 17 | } 18 | }) 19 | ``` 20 | 21 | ::alert{type="warning"} 22 | ⚠️ Be careful! If you disable lazy-loading, the tsParticles library will be loaded *before* your application using a Nuxt 23 | plugin. This will make particles render negligibly earlier at the cost of significant load-time performance. Don't disable 24 | this option unless the [Total Blocking Time](https://web.dev/tbt/) web vital is not of concern to your application. 25 | :: 26 | 27 | 28 | ## Mode 29 | 30 | The `mode` option allows you to choose which bundle of the tsParticles library to use. The default value is `full`. 31 | `slim` uses the 32 | [`@tsparticles/slim`](https://www.npmjs.com/package/@tsparticles/slim) 33 | package, while `basic` uses the 34 | [`@tsparticles/basic`](https://www.npmjs.com/package/@tsparticles/basic) 35 | package. See their respective documentation for more information. 36 | 37 | If you are not using certain advanced features of the tsParticles library, you may want to try out the `slim` or `basic` 38 | bundles to avoid sending unnecessary JS to the client. 39 | 40 | ::alert{type="info"} 41 | 🛈 The `slim` mode should work for most use-cases! 42 | :: 43 | 44 | ```ts 45 | export default defineNuxtConfig({ 46 | // ... 47 | particles: { 48 | mode: 'full' // 'full' | 'slim' | 'basic' | 'custom' 49 | } 50 | }) 51 | ``` 52 | 53 | ### Custom mode 54 | 55 | If you'd like to fully control how the tsParticles library is loaded, you may use the `custom` mode. This will prevent 56 | the `nuxt-particles` module from loading the tsParticles library, allowing you to load it yourself. 57 | [Lazy-loading](#lazy-loading) will also be implicitly disabled. 58 | 59 | Somewhere on the client-side of your application **before** the [``](/components/nuxt-particles) 60 | component is rendered, you must manually initialize the tsParticles library (such as in your app.vue): 61 | 62 | ```vue 63 | 64 | 68 | 69 | 79 | ``` 80 | 81 | This also makes it possible to build a custom bundle of the tsParticles library by manually providing plugins. 82 | If bundle sizes are of the utmost importance, this is likely the best option for you. 83 | 84 | ```vue 85 | 86 | 94 | ``` 95 | -------------------------------------------------------------------------------- /docs/content/1.getting-started/3.faq.md: -------------------------------------------------------------------------------- 1 | # FAQ 2 | 3 | These are some frequently asked questions about the `nuxt-particles` module. 4 | 5 | ## Why not use `@tsparticles/vue3`? 6 | 7 | The `@tsparticles/vue3` package is the first-party Vue 3 wrapper around the `tsParticles` library, but 8 | it has some flaws. 9 | 10 | The `tsParticles` library modifies the global scope upon initialization; it is not done on a per-component basis. Therefore, 11 | loading the provided component multiple times will cause a "flash" on all existing particle containers without complicated 12 | workarounds. This is an antipattern to Vue's isolated, component-based paradigm, and is therefore not ideal. 13 | 14 | The component provided by this module solves this by keeping track of whether the library is initialized on a 15 | global level. If it has already been initialized, any subsequent component instances will not attempt to reload it. 16 | This is made possible using Nuxt's built-in `useState` composable. 17 | 18 | ## Should I enable lazy-loading? 19 | 20 | In the vast majority of cases, **yes**. The `nuxt-particles` module will automatically lazy-load the tsParticles library 21 | when the `` component is rendered. As such, the library will not be loaded until it is needed, 22 | which can significantly improve your application's performance. Disabling this feature is not recommended unless you 23 | have a specific reason to do so. 24 | 25 | -------------------------------------------------------------------------------- /docs/content/1.getting-started/_dir.yml: -------------------------------------------------------------------------------- 1 | title: Getting Started 2 | icon: material-symbols:bolt-rounded 3 | navigation.redirect: /getting-started/setup 4 | -------------------------------------------------------------------------------- /docs/content/2.components/1.nuxt-particles.md: -------------------------------------------------------------------------------- 1 | # `` 2 | 3 | The `` component renders a [tsParticles](https://particles.js.org) instance inside of a `
` element 4 | with the chosen `id`. 5 | 6 | ## Example 7 | 8 | ```vue 9 | 10 | 29 | 30 | 67 | ``` 68 | 69 | ## Props 70 | 71 | ### `id` 72 | 73 | - Type: `string` 74 | - Required: `true` 75 | 76 | Used by tsParticles to differentiate between multiple instances on the same page. Must be unique. 77 | 78 | ### `options` 79 | 80 | - Type: `IOptions` (see [tsParticles docs](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html)) 81 | - Required: `false` 82 | 83 | The options object to pass to tsParticles. May be used in place of the `url` prop to directly pass a JSON object instead 84 | of loading a configuration file. 85 | 86 | ### `url` 87 | 88 | - Type: `string` 89 | - Required: `false` 90 | 91 | The URL of the JSON file containing the particle configuration. May be used in place of the `options` prop to 92 | load a configuration file instead of directly passing a JSON object. 93 | 94 | ## Events 95 | 96 | ### `load` 97 | 98 | - Type: `(container: Container) => void` (see [tsParticles docs](https://particles.js.org/docs/classes/tsParticles_Engine.Core_Container.Container.html)) 99 | 100 | Called when tsParticles has successfully loaded its canvas. Provides a `container` object that can be used to interact 101 | with the instance. Some useful methods include: 102 | 103 | ```ts 104 | // Pause the animation 105 | container.pause() 106 | // Play the animation 107 | container.play() 108 | // Refresh the instance 109 | container.refresh() 110 | // Destroy the instance 111 | container.destroy() 112 | ``` 113 | 114 | ## Usage notes 115 | 116 | This component automatically lazy-loads the tsParticles library if the `particles.lazy` option is set to `true` in 117 | your Nuxt configuration. Otherwise, the library is loaded immediately before your entire application is rendered. 118 | 119 | Using multiple instances of this component on the same page is safe as long as each instance has a unique `id`. This 120 | may have performance implications, however, as each instance will be rendering its own canvas. Use one instance with 121 | multiple particle emitters whenever possible. 122 | 123 | If you are using a custom bundle, you must [manually initialize the library](/getting-started/configuration#custom-mode) 124 | in your application. 125 | -------------------------------------------------------------------------------- /docs/content/2.components/_dir.yml: -------------------------------------------------------------------------------- 1 | title: Components 2 | icon: material-symbols:grid-view-rounded 3 | navigation.redirect: /components/nuxt-particles 4 | -------------------------------------------------------------------------------- /docs/nuxt.config.ts: -------------------------------------------------------------------------------- 1 | export default defineNuxtConfig({ 2 | // https://github.com/nuxt-themes/docus 3 | extends: '@nuxt-themes/docus', 4 | 5 | modules: [ 6 | // https://github.com/nuxt-modules/plausible 7 | '@nuxtjs/plausible', 8 | // https://github.com/nuxt/devtools 9 | '@nuxt/devtools' 10 | ], 11 | 12 | nitro: { 13 | prerender: { 14 | failOnError: false 15 | } 16 | } 17 | }) 18 | -------------------------------------------------------------------------------- /docs/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "nuxt-particles-docs", 3 | "version": "0.1.0", 4 | "private": true, 5 | "scripts": { 6 | "dev": "nuxi dev", 7 | "build": "nuxi build", 8 | "generate": "nuxi generate", 9 | "preview": "nuxi preview", 10 | "lint": "eslint ." 11 | }, 12 | "devDependencies": { 13 | "@nuxt-themes/docus": "^1.15.0", 14 | "@nuxt/devtools": "^0.8.5", 15 | "@nuxt/eslint-config": "^0.2.0", 16 | "@nuxtjs/plausible": "^0.2.3", 17 | "@types/node": "^20.8.4", 18 | "eslint": "^8.51.0", 19 | "nuxt": "^3.7.4" 20 | } 21 | } 22 | -------------------------------------------------------------------------------- /docs/public/cover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Joepocalyptic/nuxt-particles/ffcc4190df68498db5f41e91f618268747d3a57a/docs/public/cover.png -------------------------------------------------------------------------------- /docs/public/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Joepocalyptic/nuxt-particles/ffcc4190df68498db5f41e91f618268747d3a57a/docs/public/favicon.ico -------------------------------------------------------------------------------- /docs/renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": [ 3 | "@nuxtjs" 4 | ], 5 | "lockFileMaintenance": { 6 | "enabled": true 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /docs/tokens.config.ts: -------------------------------------------------------------------------------- 1 | import { defineTheme } from 'pinceau' 2 | 3 | export default defineTheme({ 4 | }) 5 | -------------------------------------------------------------------------------- /docs/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./.nuxt/tsconfig.json" 3 | } 4 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "nuxt-particles", 3 | "version": "0.3.0", 4 | "description": "Run lightweight, heavily customizable particle simulations in your Nuxt project with tsParticles.", 5 | "repository": "Joepocalyptic/nuxt-particles", 6 | "license": "MIT", 7 | "type": "module", 8 | "exports": { 9 | ".": { 10 | "types": "./dist/types.d.ts", 11 | "import": "./dist/module.mjs", 12 | "require": "./dist/module.cjs" 13 | } 14 | }, 15 | "keywords": [ 16 | "nuxt", 17 | "particles", 18 | "tsParticles", 19 | "particles.js", 20 | "particlesjs", 21 | "particles-js", 22 | "nuxt particles", 23 | "nuxt-particles", 24 | "nuxt-module", 25 | "nuxt3", 26 | "confetti", 27 | "fireworks", 28 | "snow" 29 | ], 30 | "main": "./dist/module.cjs", 31 | "types": "./dist/types.d.ts", 32 | "files": [ 33 | "dist" 34 | ], 35 | "scripts": { 36 | "prepack": "nuxt-module-build", 37 | "dev": "nuxi dev playground", 38 | "dev:build": "nuxi build playground", 39 | "dev:prepare": "nuxt-module-build --stub && nuxi prepare playground", 40 | "release": "pnpm run prepack && changelogen --release --push && pnpm publish", 41 | "lint": "eslint ." 42 | }, 43 | "dependencies": { 44 | "@nuxt/kit": "^3.11.1", 45 | "defu": "^6.1.4", 46 | "tsparticles": "^3.3.0", 47 | "@tsparticles/basic": "^3.3.0", 48 | "@tsparticles/engine": "^3.3.0", 49 | "@tsparticles/slim": "^3.3.0" 50 | }, 51 | "devDependencies": { 52 | "@nuxt/devtools": "latest", 53 | "@nuxt/eslint-config": "^0.2.0", 54 | "@nuxt/module-builder": "^0.5.5", 55 | "@nuxt/schema": "^3.11.1", 56 | "@nuxt/test-utils": "^3.12.0", 57 | "@types/node": "^18.18.4", 58 | "changelogen": "^0.5.5", 59 | "eslint": "^8.57.0", 60 | "nuxt": "^3.11.1", 61 | "vitest": "^0.34.6" 62 | } 63 | } -------------------------------------------------------------------------------- /playground/app.vue: -------------------------------------------------------------------------------- 1 | 19 | 20 | 55 | -------------------------------------------------------------------------------- /playground/nuxt.config.ts: -------------------------------------------------------------------------------- 1 | export default defineNuxtConfig({ 2 | modules: ['../src/module'], 3 | // Defaults 4 | particles: { 5 | mode: 'full', 6 | lazy: true 7 | }, 8 | devtools: { enabled: true }, 9 | }) 10 | -------------------------------------------------------------------------------- /playground/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "private": true, 3 | "name": "nuxt-particles-playground", 4 | "type": "module", 5 | "scripts": { 6 | "dev": "nuxi dev", 7 | "build": "nuxi build", 8 | "generate": "nuxi generate" 9 | }, 10 | "devDependencies": { 11 | "nuxt": "^3.11.1" 12 | } 13 | } 14 | -------------------------------------------------------------------------------- /playground/server/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "../.nuxt/tsconfig.server.json" 3 | } 4 | -------------------------------------------------------------------------------- /playground/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./.nuxt/tsconfig.json" 3 | } 4 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "github>nuxt/renovate-config-nuxt" 5 | ], 6 | "baseBranches": [ 7 | "main" 8 | ] 9 | } 10 | -------------------------------------------------------------------------------- /src/module.ts: -------------------------------------------------------------------------------- 1 | import {defineNuxtModule, addPlugin, createResolver, addComponent} from '@nuxt/kit' 2 | import defu from 'defu' 3 | 4 | export interface ModuleOptions { 5 | mode: 'full' | 'slim' | 'basic' | 'custom' 6 | lazy: boolean 7 | } 8 | 9 | export default defineNuxtModule({ 10 | meta: { 11 | name: 'nuxt-particles', 12 | configKey: 'particles', 13 | compatibility: { 14 | nuxt: "^3.7.0" 15 | } 16 | }, 17 | // Default configuration options of the Nuxt module 18 | defaults: { 19 | mode: 'full', 20 | lazy: true 21 | }, 22 | setup (options, nuxt) { 23 | const resolver = createResolver(import.meta.url) 24 | 25 | if(!options.lazy && options.mode !== 'custom') { 26 | addPlugin(resolver.resolve('./runtime/plugins/particle-loader.client')) 27 | } 28 | 29 | nuxt.options.runtimeConfig.public = defu(nuxt.options.runtimeConfig.public || {}, { 30 | particles: { 31 | mode: options.mode, 32 | lazy: options.lazy 33 | } 34 | }) 35 | 36 | // noinspection JSIgnoredPromiseFromCall 37 | addComponent({ 38 | name: 'NuxtParticles', 39 | filePath: resolver.resolve('./runtime/components/NuxtParticles.vue') 40 | }) 41 | } 42 | }) 43 | -------------------------------------------------------------------------------- /src/runtime/components/NuxtParticles.vue: -------------------------------------------------------------------------------- 1 | 4 | 5 | 54 | -------------------------------------------------------------------------------- /src/runtime/lib/loaders.ts: -------------------------------------------------------------------------------- 1 | import type { Engine } from '@tsparticles/engine' 2 | 3 | export const loaderFull = async (engine: Engine) => { 4 | const { loadFull } = await import('tsparticles') 5 | await loadFull(engine) 6 | } 7 | 8 | export const loaderSlim = async (engine: Engine) => { 9 | const { loadSlim } = await import('@tsparticles/slim') 10 | await loadSlim(engine) 11 | } 12 | 13 | export const loaderBasic = async (engine: Engine) => { 14 | const { loadBasic } = await import('@tsparticles/basic') 15 | await loadBasic(engine) 16 | } 17 | 18 | export const loadParticles = async (engine: Engine, mode: string) => { 19 | const loaderMap = new Map Promise>([ 20 | ['basic', loaderBasic], 21 | ['slim', loaderSlim], 22 | ['full', loaderFull] 23 | ]) 24 | const loader = loaderMap.get(mode) 25 | if(loader) { 26 | await loader(engine) 27 | } 28 | } 29 | -------------------------------------------------------------------------------- /src/runtime/plugins/particle-loader.client.ts: -------------------------------------------------------------------------------- 1 | import {defineNuxtPlugin, useRuntimeConfig} from '#app' 2 | import { loadParticles } from '../lib/loaders' 3 | import { tsParticles } from '@tsparticles/engine' 4 | 5 | export default defineNuxtPlugin(async (nuxtApp) => { 6 | if(import.meta.server) { return } 7 | 8 | const runtimeConfig = useRuntimeConfig() 9 | const { mode } = runtimeConfig.public.particles 10 | 11 | await loadParticles(tsParticles, mode) 12 | }) 13 | -------------------------------------------------------------------------------- /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "extends": "./playground/.nuxt/tsconfig.json" 3 | } 4 | --------------------------------------------------------------------------------