tsParticles 3.0.0 is out. Breaking changes ahead.
Tags: showdev, webdev, javascript, typescript
Published: 2023-12-04 23:53:31

## tsParticles 3.0.0 Changelog ([link](https://github.com/tsparticles/tsparticles/pull/5226))

{% github tsparticles/tsparticles %}

Keep reading for more details about v3, they're after the changelog...

## BREAKING CHANGES

- Removed all tsParticles `load` methods to keep only a single one using a single `object` parameter
- Removed support for shape deprecated properties like `shape.image`, `shape.polygon`, `shape.stroke`
    - the stroke property can be found in the `particles section`, not in the `shape` object
    - the image and polygon properties, like any other shape, are part of the `shape.options` object
- Stroke now is a single object only like all the other particles properties
- Removed multiline text shape, the text shape now supports that
- Simplified some functions, using objects or removing unused overloads, this is breaking for v2 shapes
- Moved some properties to private since they were public by mistake (this shouldn't affect many, the properties were mainly used in the engine)
- Removed obsolete random properties in options objects
- Removed emitters shapes from the plugin files, every emitters shape now has a dedicated package

### Major Changes

- All the components for Front End frameworks were removed from this repository, each one now has its own repository. This is mainly for maintainability. It's easier to support multiple Front End frameworks versions in a dedicated repository instead of a multipurpose monorepository. Vue.js 2.x and 3.x were kept split because they have many differences.
    - Angular (`@tsparticles/angular`): https://github.com/tsparticles/angular (v3 under development)
    - Astro (`@tsparticles/astro`): https://github.com/tsparticles/astro (v3 under development)
    - Ember (`@tsparticles/ember`): https://github.com/tsparticles/ember (v3 under development)
    - Inferno (`@tsparticles/inferno`): https://github.com/tsparticles/inferno (v3 under development)
    - jQuery (`@tsparticles/jquery`): https://github.com/tsparticles/jquery (v3 under development)
    - Lit (`@tsparticles/lit`): https://github.com/tsparticles/lit (v3 under development)
    - Preact (`@tsparticles/preact`): https://github.com/tsparticles/preact (v3 under development)
    - React (`@tsparticles/react`): https://github.com/tsparticles/react (v3 under development)
    - Riot (`@tsparticles/riot`): https://github.com/tsparticles/riot (v3 under development)
    - Solid (`@tsparticles/solid`): https://github.com/tsparticles/solid (v3 under development)
    - Svelte (`@tsparticles/svelte`): https://github.com/tsparticles/svelte (v3 under development)
    - Vue.js (`@tsparticles/vue`): https://github.com/tsparticles/vue (v3 under development)
    - Web Components (`@tsparticles/webcomponents`): https://github.com/tsparticles/webcomponents (v3 under development)
    - WordPress (`@tsparticles/wordpress`): https://github.com/tsparticles/wordpress (v3 under development)
- Removed all presets from this repository for a single one (<https://github.com/tsparticles/presets>) in the @tsparticles organization, this will make easier to contribute to specific presets or create new ones. (Renaming them to `@tsparticles/preset-<name>` #3977)
- All the previous packages will be deprecated when v3 will come out. Using only the new naming system is the main focus of v3. All the official packages will have `@tsparticles/` organization in the package name, replacing `tsparticles-` prefix, except for `tsparticles` package which will remain the same.
- Moved editor to its own repository: https://github.com/tsparticles/editor
- Pjs package now supports all the legacy pjs options only. This will make this package a wrapper for old pjs users. You can't use tsParticles options in pjs calls.
- Pjs package is no longer part of `@tsparticles/slim` bundle, only included in `@tsparticles/all`.
- Text shape is no longer part of `@tsparticles/slim` bundle, included in `tsparticles`.
- Emoji shape is now part of `@tsparticles/slim` bundle.

### New Features

- Added event on config added to the engine
- Added flat options to tsparticles-confetti options
- Creating support for effects, like bubble that wasn't a real shape
- Added linear easing
- Created new emitters shapes: Canvas, Path and Polygon
- Created trail effect plugin, this one is a real trail drawn in the canvas, it works also in transparent backgrounds. It requires more resources since it's drawn calculating last N positions and not redrawing a semi-transparent canvas on itself, supports also fade.
- Added pop click interaction
- Added limit mode (breaking changes on limit options)
- Added possibility to replace color and opacity for emitters shapes
- Added more options for customizing noises values (only Simplex and Perlin paths)
- Added curl noise path plugin
- Created Simplex and Perlin noise packages from their path plugins, they can be used in multiple packages without duplication (Curl Noise path for example)
- Added new emoji shape, better performance than text shape
- Added clear flag to the root object, enabled by default, if disabled, the canvas won't be cleared

### Bug Fixes

- Improved resize event and density formula

---

## How to migrate from v2 to v3?

Version `2.x` is still the `latest` tag on `npm`, but the `next` version has a `3.0.0` version, which is something I need to release to the public to find issues, and receive some feedbacks.

As it can be seen in the changelog above, the packages are now renamed using the @tsparticles/ "grouping" on NPM. All future tsParticles official packages will be released there, except the main package.

Also from the changelog, there are breaking changes in the options and in the main load api. Many options were deprecated and keeping them kept the bundle size bigger.

The main load api is now a single function, there is no more `loadJSON`, `set`, `setJSON` in the `tsParticles` instance.

Now there's only `tsParticles.load` and it gets a new object, introduced in latest v2 versions.

The new `tsParticles.load` signature is this:

```javascript
/* await */ tsParticles.load({
    // element: /* an HTML element used as container for the canvas, if a canvas is passed, is used that instead of a generated canvas, optional */
    // id: /* a string to identify the current loading instance, if not passed, a random id is generated */
    // index: /* a number used to choose from an item if the options are an array, optional, ignored if options is object */
    // options: /* the options of the instance, can be an array of options object, optional if url is passed, if none is passed it's meaningless to load anything */
    // url: /* the url used to load the options, uses AJAX to get the options object, the result is then used like the options object above. */
});
```

The component libraries for the most common frontend frameworks/libraries are still under development, but since the core library is ready to be released I decided to use the tag `next` again. Using v3 with v2 packages is not possible and not recommended, there are many breaking changes under the hood. If a v2 package can't be found in v3, it could've been renamed or removed because deprecated.

## Important note on trails

One of the most requested feature was using trails in a transparent background, it is now possible with the new trail effect, but is an external package, I didn't want to include that package in any bundle except @tsparticles/all (which contains all packages) because it's something completely new. I don't want to increase the bundle size to others who are not using it.
It can be used like any other tsParticles plugin library importing it and loading it into the instance.

The old trails are still available, they're more performant since they are made covering with a semitransparent layer the canvas. It's a common performant solution, for transparent backgrounds the new trails are the only way.

## Important note on emojis

Emojis in v1 and v2 could be used using the text shape. Now from v3 there's a new emoji shape, it's more performant since emoji don't care about font color. You can customize only the font family (I recommend keeping the default value, but who knows), and the value like in the text shape. The best result is with one emoji per string value. Use an array if more than one is needed.
The text shape is now part of the tsparticles package instead of @tsparticles/slim, the emoji shape is part of that package instead. This will make things easier, migrate to the emoji shape if using emojis, you'll notice the difference.

## What's next?

After this, the v3 package will be updated as always, but the priority now are the component libraries. Any help is appreciated, as always.

## How to see new v3 options?

The configs used for testing can be found here: 

https://github.com/tsparticles/tsparticles/tree/main/utils/configs/src

They can be used like explained in the readme:

https://github.com/tsparticles/tsparticles/tree/main/utils/configs#usage

---

Have fun with particles, confetti and/or fireworks. Remember to share the project if you like it, and leave a star on GitHub

https://github.com/tsparticles/tsparticles