`cubing.js` compatibility notes

[lgarron]

For maximum compatibility, the cubing package uses only standardized syntax and conventions that are supported by stable browsers and appropriate tooling, including:

• JavaScript modules
• async functions
• Top-level await
• Using the "exports" field in package.json to specify exports
• Web components
• Web workers and WebAssembly for scrambling, using:
  • import.meta.resolve or import.meta.url

However, some bundlers are not fully compatible with this.

Browsers

The cubing.js package code is directly compatible with all modern browsers. This means it could be extracted used directly (e.g. by placing all the files from the package in a web hosting folder) if package imports are resolved correctly. In theory, it is possible to do this using import maps, but:

1. This does not currently work for web workers (used for searching/scrambling), due to limitations with the web platform, and
2. import maps come with additional challenges and caveats. We don't recommend using them unless you already have experience with them.

We recommend using either cdn.cubing.net or a bundler like esbuild.

Runtimes: node, bun, and deno

cubing.js is compatible with node and bun and tested thoroughly using them. Most browser-specific functionality (e.g. elements in cubing/twisty) will not work unless you polyfill a browser environment, but cubing/alg, cubing/kpuzzle, cubing/search, and cubing/scramble should work perfectly out of the box.

cubing.js uses standard JS code that should also work in deno, but we do not test this. Please file an issue if you run into anything unexpected.

TypeScript

cubing.js is implemented in TypeScript and uses TypeScript's bundler resolution conventions. We recommend the following settings:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es2022",
    "module": "es2022",
    "moduleResolution": "bundler"
    // …
  }
  // …
}

esbuild

esbuild does not support relative path resolution syntax for web worker or WASM entry points. cubing.js contains a fallback for esbuild, although we hope to remove it as soon as possible.

We recommend using esbuild if you have a choice for what bundler to use in your project. You may find it useful to try create-cubing-app for this.

Vite

Vite used to be unable to build code with recursive (dynamic) imports involving web worker code. This has been resolved as of Vite 5.1.6, but you will run into the following error when running npx vite build with the default settings:

error during build:
RollupError: [commonjs--resolver] Invalid value "iife" for option "output.format" - UMD and IIFE output formats are not supported for code-splitting builds.

You will be able to generate scrambles using:

// vite.config.js
export default {
  // …
  worker: {
    format: "es"
  }
}

Parcel

Parcel does not use package exports for resolution by default. Use the new resolver for compatibility:

// package.json
{
  // …
  "@parcel/resolver-default": {
    "packageExports": true
  }
}

Svelte

Svelte was previously unable to hydrate <twisty-player> elements, but this should now be possible.

SvelteKit was also previously unable to generate scrambles due to the use of Vite, but this appears to have been fixed.

Angular

The implementation of Angular includes a custom concept of "zones" that is completely incompatible with standard async/await code. This means cubing/twisty is likely to be unusable in Angular for the time being.

Update: this may now be resolved due to angular/angular-cli#27486

React-based tools

React is not a web standard, and includes several design decisions that make it difficult to use with standardized web technologies like custom elements. We recommend against using React in a project with cubing.js if you can avoid it.

Next.js

Next.js may hang during development when loading cubing.js: #376 (comment)

There is no known workaround. Please report this issue to Next.js if you'd like to see a resolution.

---

If you find more compatibility issues, please file a new issue and this one will be updated with any relevant information!