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 (but no 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), although we recommend using either cdn.cubing.net or a bundler to make your code more maintainable in the future.

If you are using the code directly, you may want to define your own import maps to make it more convenient to work with the cubing code.

Runtimes: node, bun, and deno

cubing.js is compatible with node, bun, and deno. 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.

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, but will print a warning.

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 is generally compatible, but will encounter an error during hydration of a <twisty-player>: sveltejs/svelte#10824

However, there is currently an issue with scrambles in SvelteKit due to the use Vite.

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.

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.

---

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