Redoc: Initial prerendering

[RomanHotsiy]

For big specs initial page rendering takes too much time.
Using Angular2 Universal prerendering should fix this issue.

This feature should be optional and should work via CLI e.g.:

$ redoc prerender index.html

[bfirsh]

Have you made progress on this at all?

This is a big blocker to use using ReDoc for the Docker API documentation. I've had a play around with Universal, but it looks like the app is a long way off working with it.

Do you think it might be possible/easier to use something like prerender in the interim?

[bfirsh]

I've given it a shot with Prerender, and it actually sort of works. The page renders okay, but nothing is functional. Eventually the client-side ReDoc kicks in and things become functional.

The main problems are:

• The site is non-functional until ReDoc loads, obviously. This is a good few seconds for a large Swagger definition.
• The page jumps up to the top once ReDoc has loaded.

This doesn't really help with load times, because the documentation isn't really functional until the client-side ReDoc has loaded. Presumably with the Angular Universal prerendering, it'll use the existing DOM, so it actually speeds up the load time?

[adamaltman]

Hi @bfirsh , this is an interesting problem that affects us too. @RomanGotsiy is away on vacation right now. He'll be back towards the end of next week.

[bfirsh]

@RomanGotsiy Any thoughts on how this could be done? I'm eager to help implement this, but I don't want to waste my time if existing thought has been up into it.

[RomanHotsiy]

Hey @bfirsh,
I played with Universal a long time ago. At that time Angular was still in beta and Universal project was just started so there were lots of issues with this. I decided to postpone it till the official Angular 2.0 release.
I'm just back from vacation and I will take a look at the situation with Universal today/tomorrow.

Presumably with the Angular Universal prerendering, it'll use the existing DOM, so it actually speeds up the load time?

AFAIK Universal prerendering will use the existing DOM so the page won't jump to the top. It will be still non-functional until ReDoc loads but after it loads all events (mouse clicks, key presses) will be replayed. + I believe Angular developers have introduced a Universal pattern which should help to improve UX until ReDoc is loaded.

Summing up: let me look into this as well so as to refresh my knowledge. I will post my thoughts here.

[bfirsh]

@RomanGotsiy Have you had a chance to look at this? Any thoughts?

[RomanHotsiy]

@bfirsh, I had a quick look but unfortunately still haven't had time to dive into this.
This is on my priority to-do list. I will post my thoughts once I get to this.

[RomanHotsiy]

@bfirsh finally I've managed to get to this.
First, Angular Universal and server-side rendering seems to be not ready now + it requires a lot of refactoring. So I don't think I will proceed with this.
Actually ReDoc doesn't need server-side rendering, it needs prerendering which may be done just using any headless browser. I have checked Universal code and it seems to be possible to just attach client-side universal features (events replay) to the prerendered that way page.

I did some quick tests with this approach. The results are following:

• page is rendered immediately
• then everything hangs for some time (but shorter than initial loading without prerendered page)
• then we have working ReDoc

So resulting performance improvement was not so big and I didn't like it.

Right now I'm working on alternative approach: lazy rendering.
How it works:

• skeleton of redoc is rendered immediately (tags and methods placeholders, side menu)
• after that methods are rendered with small intervals to let browser process UI
• menu items are disabled until corresponding method is loaded
• if user came using link to the concrete method/section this method is rendered first and the rest from above and bellow are rendered afterwards
  The tricky part here is maintaining scroll position if elements above are inserted. I have it already working in Chrome and FF but have issues in Safari and IE/Edge.

I will probably implement some fallback for IE/Edge and Safari for now (e.g. they will load just as before) and will release it till the end of week.

[bfirsh]

Nice. That sounds great. :+1:

[RomanHotsiy]

@bfirsh I have released to CDN beta version of ReDoc with the mentioned above performance optimisations

Could you test it and provide your feedback?
Use the following link to reference redoc.min.js: http://rebilly.github.io/ReDoc/releases/v1.6.0-beta.perf/redoc.min.js

This version is only on CDN, it is not available via npm

[bfirsh]

Nice - works a treat. :)

https://bfirsh.github.io/docker-api-reference/

[RomanHotsiy]

I'm Happy you liked 😀. So you will proceed with it, right?

I will keep this as beta a few more days and then will release new version.

[bfirsh]

We will indeed proceed! Thanks so much for this. :)

[RomanHotsiy]

Just released a new version v1.6.0. It has lazy rendering feature.
To enable it use lazy-rendering ReDoc option:

<redoc spec-url="..." lazy-rendering></redoc>

[RomanHotsiy]

Implemented in by redoc-cli