Interactive code snippets: first draft of Klipse integration

[viebel]

Let's try to have interactive code snippets inside the reactjs documentation and tutorials.
It will be very helpful for newcomers.

Here is a first draft of an integration of Klipse (as it was suggested in #26) using gatsby-plugin-klipse written by @ahmedelgabri.

It looks like this:

You can see the live version here: Enjoy the interactivity!!

There are a few issues:

1. When using ~~~klipse-transpile-jsx instead of <pre><code class="gatsby-code-klipse-transpile-jsx"></code></pre>, the snippet is embedded in a .gatsby-highlight that has a black background
2. One has to escape the html tags inside the snippet so instead of <, we have to write &lt' which is quite cumnbersome
3. Currently the klipse javascript tag is added to all the pages. We need to find a way to selectively add it to a page. See [Question][Plugins] Loading assets on demand? gatsbyjs/gatsby#2681
4. CircleCi has failed: it looks like a network issue.

[reactjs-bot]

Deploy preview ready!

Built with commit 3b5eb3e

https://deploy-preview-236--reactjs.netlify.com

[bvaughn]

Thank you for submitting this proof of concept PR. 😄

This component seems functionally similar to the interactive CodeEditor component we use on the home page. (It has a "JSX?" toggle that can be used to show what the JSX compiles to.) I suppose it's different in that:

• This embeds code that's defined directly within the markdown- which is nice and light-weight.
• It doesn't actually execute the code, only compiles it, which is also nice in some cases.

But it also comes at a pretty large cost; the klipse_plugin.min.js dependency this plug-in adds is 226 kB gzipped and it also requires Babel which adds another 217 kB gzipped. Due to its size, it also takes a pretty long time to parse and execute (even on my relatively new Macbook Pro):

One the one hand, we already load Babel for the examples on the home page, but we only load it if we're actually going to use it. Scoping Klipse to load only for pages that use it would help a bit, but I think the added weight is still too much.

This is a cool proof of concept. Thanks again for sharing it! I think it's best to pass on it for now though, for the reasons mentions above. Let's talk more if you have questions or if I'm misunderstood or misrepresented anything in my initial review. 😄

[viebel]

Hi @bvaughn !

Thanks for your feedback.
I understand your concerns about the size and the execution time of the Klipse plugin.
As you mentioned, we could reduce it a bit by making sure that Klipse is not loaded on all pages and not to load the babel plugin from Klipse - as it is already on the page.

More generally, I'd like to better understand your concern: do you think that the user experience is impacted by the time it takes to load and evaluate the script? I've tried to load the page a couple of times on my MacBook pro and I was not able to feel any page freeze or inconsistent UI.

Do you have a different user experience?

[bvaughn]

More generally, I'd like to better understand your concern: do you think that the user experience is impacted by the time it takes to load and evaluate the script? I've tried to load the page a couple of times on my MacBook pro and I was not able to feel any page freeze or inconsistent UI.

Yes, definitely. On the one hand, most people viewing this website are likely developers and so probably have pretty decent hardware. But many are still probably running on machines that are less powerful than your MacBook Pro and maybe in areas with poorer connectivity. A janky loading experience (eg content that shifts and changes after a couple of seconds as the page loads in, and JS parsing that locks the main thread and makes the browser feel unresponsive) is a super frustrating user experience. (Flowtype's REPL is a great example of the latter.)

[viebel]

What about adding a button that will allow the user to make the code snippets interactive?
There won't be any performance hit for standard users and this will allow curious users to play with the code snippets...

[alexkrolick]

Would it be possible to server-side render the interactive snippets?

[viebel]

@alexkrolick interesting idea...

[bvaughn]

What about adding a button that will allow the user to make the code snippets interactive?

I'm not convinced that there is a lot of added value in showing what JSX compiles to all throughout the docs, so long as we cover it in a few places (like the home page and dedicated sections like "React without JSX".

Maybe others feel differently? If so they should weigh in! 😄

[viebel]

I'm not convinced that there is a lot of added value in showing what JSX compiles to all throughout the docs

@bvaughn in some places it is useful to show what JSX compiles to while in other places it is more pertinent to show the result of the rendering. Klipse supports both.

The added value of Klipse is that it allows the user to modify the code of the documentation and see how it affects the output. Some kind of "learning by playing" 😄

[bvaughn]

I understand the value of playing with the code and seeing the output. That's why we have the interactive examples on the home page. I think that the majority of our code snippets within the docs wouldn't be runnable though. They're almost always just showing small concepts.

That's why I assumed the only functionality we'd actually get to use for them was the JSX-to-plain-JS transform.

[viebel]

Some parts of the doc contain interesting runnable code snippets.
See for instance a "Klipsification" of an old version of the article about controlled components: http://blog.klipse.tech/react/2016/12/20/react-controlled-components.html