Tech Exploration for In-Browser Node Playground

[amiller-gh]

Branching this conversation off from #9.

There is strong interest to bring a "try it in your browser" feature to the new website. We need to evaluate and choose a technical strategy to pull this off.

Deliverable from this ticket should be a fleshed out tech proposal for a node playground on nodejs.org.

Options already discussed (in order of my personal opinions on feasibility 😉):

1. Use an existing "runnable snippets" service (Ex: Glot.io is open source and provides an API)
2. Run it all in-browser (Ex: by bundling browserify native package shims for dummy behavior)
3. Run our own container to execute simple programs (would like to avoid)
4. Code dummy REPLs to only run the commends requires for specific examples.

---

1) Use Existing Service

Pros:

• Security and maintenance is someone else's issue
• Should work out of the box
• Actually runs real code. No unexpected behavior.

Cons:

• We become dependent on an external service (risk may be mitigated by using an open source solution)
• Potential added complexity to the website.
• Cost? Not sure what pricing models look like here.

2) In-Browser Solution

Pros:

• Static! Build it once and forget it. No network, hosting, or 3rd pary required.
• Runs "real"-ish code. Will do well enough for limited demos.
• Bragging rights. Really shows off that Node is just JavasScript.

Cons:

• Potential security risks?
• Potential unexpected behavior from in-browser shims.
• We will have to maintain it.
• Will bloat page size (Fix: lazy loading?..)

3) Run our own container service

Pros:

• We control it.
• Actually runs real code. No unexpected behavior.

Cons:

• SECURITY.
• Time and maintenance cost.
• We really shouldn't pick this option.

4) Dummy REPL

Pros:

• Potentially simplest solution.
• Doesn't actually run code, no security risk.

Cons:

• Doesn't actually allow you to write / run code like you would want. I question if this is the ideal UX.
• Dummy REPL may be too complex to actually handle all cases we'd want from interactive demos.

[jennschiffer]

Hi! I'm Jenn Schiffer, the community engineer on Glitch.com, and I wanted to throw our "existing service" into the ring here and answer to the thoughtful cons you listed. Glitch is an app community that includes an in-browser collaborative editor for free and deploys apps as the code is edited. We support Node primarily and allow users to show their entire app's source - not just client-side files, making it a great option for sandboxing in documentation.

Glitch apps and their source can be nicely embedded into web pages (our URLs are also supported by oembed), so we'd anticipate very little, if any, complexity being added to the site setting it up. And we don't lock people into the service (we provide a console along with buttons to import/export from/to github and download a gzip folder of the app). The apps are run based off of normal scripts in the package.json file - if it runs on Glitch it can run on any Node server. An additional "pro" of using Glitch is that being connected into a community with an existing network of contributors means your examples can be improved and updated by people who may not have even gone to the Nodejs.org.

Node is a huge part of our mission, tech stack, and how our community builds the open Web, and we would love to further help the project - I think this would be a great opportunity to do that. We’re also willing to commit in writing to providing the service at no cost as our way of supporting the Node community we’re part of, so the Foundation won’t be taking on any risk there.

If you have any questions I'll be happy to answer them whenever/wherever!

[keywordnew]

allow users to show their entire app's source - not just client-side files, making it a great option for sandboxing in documentation.

This is a useful thing to want from any chosen solution. (I think) this could make it easier for anyone updating examples in future and doing long-term maintenance. They would not need to update the source code on the service, then go to update our documentation in our own repo, potentially letting documentation get out of date. Editing the source + documentation could be done in one place.

[keywordnew]

From meeting #24: The material in #18 will likely inform what this in-browser playground demos.

[keywordnew]

There is additional context around the RunKit option:
#27 (comment)

[tolmasky]

Hi everyone, the RunKit team shared a few demos at the meeting today of how RunKit could be used both for the Getting Started page as well as actual API documentation. I'm providing these demos here for anyone else who wants to take a look, as well as the github repo it's being hosted at (we might be continuing to update these demos as its serving as a greattest bed for some of our new unshipped features).

Site: http://nodejs-org-runkit-demo.com/
Github: https://github.com/nodejs-org-runkit-demo/nodejs-org-runkit-demo.github.io/tree/source

The API documentation demo linked in that page is currently just being generated from more or less the unchanged markdown files used to generate the current docs, we've simply re-arranged the flow but haven't spent any time "rethinking" the examples themselves for this sort of "try-first" model, and I think there could be a lot of great opportunities there.

The main idea behind the Getting Started prototype is to have many different kinds of "Getting Starteds" for the many different uses of Node -- people who want to make a microservice vs a terminal app would be best served with different tutorials. We've only really fleshed out the first two sections (as we've been making them fairly custom), but I think it does a good job of conveying the idea.

Thanks!

[amiller-gh]

Thank you @tolmasky for the amazing demos today! They certainly helped us wrap our head around what RunKit is capable of providing for this project. For API snippets and single-file tutorials I think RunKit provides amazing utility.

I'd love to also see, as you mentioned in the meeting, how we can set up a milti-file snippet for some potentially more complicated and module-focused examples. I think we'll have to see how many of these complicated demos we will actually have after we work out the exact content for our "getting started" and "advanced tutorials" tracks, but I can't imagine a situation where we don't have at least a few – modules are such a central concept in Node.js

[MarkTiedemann]

Since this feature is mainly targeted at people new to Node, I think it would make sense for a good first impression to provide them with some sort of syntax highlighting, error squiggles, auto-completion and IntelliSense just like you would get in your code editor (for example, by using an editor like Microsoft/monaco-editor).

[Trott]

I've unarchived this repo so I can close all PRs and issues before re-archiving.