v7.0.0

Migrating from Shuffle v6 to v7

Overview

Shuffle v7 is a major modernization that moves the library to pure ESM, TypeScript source code, and ES2024 as the compilation target. While this includes breaking changes around module format and browser support, the public API remains fully backward compatible. For most ESM users, upgrading should be straightforward.

Breaking Changes

1. ESM-Only (No CommonJS Support)

Shuffle v7 is distributed as pure ESM with type=module and no longer provides CommonJS builds.

Before (v6):

// CommonJS
const Shuffle = require('shufflejs');

// ESM
import Shuffle from 'shufflejs';

After (v7):

// ESM only
import Shuffle from 'shufflejs';

Migration: If you're using CommonJS (require), you must migrate your project to use ES modules. Most modern bundlers (Webpack 5+, Vite, Rollup) handle ESM natively.

2. Build Output Changes

The package structure has changed significantly:

v6 Package Exports:

{
  "main": "./dist/shuffle.js",
  "module": "./dist/shuffle.esm.js",
  "exports": {
    "types": "./index.d.ts",
    "require": "./dist/shuffle.js",
    "default": "./dist/shuffle.esm.js"
  },
  "types": "./index.d.ts"
}

v7 Package Exports:

{
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/shuffle.d.mts",
      "default": "./dist/shuffle.mjs"
    },
    "./package.json": "./package.json"
  },
  "types": "./dist/shuffle.d.mts"
}

What Changed:

• ❌ No more UMD build (dist/shuffle.js)
• ❌ No more separate minified files
• ✅ Single ESM build (dist/shuffle.mjs)
• ✅ TypeScript definitions generated from source (.d.mts)

Migration: If you were directly referencing build files (e.g., in a <script> tag), you'll need to use a bundler or import maps. For users importing via a package manager, no changes needed.

3. ES2024 Target

Shuffle v7 is compiled to ES2024, which means older browsers may need transpilation.

Minimum Browser Versions:

• Chrome 123+ (March 2024)
• Firefox 125+ (April 2024)
• Safari 17.4+ (March 2024)
• Edge 123+ (March 2024)
• Node.js 24+ (for server-side usage)

Migration: If you need to support older browsers:

• Configure your bundler (Webpack, Vite, etc.) to transpile node_modules/shufflejs
• Use Babel or SWC with appropriate presets
• Ensure polyfills are available if needed

4. Private Class Fields

Internal methods now use JavaScript private fields (#method) instead of underscore-prefixed methods (_method).

v6:

// These were technically accessible (but undocumented)
shuffle._filter(items);
shuffle._layout();

v7:

// These are now truly private and will throw errors
shuffle.#filter(items); // ❌ SyntaxError
shuffle.#layout(); // ❌ SyntaxError

Migration: If you were accessing private methods, you'll need to use the public API equivalents:

5. Private Static Fields

The double-underscored static methods have been removed.

6. External Dependencies

The external dependencies tiny-emitter and array-parallel have been copied and migrated to TS + ESM.

New Features & Improvements

TypeScript Type Exports

All types are now properly exported for enhanced type safety:

import Shuffle, {
  type ShuffleOptions,
  type FilterArg,
  type FilterFunction,
  type SortOptions,
  type ShuffleEventData,
  type ShuffleEventCallback,
  type InlineCssStyles,
} from 'shufflejs';

const options: ShuffleOptions = {
  itemSelector: '.card',
  speed: 500,
};

const shuffleInstance = new Shuffle(element, options);

Typed Event System

Events are now fully typed for better autocomplete and type checking:

import Shuffle, { type ShuffleEventData } from 'shufflejs';

const shuffle = new Shuffle(element);

// Type-safe event handlers
shuffle.on('shuffle:layout', (data: ShuffleEventData) => {
  console.log(data.shuffle); // Correctly typed as Shuffle instance
});

shuffle.once('shuffle:removed', (data) => {
  // data is automatically typed
  console.log(data.collection); // HTMLElement[]
});