The future of the Live Examples sandbox - StackBlitz integration

[mhawryluk]

We want our Live Examples page to offer the best possible experience of exploring the library. Live updates, integrated code editor, example controls and such bring a big value to the product website. However, we are still working on improving some major aspects of the experience.

Taking inspiration from other similar solutions, we aimed to use WebContainers, to enclose the example code evaluation in a separated sandbox, to make the site safer. While this approach is still something we want to potentially explore in the future, for now we find that using an integration with an existing code sandbox solution is the way to go.

Main challenges when implementing fully custom web containers sandbox:

• achieving high stability and low latency
• having the example visible immediately to not discourage visitors
• implementing communication code editor <-> container, as well as example controls panel <-> container
• using experimental library features in the sandbox

The current proposal is therefore as follows:

1. Make the code editor in all examples readonly. This would ensure safety of evaluation and allow reducing a lot of our code complexity.
2. Add a "Open in StackBlitz" button for each example. Using the StackBlitz SDK we can dynamically create projects containing the default example code, which users can modify and watch the example updated live in the preview.
3. Verify whether StackBlitz sandbox can be embedded inside our page, without redirecting to a new tab.
4. StackBlitz sandbox will use the official, published version of the library, while the default readonly examples can still use experimental.
5. Modify how example controls work. Instead of comments above exported functions and use of the babel plugin, export objects like so:

export const Slider1 = {
  onChange: () => {...},
  range: [1, 2],
};

export const Button = {
  onClick: () => {...},
  label: 'reset',
};

The example can be in its own example.ts file (the only one that user should want to modify). Then in another file (index.ts) we can import every exported example control object and construct the example control panel from it.

// This is to create controls automatically. Please edit 'example.ts' instead.

import * as controls from './example.ts';

...

[reczkok]

While I love our current live examples experience I understand that there are some compromises if we want to provide a safe experience. I think turning the examples readonly is a big blow for the overall impression and will be an additional hurdle for people who would like to tinker with them. There are countless times that I wanted to check how some small change would affect one of the WebGPU Samples only to realize once again that it's not editable. Having to redirect users to an external website may be okey depending on how fast the project creation on StackBlitz is. Embedding StackBlitz sandbox would be the ideal solution that would solve most of the concerns raised, although I assume there will be some difficulties with the integration (life is never so easy with high level APIs).