Merge pull request tsparticles#5657 from tsparticles/v4

Docs

Author: matteobruni

.github/workflows/npm-publish.yml

@@ -7,7 +7,7 @@ on:
 
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -16,6 +16,7 @@ concurrency:
 env:
   NX_CLOUD_DISTRIBUTED_EXECUTION: true
   NX_CLOUD_ACCESS_TOKEN: '${{ secrets.NX_CLOUD_ACCESS_TOKEN }}'
+  IS_STABLE: ${{ !contains(github.ref, '-alpha.') && !contains(github.ref, '-beta.') }}
 
 jobs:
   publish:
@@ -39,12 +40,11 @@ jobs:
           run_install: false
 
       - name: Initialize Nx Cloud
-        run: npx nx-cloud start-ci-run --distribute-on="5 linux-medium-js"
+        run: pnpm nx-cloud start-ci-run --distribute-on="5 linux-medium-js"
 
       - name: Get pnpm store directory
         id: pnpm-cache
-        run: |
-          echo "pnpm_cache_dir=$(pnpm store path)" >> $GITHUB_OUTPUT
+        run: echo "pnpm_cache_dir=$(pnpm store path)" >> $GITHUB_OUTPUT
 
       - uses: actions/cache@v5
         name: Setup pnpm cache
@@ -58,15 +58,20 @@ jobs:
         run: pnpm install
 
       - name: Build All Packages
-        run: npx nx run-many -t build:ci
+        run: pnpm nx run-many -t build:ci
         env:
           CI: true
 
+      # 📦 ZIP artifacts (solo stable)
+      - name: Generate zip artifacts
+        if: env.IS_STABLE == 'true'
+        run: pnpm run release:zip-artifacts
+
+      # 🚀 Publish npm
       - name: Publish to NPM (OIDC Auth)
         run: |
           TAG="${GITHUB_REF#refs/tags/}"
-          
-          BASE_CMD="npx lerna publish from-package --ignore-scripts"
+          BASE_CMD="pnpm lerna publish from-package --ignore-scripts"
 
           echo "Publishing tag: $TAG via OIDC"
 
@@ -84,6 +89,30 @@ jobs:
             $BASE_CMD
           fi
 
+      # 🧠 Create release (raw GitHub notes)
+      - name: Create Release (raw)
+        if: env.IS_STABLE == 'true'
+        id: release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release-artifacts/*.zip
+          generate_release_notes: true
+
+      # ✨ Prettify changelog → per package
+      - name: Prettify changelog
+        if: env.IS_STABLE == 'true'
+        run: |
+          echo "${{ steps.release.outputs.body }}" > RAW_RELEASE.md
+          pnpm run release:prettify-changelog
+
+      # 🔁 Update release con changelog finale
+      - name: Update Release Notes
+        if: env.IS_STABLE == 'true'
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release-artifacts/*.zip
+          body_path: RELEASE_NOTES.md
+
       - name: Stop Nx Cloud Session
-        run: npx nx fix-ci
+        run: pnpm nx fix-ci
         if: always()

README.md

@@ -31,6 +31,7 @@ React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Riot.j
 - [tsParticles - TypeScript Particles](#tsparticles---typescript-particles)
   - [Table of Contents](#table-of-contents)
   - [Do you want to use it on your website?](#do-you-want-to-use-it-on-your-website)
+  - [Start here in 2 minutes](#start-here-in-2-minutes)
   - [**_Library installation_**](#library-installation)
     - [**_Hosting / CDN_**](#hosting--cdn)
       - [jsDelivr](#jsdelivr)
@@ -72,16 +73,23 @@ React.js, Vue.js (2.x and 3.x), Angular, Svelte, jQuery, Preact, Inferno, Riot.j
       - [`@tsparticles/wordpress`](#@tsparticles/wordpress)
     - [Elementor](#elementor)
   - [Presets](#presets)
+    - [Ambient](#ambient)
     - [Big Circles](#big-circles)
     - [Bubbles](#bubbles)
     - [Confetti](#confetti)
+    - [Confetti Cannon](#confetti-cannon)
+    - [Confetti Explosions](#confetti-explosions)
+    - [Confetti Falling](#confetti-falling)
+    - [Confetti Parade](#confetti-parade)
     - [Fire](#fire)
     - [Firefly](#firefly)
     - [Fireworks](#fireworks)
     - [Fountain](#fountain)
+    - [Hyperspace](#hyperspace)
     - [Links](#links)
     - [Sea Anemone](#sea-anemone)
     - [Snow](#snow)
+    - [Squares](#squares)
     - [Stars](#stars)
     - [Triangles](#triangles)
   - [Templates and Resources](#templates-and-resources)
@@ -123,6 +131,69 @@ files splitted for `import` syntax.
 just [below](https://github.com/tsparticles/tsparticles/blob/main/README.md#library-installation) to guide you to
 migrate from the old particles.js library.
 
+## Start here in 2 minutes
+
+If you are new to tsParticles, this path is usually the fastest:
+
+1. Install `@tsparticles/engine` and `@tsparticles/slim`
+2. Load the slim bundle once
+3. Start with a small config and iterate
+
+```javascript
+import { tsParticles } from "@tsparticles/engine";
+import { loadSlim } from "@tsparticles/slim";
+
+await loadSlim(tsParticles);
+
+await tsParticles.load({
+  id: "tsparticles",
+  options: {
+    background: {
+      color: "#0d1117",
+    },
+    particles: {
+      move: {
+        enable: true,
+      },
+      number: {
+        value: 60,
+      },
+    },
+  },
+});
+```
+
+Useful docs for the next step:
+
+- Docs home: <https://particles.js.org/docs/>
+- Options guide: <https://github.com/tsparticles/tsparticles/blob/main/markdown/Options.md>
+- Migration guide: <https://github.com/tsparticles/tsparticles/blob/main/markdown/pjsMigration.md>
+- Presets catalog: <https://github.com/tsparticles/presets>
+
+## Quick checklist
+
+- Install `@tsparticles/engine` and one bundle (`@tsparticles/slim` is the common default)
+- Load the bundle before calling `tsParticles.load(...)`
+- Start from a small config, then extend incrementally
+
+## Choose your quick-start path
+
+- **I want fewer dependencies**: use `@tsparticles/engine` + only needed feature packages
+- **I want the easiest default**: use `@tsparticles/slim`
+- **I need everything enabled**: use `@tsparticles/all`
+
+## Common pitfalls
+
+- Loading options that require plugins before loading those plugin packages
+- Starting with very high particle counts before checking FPS
+- Mixing legacy snake_case keys with modern camelCase options
+
+## Related docs
+
+- Main docs: <https://particles.js.org/docs/>
+- Root options guide: <https://github.com/tsparticles/tsparticles/blob/main/markdown/Options.md>
+- Migration guide: <https://github.com/tsparticles/tsparticles/blob/main/markdown/pjsMigration.md>
+
 ## **_Library installation_**
 
 ### **_Hosting / CDN_**
@@ -440,6 +511,16 @@ the `Premium Addons for Elementor` plugin collection.
 There are some presets ready to be used in [this repository](https://github.com/tsparticles/presets), and they also have a bundle file that contains everything
 needed to run.
 
+### Ambient
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-ambient/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-ambient) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-ambient.svg)](https://www.npmjs.com/package/@tsparticles/preset-ambient) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-ambient)](https://www.npmjs.com/package/@tsparticles/preset-ambient)
+
+This preset loads ambient circles on a dark background.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/ambient/images/sample.png)](https://particles.js.org/samples/presets/ambient)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/ambient#readme)
+
 ### Big Circles
 
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-big-circles/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-big-circles) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-big-circles.svg)](https://www.npmjs.com/package/@tsparticles/preset-big-circles) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-big-circles)](https://www.npmjs.com/package/@tsparticles/preset-big-circles)
@@ -470,6 +551,46 @@ This preset loads white and red confetti launched from the screen center on a tr
 
 You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confetti#readme)
 
+### Confetti Cannon
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-confetti-cannon/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-confetti-cannon) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-confetti-cannon.svg)](https://www.npmjs.com/package/@tsparticles/preset-confetti-cannon) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-confetti-cannon)](https://www.npmjs.com/package/@tsparticles/preset-confetti-cannon)
+
+This preset loads confetti launched from a draggable cannon.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/confettiCannon/images/sample.png)](https://particles.js.org/samples/presets/confettiCannon)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confettiCannon#readme)
+
+### Confetti Explosions
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-confetti-explosions/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-confetti-explosions) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-confetti-explosions.svg)](https://www.npmjs.com/package/@tsparticles/preset-confetti-explosions) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-confetti-explosions)](https://www.npmjs.com/package/@tsparticles/preset-confetti-explosions)
+
+This preset loads confetti bursts at multiple points on the screen.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/confettiExplosions/images/sample.png)](https://particles.js.org/samples/presets/confettiExplosions)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confettiExplosions#readme)
+
+### Confetti Falling
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-confetti-falling/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-confetti-falling) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-confetti-falling.svg)](https://www.npmjs.com/package/@tsparticles/preset-confetti-falling) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-confetti-falling)](https://www.npmjs.com/package/@tsparticles/preset-confetti-falling)
+
+This preset loads slowly falling confetti particles.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/confettiFalling/images/sample.png)](https://particles.js.org/samples/presets/confettiFalling)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confettiFalling#readme)
+
+### Confetti Parade
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-confetti-parade/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-confetti-parade) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-confetti-parade.svg)](https://www.npmjs.com/package/@tsparticles/preset-confetti-parade) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-confetti-parade)](https://www.npmjs.com/package/@tsparticles/preset-confetti-parade)
+
+This preset loads confetti moving horizontally across the screen like a parade.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/confettiParade/images/sample.png)](https://particles.js.org/samples/presets/confettiParade)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/confettiParade#readme)
+
 ### Fire
 
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-fire/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-fire) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-fire.svg)](https://www.npmjs.com/package/@tsparticles/preset-fire) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-fire)](https://www.npmjs.com/package/@tsparticles/preset-fire)
@@ -500,6 +621,16 @@ This preset loads a beautiful fireworks effect.
 
 You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/fireworks#readme)
 
+### Hyperspace
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-hyperspace/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-hyperspace) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-hyperspace.svg)](https://www.npmjs.com/package/@tsparticles/preset-hyperspace) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-hyperspace)](https://www.npmjs.com/package/@tsparticles/preset-hyperspace)
+
+This preset loads a hyperspace tunnel effect with fast-moving particles.
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/hyperspace/images/sample.png)](https://particles.js.org/samples/presets/hyperspace)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/hyperspace#readme)
+
 ### Fountain
 
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-fountain/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-fountain) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-fountain.svg)](https://www.npmjs.com/package/@tsparticles/preset-fountain) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-fountain)](https://www.npmjs.com/package/@tsparticles/preset-fountain)
@@ -532,6 +663,14 @@ You can find the instructions [here](https://github.com/tsparticles/presets/tree
 
 You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/snow#readme)
 
+### Squares
+
+[![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-squares/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-squares) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-squares.svg)](https://www.npmjs.com/package/@tsparticles/preset-squares) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-squares)](https://www.npmjs.com/package/@tsparticles/preset-squares)
+
+[![demo](https://github.com/tsparticles/presets/raw/main/presets/squares/images/sample.png)](https://particles.js.org/samples/presets/squares)
+
+You can find the instructions [here](https://github.com/tsparticles/presets/tree/main/presets/squares#readme)
+
 ### Stars
 
 [![jsDelivr](https://data.jsdelivr.com/v1/package/npm/@tsparticles/preset-stars/badge)](https://www.jsdelivr.com/package/npm/@tsparticles/preset-stars) [![npmjs](https://badge.fury.io/js/@tsparticles/preset-stars.svg)](https://www.npmjs.com/package/@tsparticles/preset-stars) [![npmjs](https://img.shields.io/npm/dt/@tsparticles/preset-stars)](https://www.npmjs.com/package/@tsparticles/preset-stars)
@@ -629,6 +768,12 @@ You can find all options
 available [here](https://particles.js.org/docs/interfaces/tsParticles_Engine.Options_Interfaces_IOptions.IOptions.html)
 📖
 
+If you want a practical map with examples, check these markdown docs too:
+
+- Root options: <https://github.com/tsparticles/tsparticles/blob/main/markdown/Options.md>
+- Colors: <https://github.com/tsparticles/tsparticles/blob/main/markdown/Color.md>
+- Container API: <https://github.com/tsparticles/tsparticles/blob/main/markdown/Container.md>
+
 ## Want to see it in action and try it?
 
 I've created a tsParticles collection on [CodePen](https://codepen.io/collection/DPOage) 😮 or you can check out
@@ -669,6 +814,10 @@ switch? [Read here](https://dev.to/matteobruni/5-reasons-to-use-tsparticles-and-
 
 _Below you can find all the information you need to install tsParticles and its new syntax._
 
+Migration quick guide in this repository:
+
+- <https://github.com/tsparticles/tsparticles/blob/main/markdown/pjsMigration.md>
+
 ---
 
 ## Plugins/Customizations
@@ -679,6 +828,10 @@ tsParticles now supports some customizations 🥳.
 
 _Read more [here](https://particles.js.org/docs/modules/Core_Interfaces_IPlugin.html)..._
 
+Practical customization guide (shape + preset examples):
+
+- <https://github.com/tsparticles/tsparticles/blob/main/markdown/Plugins.md>
+
 ---
 
 ## Dependency Graph

bundles/all/README.md

@@ -201,6 +201,12 @@ ba --> s
 ba --> u
 ```
 
+## Quick checklist
+
+1. Install `@tsparticles/engine` (or use the CDN bundle below)
+2. Call the package loader function(s) before `tsParticles.load(...)`
+3. Apply the package options in your `tsParticles.load(...)` config
+
 ## How to use it
 
 ### CDN / Vanilla JS / jQuery
@@ -350,3 +356,14 @@ let particlesInit = async engine => {
   await loadAll(engine);
 };
 ```
+
+## Common pitfalls
+
+- Calling `tsParticles.load(...)` before `loadAll(...)`
+- Verify required peer packages before enabling advanced options
+- Change one option group at a time to isolate regressions quickly
+
+## Related docs
+
+- All packages catalog: <https://github.com/tsparticles/tsparticles>
+- Main docs: <https://particles.js.org/docs/>

bundles/basic/README.md

@@ -56,6 +56,12 @@ bb --> s
 bb --> u
 ```
 
+## Quick checklist
+
+1. Install `@tsparticles/engine` (or use the CDN bundle below)
+2. Call the package loader function(s) before `tsParticles.load(...)`
+3. Apply the package options in your `tsParticles.load(...)` config
+
 ## How to use it
 
 ### CDN / Vanilla JS / jQuery
@@ -205,3 +211,14 @@ let particlesInit = async engine => {
   await loadBasic(engine);
 };
 ```
+
+## Common pitfalls
+
+- Calling `tsParticles.load(...)` before `loadBasic(...)`
+- Verify required peer packages before enabling advanced options
+- Change one option group at a time to isolate regressions quickly
+
+## Related docs
+
+- All packages catalog: <https://github.com/tsparticles/tsparticles>
+- Main docs: <https://particles.js.org/docs/>