Migrate examples to CodeSandbox

[bvaughn]

The docs site currently links to Codepen.io in several places, eg "Try it on CodePen". This is a maintenance burden for a few reasons:

• These pens are versioned separately from the website and so they can get stale.
• Updating them is a hassle. (Currently updates have to be done by @gaearon since he created the pens.)
• OSS users can't contribute fixes without forking the pens, which would make them harder still to update in the future.

CodeSandbox has a feature to import pens directly from GitHub. This sounds great! If our pens lived in GitHub then it would be much easier to keep them synchronized with docs changes. (Also CodeSandbox is slick ❤️ !)

Open questions

Ideally we could group all of the current pens together into a single folder (eg sandbox) and then deep-link to individual example files. However after a brief look at the CodeSandbox feature, I believe it treats an entire git repository as a single project.

Considerations

It's possible that the levels of traffic the React website sees would cause scaling problems for CodeSandbox. We might want to try this integration in some limited form at first, with reduced traffic.

cc @CompuIves in case you're interested in collaborating on this

[CompuIves]

Absolutely, I'd love to collaborate and make this happen!

Ideally we could group all of the current pens together into a single folder (eg sandbox) and then deep-link to individual example files. However after a brief look at the CodeSandbox feature, I believe it treats an entire git repository as a single project.

Both approaches would work. I'd suggest using the same strategy as redux: create an examples folder with create-react-app projects and link them separately. An example URL would look like this for examples/portal folder:

https://codesandbox.io/s/github/reactjs/reactjs.org/tree/master/examples/portal

The advantage of having separate CRA projects is that the user can easily clone/download the CRA project from GitHub/CodeSandbox and continue working locally. We also show what a possible (recommended) project structure is from the beginning.

It's possible that the levels of traffic the React website sees would cause scaling problems for CodeSandbox. We might want to try this integration in some limited form at first, with reduced traffic.

Since we leverage the browser for 95% of the work I'm fairly positive that we can handle a lot of traffic. Though maybe we come across other bottlenecks, so I agree that it would be safest to test it in a limited form first. Maybe we can move the examples one by one gradually over, evaluating after every update how the servers hold. We could also create a simple script (like if (Math.random() > 0.5)) that allows us to sort of 'AB-test' old vs new, and gradually increase it.

I'm curious what you think! I'm willing to create a PR with examples moved over instantly 😄 .

[gaearon]

Another thing that’s concerning: we need to look how much JS is downloaded by CodeSandbox vs CodePen. Not everyone has a great internet connection.

[bvaughn]

If you're willing to put together a proof of concept for 1 or 2 pens, @CompuIves, I'd love to review a PR. The Netlify preview will give us a nice way to see how much JS is downloaded too.

[EricSimons]

Hey all! This seems related to #18 — great to see the discussion moving fwd :)

@bvaughn I def agree with your main points here; having pens automatically imported from Github is a great idea. Also totally agree reg scaling problems + @gaearon's comments about payload size; we definitely don't want to hurt the UX of browsing React documentation examples.

Since Webpackbin and StackBlitz also support importing pens directly from Github & have expressed interest in hosting the React doc examples, perhaps it would make sense to release some decision making criteria that the team will use for picking the best solution? (For ex: uptime reliability, total JS payload size, etc). This would also ensure everyone in the React community has an equal opportunity to compete for this coveted honor :)

[bvaughn]

Hey @EricSimons, thanks for weighing in. I'm sure we'd all love to see sample integrations from other online IDEs as well. Would you be interested in putting a PR together? (Or would you know who to reach out to about this?)

I don't think we have any formal "decision making criteria" other than what you listed, but I'll take a stab at things I would consider:

• Minimal boilerplate: Updating examples or adding new examples shouldn't require a ton of boilerplate. I think all of our examples are just a single JavaScript file. Since the only thing that varies between these examples is JavaScript, it would be nice to avoid or limit redundant boilerplate files like package.json and index.html in order to help with maintenance.
• Payload size: The smaller the better for our users I think.
• Download speeds and uptime reliability.

Currently we link from docs to pens (eg "Try it on CodePen"). Depending on the payload size, maybe it could be nice to embed some of the examples directly within the React docs. Issue #26 is kind of related to this.

[EricSimons]

@bvaughn definitely! I'm on the road until tmrw but I can put in a PR for a sample StackBlitz integration this wknd. Looping in @christianalfoni here re: Webpackbin 🍻

[alexkrolick]

Re: download sizes

What if instead of using CRA, you use UMD builds from a CDN (unpkg?) with script tags inside of Codesandbox? Then you can still version control it, but the packages will be cached as you view more examples. It also keeps the examples pretty lightweight.

[bvaughn]

What if instead of using CRA, you use UMD builds from a CDN (unpkg?) with script tags inside of Codesandbox? Then you can still version control it, but the packages will be cached as you view more examples. It also keeps the examples pretty lightweight.

I like the idea of caching packages via unpkg.

[EricSimons]

I was actually thinking the same thing re: unpkg builds, and then it got me thinking: why use StackBlitz/Codesandbox at all? All of the current examples are single files and use UMD builds for deps anyways, so the unique value prop of SB/CSB (importing from NPM + bundling features) would be completely unused.

Instead, I'm thinking we create a simple open source playground that's statically hosted on the docs' netlify itself. That would cover @bvaughn's point about reliability/uptime/download speed (as the payload size would be super small since it's tailored specifically for this use case) + would allow @CompuIves, @christianalfoni, and I to pool our efforts for creating the best experience specifically for the React docs 💪

@CompuIves @bvaughn would love to hear your thoughts — happy to get a repo set up for this if ya'll think it's a good idea!

[CompuIves]

Hmm, I think you miss some advantages this way though. When you find a bug or need help you can't fork the code to show what you mean. You also lose discoverability, in the case of codesandbox if users want an example of eg. error boundaries they can use the search function to search through official examples. And I think that it's great to show an online editor like your local editor for more advanced examples, like portals.

Though I do like the idea of a kind of hybrid approach, I'm a fan of react-live, maybe we could use that to show examples with an extra option to open it in an online editor. That way people can play inline, it's hosted locally and you give the option to fork it for more experimenting or reproducing errors.

Regarding the unpkg versions, with the new CodeSandbox packager we use the umd bundles behind the scenes and cache them on Amazon Cloudfront and with service workers. So the download size should be about the same as react+react-dom umd. We also expose an option to use the umd build from unpkg directly, we could also do that.

[bvaughn]

Instead, I'm thinking we create a simple open source playground that's statically hosted on the docs' netlify itself.

I had also considered this- prior to seeing that CodeSandbox had an import-from-GH feature. I've built a couple of REPLs at this point. It wouldn't be hard to just create an endpoint (on the reactjs.org site) that pulls a file from the docs GitHub repo. Had also thought a bit about a custom Gatsy plug-in that converted code examples in the markdown into an editable/live REPL.

There's lots of ways we could do this. 😄 At this point, tossing around ideas and trying proofs of concept is good.