Internals

Summary

Topaz primarily comprises of a few components, each with some subcomponents:

• Execution handler/environment ("Onyx"): handles and creates the execution environment for each plugin
  • SafeWebpack: intercepts Webpack APIs to sandbox them
  • Permissions: handles allowed/disallowed permissions, UI to ask the user
• Bundler: bundles plugin/theme source code into usable code for the browser
  • Manager: handles input and passes into bundler, passes return code to Onyx, uses handlers (start, stop, etc)
  • Source map generator ("mapgen"): generates source maps from generated output from bundler

Bundler

The bundler is the core part of Topaz, allowing plugins and themes to "just" run without needing Git/etc. The bundler is largely from scratch, just using a few 3rd party dependencies for transpiling (Sucrase for JSX/TS/TSX -> JS, Grass for SCSS -> CSS). It is designed purely for in browser / over the network use, it does not use any local files/etc. It primarily supports CJS with some experimental/WIP ESM support. It supports most bundler things, such as:

• Transpiling supersets (JSX/TS/TSX, SCSS)
• Resolving and embedding imports at bundle-time
• Source maps (see mapgen)

Some features are out of scope / unneeded for it's purpose and won't be done, such as:

• Minification, code splitting, tree shaking - as plugins are cached/stored locally size is not a focus
• Transpiling down ES levels (ES5/etc) - Topaz targets latest browsers only

Storage

Topaz stores with IndexedDB with a custom wrapper (see storage.js) which also features localStorage compat. It just stores an object (store) in one object store in one value, to allow sync operations (not requiring async). This also allows it to act as a cache.