Rxjs: Converting all examples to Stackblitz?

[ladyleet]

Description Of The Issue

We are potentially thinking about using converting Stackblitz.

Benefits:

Interactive examples.

Negatives:

Most operators are one or two line examples so it might be overkill.
If someone edits the example we don't want them to edit the example that everyone is seeing.
It should not be linked to someone else's Stackblitz.

Questions:

Are they embeddable?
Who has time for this?

IF YOU ARE GOING TO PROCEED:

Only do one conversion so we have time to discuss as a team the PR before spending too much time on it!

[ladyleet]

@benlesh @JWO719 @cartant anything I missed here?

[sulco]

Hey @ladyleet, I believe I can prepare a proposition of the solution.

I'd propose to look for inspiration in the Angular Material docs
(the button opens an example in a new tab):

https://material.angular.io/components/snack-bar/overview

• it's simple, unintrusive and, as the Material example shows, a pattern somewhat known/used in the community

Have you seen these? What are your thoughts on that?

[ladyleet]

@sulco that is so lovely of you! :) @benlesh i know you had a lot of thoughts about this. and @JWO719 as well. can y'all provide some guidance to @sulco ?

[Only1MrAnderson]

I am happy to help as well. Just simple like this? https://stackblitz.com/edit/rxjs-zjwhup

[ladyleet]

@Only1MrAnderson thank you so much!!! :) wait for their comments. :)

[Kajmeh]

I would like to help as well, just need to see one example or some guidelines

[JoshDSommer]

@ladyleet, @Kajmeh Here is the Async Subject example. it seems almost too easy.

AsyncSubject: https://stackblitz.com/edit/rxjs-uek8lm

I went to stack blitz, created a new RXJS project, then copied the example exactly from the existing demos here: https://rxjs.dev/guide/subject. Took a couple seconds if that.

Edit end up doing a couple more:

BehaviorSubject : https://stackblitz.com/edit/rxjs-x3bzem

ReplaySubject Example 1: https://stackblitz.com/edit/rxjs-19yeeu

ReplaySubject Example 2: https://stackblitz.com/edit/rxjs-f48pgj

[ladyleet]

@JoshDSommer isn't it lovely that it's so easy??? <3

[ladyleet]

@Kajmeh looking forward to your contributions too! :) super stoked folks are excited about helping with this! the core team is so busy, so it seems small, but is sooooooo awesome.

[sulco]

Just a heads up though, even though using the StackBlitz interface is super straightforward, using the StackBlitz API will provide a solution that is easier to maintain.

That way the source of the StackBlitz examples will originate in the git repository.

It will be less manual labor in the long run too.

[JoshDSommer]

@sulco I looked over the documentation and would be much easier to maintain in the future. Are you thinking one repo with multiple folders under it, one folder for each example containing:

    - index.html
    - index.ts
    - package.json

ReplaySubject
   ....

the AyncSubject folde contents being a clone of the contents of: https://stackblitz.com/edit/rxjs-f48pgj

Then using StackBlitz's API to open these or embed them like their examples https://stackblitz.com/edit/sdk-github-project

[gabrielgeorge]

Some of the functions already have a complete sample code.
Are we still going to give a stackblitz link in any case?

[dkosasih]

If someone edits the example we don't want them to edit the example that everyone is seeing.

I suggest maybe create the code under one user. So that the created user could fork from the contributors.
That way the example could stay consistent.

[MaryJJ]

Can I contribute with this example?
https://stackblitz.com/edit/rxjs-bm4nqh
I would like to make more examples. :)

[sulco]

@JoshDSommer yeah, that's precisely what I had in mind :)

[shobhitg]

Is there a way to have console opened by default in StackBlitz?

This is important because I can imagine that majority of RxJS examples are console based.

Also it would be nice to have a template so that there can be some user-friendly annotation/description.

For example: https://stackblitz.com/edit/rxjs-combinelatest-vs-zip

I guess there would need to be a github repo with a generic template which everyone can simply fork from.

[sulco]

Yes, you can configure console to be opened. Use the devToolsHeight parameter as per the sdk docs.

I actually have a working prototype of the solution:

The short story from the experiments: the js-only examples are be easy to cover without much changes (i.e. the current js code from the sources just needs imports).

The ones that require an html template (e.g. a button to click) are more tricky and there are a couple of ways we can go about it.

Since it's late at my timezone already;) so I'm going to clock out for today and push the code + try something more with these html's tomorrow.

[ladyleet]

@sulco you're kind of awesome! the guys are super busy as of late but i'm poking them about this because i need more input <3

[benlesh]

I think there's a tricky bit here where ideally the stackblitz is created from the example in the docs. :thinking:

Although I'm not really sure how to do that. What I don't want is for the example in the docs and the stackblitz to get out of sync. It would also be nice to have it in our code base so we can have versioning etc. There's a future where we're going to have to be able to have v7 docs and v6 docs, and the examples should live on for both.

Does anyone have any ideas for that?

[benlesh]

Alternatively, we can have the examples live in a different directory in the repository and create stackblitzes from those, maybe? And link them somehow to the docs comments?

I think there's just a bit more engineering to this to really get it right. Or maybe we can come up with a solid "quick and easy" solution... I'm not sure.

I just know that I'd like:

1. examples to be versioned along with the code
2. examples in docs and in stackblitz to come from the same source, so it doesn't get out of sync
3. It to be very obvious that the user can play with the code to try it out

[gabrielgeorge]

I think stackblitz got a function that you can run sample from github.
https://stackblitz.com/docs#open-and-embed-github-repos

Haven't tried it on my end, but my current concern is how do we separate the code. just the code, with the documentation.

If we can have the sample code separated (which at some point might be too hard to maintain code and the sample in two different files), I think it's possible to run it through the embed method.

[ladyleet]

@ericsimons @beeman y'all have any ideas here?

[beeman]

I think @sulco is on a great path here, making the integration similar to how it's done in Angular Material.

Also, I think that setup ticks all Ben's boxes. If not, we should look at how to create the examples in a standalone way and then include them in the docs.

While opening GitHub projects is awesome, it works for complete repos and not for partial repos. In this case we have a lot of examples in 1 repo.

@sulco feel free to reach out if you want me to look at how to cleanly get the templates in!

[ladyleet]

fab! :)

[sulco]

Progress report: I've looked some more into the examples to see how big of an issue is the templates thing, but so far it's actually not a problem.

I went through all the examples for _operators_ and updated them with necessary import statements so they actually work on their own.

I've also implemented a rudimentary StackBlitz SDK solution (with a button next to examples) so it does generate the working "blitz" from the code on the fly. It needs a bit polish (put it in an Angular service, add tests), but it works.

Don't want to promise anything regarding ETA, but so far so good and I do have some time this weekend ;)

You can track the progress on this branch: https://github.com/sulco/rxjs/commits/stackblitz-docs

[shobhitg]

There is one more thing I wanted to bring up.

in Stackblitz (and all other similar environments), whenever we change code, it reruns, but it doesn't clear the whole context. So the old subscriptions linger. To be able to reliably re-run the blitz, user have to press the hard refresh button.

Not a big concern, but this is definitely something that impacts RxJS examples more than anything else. Not sure what can be done about it.

[sulco]

@shobhitg thanks for pointing that out. It shouldn't be an issue though with StackBlitz' "page reload" option (which can be turned on with sdk as well)

[niklas-wortmann]

I'm really amazed by this enthusiasm. Thanks for all the hard work everyone puts into this. If one needs early feedback, feel free to contact me.

[sulco]

Thanks @JWO719! I've just created a PR. Let me know what you think.

[gkalpak]

It has been mentioned already, but I want to stress out how important it is to have a single source of truth for the examples.

#

_For context:_
For Angular and Angular Material, the examples are kept in separate files (which can be, for example, linted and type-checked) and then "embedded" into the docs at build time (as a dgeni transform).

Having the examples be separate like this allows them to be tested, which eliminates a several types of errors into sneaking into the example code. For example, Angular also has e2e tests for the examples (and could easily add unit tests if desired) in addition to linting and type-checking.

This approach, of course, requires a non-trivial engineering/tooling overhead. Another disadvantage for authors (and source-code readers) is you don't have the example code together with the docs content, since they are in separate files. (There are mitigations available - e.g. I have built this VSCode extention to help with that - but having the example code right into the docs is much easier for docs-authoring/source-code-reading.)

#

For RxJS, where the examples usually only consist of JS/TS code (no HTML or CSS or node scripts) and are short/less complex, having the examples embedded in the docs - and creating the StackBlitz examples from that as in @sulco's PR - might be an acceptable compromise.

In any case, there should always be one source of truth; either code-blocks in the docs content (as in RxJS currently) or separate source-code files (as in Angular and Angular Material).

#

_{If anyone wants to know more on how our tooling works, feel free to reach out to @petebacondarwin or me.}

(Yes, @petebacondarwin, I just "volunteered" you to answer dgeni questions. You are welcome :grin:)

[petebacondarwin]

Also it may be interesting to note that the AngularJS (not Angular) docs use the embedded source of truth approach.

[cmckni3]

Personally, I prefer codesandbox now because of the template feature, embedding, and GitHub integration. I also find that I have less issues in codesandbox overall compared to stackblitz

[EricSimons]

Yay! Amazing work on https://github.com/ReactiveX/rxjs/pull/4479 @sulco!! So excited to see this PR land 😄

@cmckni3 fyi the issue you linked is on npm's end, not ours- feel free to DM me for help any time though! As for features, StackBlitz API & SDK provides all the above + more (see @sulco's PR, Angular.io, Angular Material, etc). Worth checking out!

[railsstudent]

@ladyleet
exhaustMap - https://stackblitz.com/edit/rxjs-2tbdsz

[ladyleet]

@railsstudent thank you! @sulco good to close?

[sulco]

@ladyleet looks like it. The StackBlitz examples in docs are live and kicking :)