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 https://github.com/reactjs/reactjs.org/issues/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.

[EricSimons]

@CompuIves holy cow, react-live is awesome! This is def what we should use for this — super small footprint too (64k!). Love the idea about the hybrid approach w/ ability to fork for experimenting/repro-ing errors.

I also agree about wanting to preserve the ability to fork/etc — I think this is easily solved by just using Codepen's POST API to prefill their editor with the current file data in the react-live editor. Sticking with Codepen for this sort of functionality would also ensure concerns around performance/uptime are addressed (as Codepen already runs the examples reliably right now).

@bvaughn I dig the Gatsby plugin idea — I'll start working on a react-live based editor and create a couple proof of concepts w/ Gatsby integration :) @CompuIves wanna join in on this w/ me?

[bvaughn]

@CompuIves holy cow, react-live is awesome

We're using react-live on the home page for our live editor examples. We've got a small wrapper component, CodeEditor, around it.

If we used it for this functionality too, maybe we could have a button that exported the code being edited into a CodeSandbox / CodePen / WebpackBin / StackBlitz for saving and sharing?

[CompuIves]

Sounds great! I already started with a remark plugin this afternoon that takes a file and shows syntax highlighted code with a CodeSandbox url, maybe we can make it work with React Live! I have a wedding this evening but I can share it tomorrow.

I still think it would be best to export to an online editor like CodeSandbox/Stackblitz/WebpackBin, for the reasons I mentioned (discoverability, local editor feeling, more 'real life' code with imports). If someone wants to add a dependency that's also easily possible then.

On Thu, Oct 12, 2017, 20:24 Brian Vaughn notifications@github.com wrote:

@CompuIves https://github.com/compuives holy cow, react-live is awesome

We're using react-live on the home page for our live editor examples. We've got a small wrapper component, CodeEditor https://github.com/reactjs/reactjs.org/blob/master/src/components/CodeEditor/CodeEditor.js, around it.

If we used it for this functionality too, maybe we could have a button that exported the code being edited into a CodeSandbox / CodePen / WebpackBin / StackBlitz for saving and sharing?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336224136, or mute the thread https://github.com/notifications/unsubscribe-auth/AAj1CF8zJxCWck_NEhnJAMK_03Vqf_o0ks5srllKgaJpZM4P0RPj .

[EricSimons]

@bvaughn whaaa I didn't even realize that! I love the idea for a button to export — that def would provide the best UX. Perhaps the button click triggers a dropdown with Codepen/StackBlitz/Codesandbox/etc as export options?

[EricSimons]

I still think it would be best to export to an online editor like CodeSandbox/Stackblitz/WebpackBin, for the reasons I mentioned (discoverability, local editor feeling, more 'real life' code with imports). If someone wants to add a dependency that's also easily possible then.

@CompuIves I think supporting Codepen + SB/CSB/etc as @bvaughn mentioned is the right move. I actually think that Codepen should be the "primary" option for exporting because their UI is so simple & easy to get started with, which is important because most forks are prob going to be created by devs just starting to learn React for questions/issues about React itself.

Per https://github.com/reactjs/reactjs.org/issues/18, it prob makes sense to mention CodeSandbox/StackBlitz towards the ends of the docs when they talk about running CRA locally, as those learners are at a point where they are "graduating" from simple examples and SB/CSB provide an excellent middle ground between Codepen and CRA 👍

[bvaughn]

Perhaps the button click triggers a dropdown with Codepen/StackBlitz/Codesandbox/etc as export options?

Sure, maybe, assuming these provide an API to easily import the current contents of CodeEditor. 😄

[EricSimons]

@bvaughn codepen's post API definitely checks that box! I'm sure the rest of us will be happy to set up similar endpoints as well :)

[CompuIves]

I actually think that Codepen should be the "primary" option for exporting because their UI is so simple & easy to get started with, which is important because most forks are prob going to be created by devs just starting to learn React for questions/issues about React itself.

I don't necessarily agree with this, CodeSandbox was built with a focus on absolute beginners from the start and many beginners have already learned React using CodeSandbox. We're used on several bootcamps and universities as well for teaching React. We even go a step further and transform errors to friendlier versions and use react-error-overlay to lower the learning curve.

I agree with all the other points though, I'll open source what I've made tomorrow!

On Thu, Oct 12, 2017, 20:44 Eric Simons notifications@github.com wrote:

@bvaughn https://github.com/bvaughn codepen's post API definitely checks that box! I'm sure the rest of us will be happy to set up similar endpoints as well :)

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336229620, or mute the thread https://github.com/notifications/unsubscribe-auth/AAj1CIdk4CJsLj3qLNiwcuzDLOnJSO0uks5srl4AgaJpZM4P0RPj .

[bvaughn]

Maybe we make a "Fork this example" button that opens a small modal that has links to Codepen, CodeSandbox, etc - to give users a choice.

As a user, I might have an account with one already, or a familiarity with it.

[alexkrolick]

It seems like the tricky part with export is getting all the dependencies included in the right way for each target. E.g. Codepen has a "JS" tab that can point to a CDN, and Codesandbox has the "modules" section which points at NPM. If you could guarantee that each target would have exactly one CSS, HTML, and JS file, and include all deps as <script> it might make things significantly easier.

There's also the different Babel environments to worry about. Codepen doesn't have stage-2 for example, so class properties are a no-go.

@CompuIves how about a React template that marks the core libs as external in its webpack builds? That could speed things up a fair amount and make it possible to comply with the same schema as Codepen without adding import statements.

[EricSimons]

@alexkrolick this actually won't be too hard; unpkg already uses version numbers in the URL so the POST requests made to StackBlitz/CSB/etc could just include an object listing the deps and their versions (for ex, { 'react': '16.0.0' })

[EricSimons]

^ I'm working on the UI for the dropdown now; will report back once I have a demo!

[CompuIves]

@CompuIves how about a React template that marks the core libs as external in its webpack builds? That could speed things up a fair amount and make it possible to comply with the same schema as Codepen without adding import statements.

Yep, that should be possible, but might seem confusing since then we get 2 different react templates on codesandbox that look the same, but have small differences. I also think that using create react app is advantageous since the user is in a recommended toolbox from the get go.

We currently infer this data from the github template, can't we use the github import (a bit like redux) for this? This allows users to fork and download the examples locally as well. The download size wouldn't increase and from a clutter perspective this is better because we don't fork for every view.

On Thu, Oct 12, 2017, 22:12 Eric Simons notifications@github.com wrote:

^ I'm working on the UI for the dropdown now; will report back once I have a demo!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336252274, or mute the thread https://github.com/notifications/unsubscribe-auth/AAj1CMwvkJvtJmLl3nJ66veUeuGICa8Hks5srnKigaJpZM4P0RPj .

[CompuIves]

I'm not sure if I'm viewing this the wrong way, but using a POST endpoint feels like a dumbed down version of the git support. It feels like extra work for a solution that would be more cumbersome for the users and for our API.

On Thu, Oct 12, 2017, 22:47 Ives van Hoorne ives.v.h@gmail.com wrote:

@CompuIves how about a React template that marks the core libs as external in its webpack builds? That could speed things up a fair amount and make it possible to comply with the same schema as Codepen without adding import statements.

Yep, that should be possible, but might seem confusing since then we get 2 different react templates on codesandbox that look the same, but have small differences. I also think that using create react app is advantageous since the user is in a recommended toolbox from the get go.

We currently infer this data from the github template, can't we use the github import (a bit like redux) for this? This allows users to fork and download the examples locally as well. The download size wouldn't increase and from a clutter perspective this is better because we don't fork for every view.

On Thu, Oct 12, 2017, 22:12 Eric Simons notifications@github.com wrote:

^ I'm working on the UI for the dropdown now; will report back once I have a demo!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336252274, or mute the thread https://github.com/notifications/unsubscribe-auth/AAj1CMwvkJvtJmLl3nJ66veUeuGICa8Hks5srnKigaJpZM4P0RPj .

[CompuIves]

Oh! I think I know of something that could work as a combination. I'll send it tomorrow.

On Thu, Oct 12, 2017, 22:51 Ives van Hoorne ives.v.h@gmail.com wrote:

I'm not sure if I'm viewing this the wrong way, but using a POST endpoint feels like a dumbed down version of the git support. It feels like extra work for a solution that would be more cumbersome for the users and for our API.

On Thu, Oct 12, 2017, 22:47 Ives van Hoorne ives.v.h@gmail.com wrote:

@CompuIves how about a React template that marks the core libs as external in its webpack builds? That could speed things up a fair amount and make it possible to comply with the same schema as Codepen without adding import statements.

Yep, that should be possible, but might seem confusing since then we get 2 different react templates on codesandbox that look the same, but have small differences. I also think that using create react app is advantageous since the user is in a recommended toolbox from the get go.

We currently infer this data from the github template, can't we use the github import (a bit like redux) for this? This allows users to fork and download the examples locally as well. The download size wouldn't increase and from a clutter perspective this is better because we don't fork for every view.

On Thu, Oct 12, 2017, 22:12 Eric Simons notifications@github.com wrote:

^ I'm working on the UI for the dropdown now; will report back once I have a demo!

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336252274, or mute the thread https://github.com/notifications/unsubscribe-auth/AAj1CMwvkJvtJmLl3nJ66veUeuGICa8Hks5srnKigaJpZM4P0RPj .

[EricSimons]

I spent a little time digging into the react-live + dropdown stuff yesterday and I actually think this will be pretty straightforward to pull off. That said, there are a few small hiccups reg the react-live editors that we'd need to sort out. For example, the current react-live examples all end with:

ReactDOM.render(
  <HelloMessage name="Jane" />,
  mountNode
);

with the key problem being mountNode, whereas in the codepen examples, they pass along document.getElementById('root'). This could prob be solved by regex replace document.getElementById('root') for mountNode from the JS source files before they're passed into the CodeEditor component (especially if we're using a custom gatsby plugin similar to what @CompuIves made in https://github.com/reactjs/reactjs.org/pull/138#issuecomment-336492351).

This would also enable one-click forking for Codepen via their POST API, and StackBlitz/CSB/etc could do something similar or point at the source files themselves in the github repo.

This brings me to another question (mostly for @bvaughn I think): would we want to use react-live on all examples? Or would we want to still display many of them via Prism (which is currently how it works)?

If it's the latter, then perhaps the best first step is just creating the dropdown menu to go underneath the current Prism codeblocks and not taking on the various challenges reg react-live quite yet. Since the dropdown will include exporting to Codepen (plus new providers like StackBlitz, Codesandbox, etc), this would ensure the concerns around payload size/reliability/etc are addressed since Codepen isn't being replaced as an export target. It would also solve the key headaches around updating the examples, as they would all be contained within this repo in individual JS files.

Once the dropdown is on prod & battle tested, we could then circle back to revamping react-live for embedded usage in the docs (if that's still desired)

[CompuIves]

Hmm, to be completely honest I don't think that showing a dropdown with different editors is beneficial for the user. It seems like we're falling back to "suggesting more tools" like @gaearon said, which is why this issue started for discussion on how to approach this.

If someone wants to play with an example, and gets 4 editor choices when clicking on a dropdown, it will definitely confuse the user. Showing CodePen as main option would solve this partially, but honestly I don't think that CodePen is the best editor to show either. It doesn't have things like error transformers, or an error overlay, or an option to download the example to a pregenerated CRA template, or things like eslint and autocomplete. These are all very valuable tools for beginners learning React. CodePen has many uses, I also use it daily, but it's not specialized for React development.

Objectively, I think we're now discussing adding all these different editors to make it fair for CodeSandbox/StackBlitz/CodePen (the parties involved), but we're compromising the user/UX because of this. The only added advantage I see is that we give the user a choice, but I believe we shouldn't give beginners many choices to begin with (fatigue).

[EricSimons]

@CompuIves I obv agree that both StackBlitz & CodeSandbox are incredible environments for learners, but the point of this issue is to solve the maintainers current pain points. Per @bvaughn, these are:

• The 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.

Note that there's no mention of Codepen itself being an inadequate solution to their needs (besides Github integration, which is now solved w/ POST endpoint solution). I'm sure they'd also love to let users have access to NPM, bundling, robust error handling and other features in StackBlitz/CSB, but those also are not present in the key solution criteria that @bvaughn laid out:

• 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.

Both StackBlitz and CodeSandbox have existed less than a year, lack meaningful funding, and do not have time proven track records in regards to download speeds and uptime reliability. These pose as a major risk for a $500B company's most popular OSS project's documentation. Further, CSB & SB payload sizes are also (at best) 2x what Codepen's is. Despite all of the awesome functionality we have, the folks learning React in India off of spotty 3G connections will have to wait at least twice as long to begin using the editor — and that's assuming the request doesn't fail in the first place.

I don't see any arguments here that negate Codepen's proven track record, smaller footprint, and uptime reliability. And considering they're also the largest & most widely used online editing environment, I don't think there's a valid argument that their UX is so poor that it makes gambling on StackBlitz or CSB worth the risk.

Would I love to see all of React's examples being hosted on StackBlitz exclusively? Of course—but considering the requirements Brian & team have outlined, I genuinely don't think leaving Codepen is the right solution for their needs and suggesting otherwise would feel disingenuous.

That said, I'd be honored to see StackBlitz & Codesandbox listed alongside Codepen should we agree about the UX considerations. Since @bvaughn originally suggested the dropdown idea, I think it would be great to hear his thoughts here about this! 🍻

[PerStirpes]

🍿

[chriscoyier]

Hey gang!

Just chiming in here with the CodePen perspective, in case that's helpful. Of course, I totally understand you gotta do what's right for the project and your team.

1) Totally agree that being able to pull code from a repo and inject that into an embedded example is pretty awesome and would be better for a documentation environment that is in a repo anyway. We'd love to offer that, and it's on the list, but isn't right around the corner for us.

2) If it's helpful to have multiple people be able to update Pens, we'd be happy to create a "Team React" account (for free) where y'all could host the demos and you can invite whoever you like to that Team, who will all have editing access.

3) There are a couple of other features of CodeSandbox that I think are compelling. One is the transparency of seeing import React from 'react'; right in the JS (modules). We're headed in the direction of allowing that on CodePen. It's under development and closer than GitHub pulling, but I still couldn't say exactly when that will be ready.

[christianalfoni]

Hi guys :-)

Just chiming in with my thoughts after reading through the comments. I think it is a great idea to introduce CodeSandbox and StackBlitz in the React docs, but I do not think it is a good idea to integrate it with the current examples.

I think we all have a lot of assumptions and maybe not that much data backing it up :-) It would be interesting to know how many CodePens are actually forked vs people visiting the docs. If it is a small percentage it could be for whatever reasons. It is unlikely to be lack of options to other services though ;-) If it is a high percentage of forks/visitors it likely suggest that this is already a good solution.

So what I would suggest is rather introducing these services as "Okay, I am done with the docs... what now?". Introducing these tools as part of a "next steps" would give the person a natural transition to bringing in other NPM packages, deploy projects to the cloud etc... without actually installing anything locally, learning Node, NPM, build steps etc.

Okay... my cents :) Sorry if I missed anything in the discussion!

[CompuIves]

I think the major focus point should be on the user experience (documentation primarily exists for UX). Of course, maintainability is important, and it should be a priority, but we shouldn't neglect the UX.

Regarding the criteria, I'll cover them point by point in the case of CodeSandbox.

1. Minimal boilerplate:

We don't add much boilerplate. You only have to link to a single file and we infer the settings from the parent project. There is a maximum boilerplate of one CRA project, which is advantageous since in that project you can specify versions that will be propagated to all examples. This means that you only have to update a single file, package.json, to update dependencies for all examples. I think this is the best maintainability there is, especially when we add line highlight support using comment rules.

2. Payload size:

With the new packager we have a payload size of ~750KB for the embed (old packager has 900KB), this is 50KB more than CodePen.

3. Download speed and uptime reliability

I completely agree with this point. That's why I think it's a great idea to show the examples using react-live, we only give the option to fork code. This way you don't rely on an external service to show the code, but still give the option to the user to further work in a specialized environment for learning React. We also had a 100% uptime since we went online (last December).

That said, I'm of course biased. I'm curious what others think regarding this subject.

[EricSimons]

I think the major focus point should be on the user experience (documentation primarily exists for UX)

@CompuIves I think this is precisely why they want a solution with minimal payload size, fastest download speed, and highest uptime reliability: there is no worse UX than a product that randomly fails to work as intended.

^ StackBlitz also has it's fair share of random errors (we're all very new products after all), but that's precisely the point of why it's a bad idea to increase the scale of either of these services at this point in time, especially with the UX of the React docs at stake.

I personally 100% agree with what @christianalfoni suggested — would love to see some discussion around his ideas!

[EricSimons]

Just spent the past half hour creating https://github.com/reactjs/reactjs.org/pull/162 that seamlessly syncs example code from this repo to Codepen 👍

I think this elegantly solves the problems @bvaughn outlined about having to update pens manually (now you simply edit JS files in the examples folder and everything "just works"), plus it fully covers the key solution requirements regarding uptime & reliability (the React docs already trust & use Codepen).

Importantly, this solution introduces no major UX changes to the docs (current links to codepen now just point at a different URL), which should make adoption & rollout substantially faster if we decide to go down this route.

Would love to hear everyone's thoughts!

[jsonnull]

I think before moving forward with one integration service, a set of criteria should be decided on to compare alternatives. Download size and uptime have already been mentioned in this thread, and ease of update was brought up as an important factor. Something I personally care about is how long it takes for a sandbox to become runnable+editable, so maybe that time could be considered as well.

Once we have some concrete criteria and numbers for comparison, it should be possible to make arguments for/against specific services.

I would caution React contributors against diving into any particular solution before that, as the decision could be premature.

[EricSimons]

@jsonnull not sure if you were responding to my last comment, but just in case there's any confusion: my PR isn't recommending any new services to integrate with. The React docs already use Codepen for all of their examples — my PR simply allows them to automatically sync example code within this repo to Codepen, thus solving the core problem @bvaughn outlined when creating this issue.

[jsonnull]

my PR isn't recommending any new services to integrate with [...] my PR simply allows them to automatically sync example code within this repo to Codepen, thus solving the core problem @ bvaughn outlined

Maybe I wasn't following the sentiment of the thread very well, this just struck me as heavy-handed when there are contributors present who are discussing other alternatives. Namely, there's an unresolved thread as to whether CodeSandbox would be more suited to the task due to features and factors which have been mentioned in this thread.

Seeing as there wasn't a consensus as far as I could tell, I suggested a method for moving that discussion forward toward a solution while addressing unresolved questions brought up earlier in the thread.

[EricSimons]

[your PR] struck me as heavy-handed when there are contributors present who are discussing other alternatives.

@CompuIves has had a PR open for a Codesandbox integration for a few days now, though I wouldn't accuse him of being 'heavy-handed'. We're all just trying to throw our best ideas into the mix and see if the maintainers find them useful.

Namely, there's an unresolved thread as to whether CodeSandbox would be more suited to the task due to features and factors which have been mentioned in this thread.

I think that @bvaughn has done a great job of identifying the core problem and listing out the key solution criteria, all of which revolves around stability. Objectively, this is not an area that Codesandbox nor StackBlitz excels in. Happy to provide links & info if desired.

If the maintainers want to expand the scope of their solution criteria beyond stability to include product functionality such as NPM support, exporting to CRA, etc then I'd obviously love to make my case for why StackBlitz is a more scalable, stable & delightful solution. Until then, I'd rather focus our efforts on open source solutions that best serve the existing solution criteria.

[CompuIves]

I feel like I'm repeating myself here, but I guess I'll bite.

I don't believe the mentioned guidelines are set in stone, but I'll go point by point again for the sake of comparability. Here we go again.

Minimal boilerplate The solution of CodeSandbox has the least boilerplate and is most maintainable compared to the other proposed solutions. Files are synced with CodeSandbox and the documentation, and so are line highlights. We can link to separate files for every CRA project and have a central index.html/package.json.

Payload size I think this mainly comes down to how fast the editor loads. My last experimentation was inlining the sandbox embed in place of the actual code. This embed requires 900KB on initial load, and ~17KB (just the sandbox code) on any consecutive launch. An inline embed is always faster than opening an equivalent new page and, most importantly, keeps the user in context. I think this really is fast enough:

Download speed and uptime reliability Of course, I can't guarantee that there will be no bugs. But I can say that CodeSandbox is already used by many different libraries and frameworks (like Vue) for documentation. If there is a bug, it gets fixed quickly by one of our contributors or by me.

But remember that we're not talking about critical logic for the documentation here. If, in the worst case, CodeSandbox is down, everyone will still be able to see the code, they only cannot interact with it. I can build functionality to ping CodeSandbox and show a link to CodePen when the response time is >3000ms if that's a major concern.

Now these are three points, but the major benefit I see here is that this can be a gateway for new users to experiment further. If users open an example on CodeSandbox and want to build with examples/libraries that are found somewhere else on the web, then they are not limited to one file or only umd dependencies. This makes the learning traject much easier for a new user, because they don't have to download anything. Especially when you have error transformers, react-error-overlay and more than 60,000 other indexed examples to look at. When they decide that they like React, they can easily press download and get the files locally to continue from there. I can talk for a long time about this, I tried to distill the benefits in this talk.

I have the feeling that I'm starting to repeat myself and am getting tired of it. I also think that this discussion is becoming more and more of a burden for the maintainers, so I'll try to wait for a response from them before suggesting or defending CodeSandbox as solution.

[EricSimons]

Again Ives, the problem is not your functionality set or usage in the community, as you clearly check those boxes with flying colors. The problem comes down to reliability, because as I said earlier, there is no worse UX than a product that fails to work as intended. This is really, really hard for a 1 man (and in our case, 2 man) team to completely nail down. At the current scale of SB/CSB it doesn't matter too much, but when you're talking about adding millions of users accessing your site, that error only affecting 5% of people ends up being a big problem.

For ex, take the bug @bvaughn hit a week ago- it's still out in the wild negatively impacting users, and this has been happening for some time now. Windows users can't use CSB because there's no IE support. The list goes on.

Again, StackBlitz has it's fair share of issues. I have no problem admitting this — we take bug squashing & performance seriously but it's just part of the process of creating new products. However, it sounds like the React team wants to avoid the headache of dealing with tens of thousands of unhappy users when bugs like these occur, and I respect that decision. They're just trying to do what's right for their users, after all.

I'm also not the authority here on this matter, so we should probably just ask @bvaughn: At this point in time, is the React team willing to sacrifice reliability for additional functionality? I think a firm answer on that will help clear up any confusion I (and others) may have.

[CompuIves]

This is really, really hard for a 1 man (and in our case, 2 man) team

Fair enough, but I'm not alone. We're open source with 22 contributors.

For ex, take the bug @bvaughn hit a week ago- it's still out in the wild negatively impacting users, and this has been happening for some time now.

5 days. And this only happened to a small portion of the regular visitors of CodeSandbox. Fix will be out today or tomorrow.

Windows users can't use CSB because there's no IE support.

This is a good one! Just deployed the polyfills + support for IE.

The list goes on.

That list contains 6 minor bugs. Remaining 55 issues are feature requests.

I said I'd try not to respond, but I had to set the facts straight. I don't think criticizing work from others is constructive or helping at this moment.

[bvaughn]

Hi folks :smile:

I stepped away for the weekend to focus on some personal OSS projects and it looks like I missed a ton of discussion. Sorry for my silence!

I just read through the thread and I have a couple of thoughts (below) but first I want to say that no decision we make here is final. The new website is easy to update and deploy (thanks to Gatsby and Netlify). If we go with younger, less-proven tech for the site examples and it doesn't hold up- we can change it. I appreciate all of the considerations being discussed below above. Let's keep a collaborative spirit. :)

It seems like the tricky part with export is getting all the dependencies included in the right way for each target. E.g. Codepen has a "JS" tab that can point to a CDN, and Codesandbox has the "modules" section which points at NPM.

@alexkrolick I'm not convinced this is necessarily tricky. We could write an adapter for each export target. Then the only thing that would change would be the markdown-embedded JS script (aka text) that got sent through the adapter. That being said, I'm not sold on this feature being necessary. I just mentioned it as a possibility.

This brings me to another question (mostly for @bvaughn I think): would we want to use react-live on all examples? Or would we want to still display many of them via Prism (which is currently how it works)?

@EricSimons I have been picturing either a transform (custom Gatsby plug-in) or just a manual annotation to the markdown that would add "try it" links to some special code examples, like those on the home page (and maybe some others). But it wouldn't make sense to put these links with every code snippet because a lot of them don't really run, they just show a technique or style.

react-live and Babel also have size considerations. While we currently load them for the home page, we don't load them for any other page. I'd be reluctant to add their weight to every page with a code example. I like the idea of deferring cost until a user chooses to interact with an example (eg by clicking an "try it" linke).

To @CompuIves point, we could also build basic editor functionality into a new endpoint on the reactjs.org website. We would have to provider users with a way to share their "forks" - possible by using lz compression to store the code as part of the URL string like the Babel REPL does. But unless we spent a lot of time on it, it wouldn't offer the same rich feature set as the other options being discussed.

If it's helpful to have multiple people be able to update Pens, we'd be happy to create a "Team React" account (for free) where y'all could host the demos and you can invite whoever you like to that Team, who will all have editing access.

Hey @chriscoyier :) Thanks for chiming in! A shared group account could be nice. I actually created a "reactjs" (individual) account to share with the team but the more I thought about pulling code from GitHub directly, the more I liked the idea. Even just migrating Dan's ~80 examples to a new account would be kind of a drag.

Also a shared React team account wouldn't enable React users to improve the coding examples (without having to fork "official" pens).

I also appreciate your transparency about what features are not likely to become available soon. :+1:

I think we all have a lot of assumptions and maybe not that much data backing it up :-) It would be interesting to know how many CodePens are actually forked vs people visiting the docs.

@christianalfoni's I suspect a majority of the current forks are people trying to update/improve the docs (eg they get shared back with us via PRs). I think moving the examples ot GitHub will help a lot with this. I'm not sure how common it will be for people to want to fork at that point. I have no real data for this though, just "anecdata".

That's why I think it's a great idea to show the examples using react-live, we only give the option to fork code. This way you don't rely on an external service to show the code, but still give the option to the user to further work in a specialized environment for learning React. But remember that we're not talking about critical logic for the documentation here. If, in the worst case, CodeSandbox is down, everyone will still be able to see the code, they only cannot interact with it.

I agree with @CompuIves that removing CSB/CP/CB/etc from the critical path minimizes the risk.

[EricSimons]

@bvaughn thanks a ton for taking the time to read through all the comments & share your thoughts; there was definitely a lot of stuff to parse through in there. I'm actually not quite sure what the next steps are as of right now, so I've taken some time to re-read the thread & distill remaining q's (w/ context) as I imagine you're prob super busy :)

1: Should the docs use the existing CodeEditor component for embedding/running examples?

As opposed to custom integration with a 3rd party like Codepen, CSB, SB, etc. I think the answer is "yes" considering Brian's last comment above:

I agree that removing CSB/CP/CB/etc from the critical path minimizes the risk.

Concerns around payload size also addressed by Brian:

I like the idea of deferring cost until a user chooses to interact with an example (eg by clicking an "try it" link).

^ @CompuIves already has code written to do this on the CSB PR branch and has said he could swap in the CodeEditor component. There's also some elbow grease we'll need to put in to finish it up (see https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336539846) but it's quite minimal.

(PS @bvaughn — I'm seeing the same payload size for the homepage as well as doc pages; are you sure babel/etc are being split out into a separate bundle right now?)

2: Does it make sense to entirely get rid of Codepen?

This is the crux of the discussion @CompuIves and I were having. To recap, it seems like the biggest problem Brian wanted solved in his original comment was seamless syncing of examples in this repo to Codepen. https://github.com/reactjs/reactjs.org/pull/138 adds this functionality, which begs the question: does it make sense anymore to choose another provider to entirely replace Codepen? Related:

3: Does it make sense to enable "forking" on services other than Codepen?

@CompuIves has pointed out that it could be confusing to have a dropdown of multiple providers, although this could be nicely solved by having Codepen continue to be the "primary" export target. The other providers would then be included in an optional dropdown menu next to it, ensuring folks don't get confused up front with multiple options.

The only arg against keeping Codepen as the primary export target (which is that Codepen doesn't have as much functionality as CSB/SB/etc) is tied to the results of question # 2

4: Should CSB/SB/etc just be listed for "where to go next" instead of hosting the examples?

@christianalfoni made a good case for this in https://github.com/reactjs/reactjs.org/issues/122#issuecomment-336569792

[bvaughn]

(PS @bvaughn — I'm seeing the same payload size for the homepage as well as doc pages; are you sure babel/etc are being split out into a separate bundle right now?)

Babel is loaded from unpk (https://unpkg.com/babel-standalone@6.26.0/babel.min.js) to share cached bytes with other REPLs. It's only downloaded for the home page route.

As for "what's next", I see a couple of PRs have been opened relating to this issue. That's great! It's more of a response than I anticipated when I wrote this issue though, and so it's going to take more time to review and consider. Because of this, it will likely take me a couple of days to fit it into my work schedule. (Sorry!)

I'd prefer to hold off on discussing any more pros/cons until I've taken a look at the proofs of concept. Looking forward to it!

[bvaughn]

The feedback and community contributions for this issue have been fantastic. I'd like to express a heartfelt thanks to everyone who participated! I hope we continue this discussion moving forward.

I've spoken directly with @EricSimons and @CompuIves and for the time being, we're going to move forward with the more iterative Codepen solution (merged via #245). I'm going to close this issue since the primary pain point it expresses is addressed by way of that PR.

If you have additional ideas to improve the way we handle the examples- to make it easier for the community to contribute to the examples, or to make the examples more accessible- please open PRs and/or issues and let's talk. I've created one such follow-up issue already (#246).

Thanks again, everyone. ❤️