We’ve updated our example viewer!

For a long time now our examples have been built on top of Sandpack. This has been a powerful tool for us to provide interactive examples in our docs but it’s also come at a cost.

The problems

We liked Sandpack, but we kept brushing up against some pain points that ultimately we decided we couldn’t ignore.

  • Our examples were slow to load. Sandpack is an impressive tool, but it is also a heavy one. The sandpack client itself takes a moment to load, and then if an example included dependencies those would need to be fetched as well. For one-off example pages this wasn’t terrible, but particularly for longer docs pages like our guides or tutorials this could really kill the momentum.

  • Sandpack didn’t properly support Svelte when we first released Svelte Flow. Ultimately we ended up developing a separate SvelteKit app to host our Svelte examples and adapted our example viewer to switch between Sandpack examples and simple iframe embeds.

  • Finally, developing new examples was a pain. The source code for our React examples lived in folders deep inside our example viewer component and had special handling of certain files or formats that made authoring examples quite difficult: each change to an example would trigger a hot reload of our docs, which meant waiting for sandpack to reload and re-render the example again and again.

And on top of all that we had an entirely separate app we used to generate the screenshots for our examples overview page!

The solution

We were quite happy with how our Svelte examples worked (thank you Peter), and decided we wanted to explore a unified solution that would work for both our Svelte and React examples. In the end, we landed up with something even simpler than our SvelteKit app, dropping the need for a server entirely and instead serving everything from a static site.

We’ve created a single example-apps app in our monorepo that uses vite to serve our examples during development and build them into static files for production. If you’re curious, you can find a plain directory of all our examples over at examples-apps.xyflow.com.

We also made authoring examples easier. Developing examples now more closely resembles developing a standalone app, and we put together a simple scaffold script to help us quickly create new examples:

The scaffold script helps you quickly put together a new example for either
reactflow.dev or svelteflow.dev by copying over the boilerplate. All arguments
are *required*.
 
USAGE:
 
  pnpm scaffold <FRAMEWORK> <ROUTE>
 
EXAMPLES:
 
  pnpm scaffold react blog/web-audio/demo
 
  pnpm scaffold svelte guides/getting-started
 
ARGUMENTS:
 
  FRAMEWORK   'react' | 'svelte'
 
              The framework the example will be written in. This affects where
              the generated files are placed in conjuction with the ROUTE
              argument.
 
  ROUTE       string
 
              The route fragment the example app will be served at when combined
              with the FRAMEWORK argument. For example, calling the script as
              `pnpm scaffold react examples/nodes/custom-node` will scaffold
              the example and make it accessible at
              '/react/examples/nodes/custom-node/index.html'.

Are there any downsides?

We’ve lost one big feature in the transition: the ability to edit examples directly on the docs site. For some users this might be a big deal, but to compensate we now support opening the examples in StackBlitz in addition to CodeSandbox!

Wrap up

That’s all for now folks . For most people this change should be seamless with a free boost to performance to boot. If we’ve managed to break anything in the migration please let us know by opening an issue, and if you think the changes are excited we’d love if you tweeted about it and tagged us @xyflowdev!