Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
137 lines (82 sloc) 6.16 KB

Getting Started

@bitovi/velocirender provides a web-server for Single-page apps that is optimized for speed. By striking a balance between traditional server-side rendering and client-only rendering we are able to get the best of both worlds. A partially rendered page is delivered to the browser immediately; allowing critical assets such as CSS and JavaScript to begin being fetched. Meanwhile rendering instructions are streamed from the server to the browser allowing the user to see page content before the application has fully booted up.

Installing

Velocirender requires Node.js 10.0 and above.

To install Velocirender use one of the following commands:

npm install -g @bitovi/velocirender

or

yarn global add @bitovi/velocirender

This will add a new utility, velocirender to your PATH. You can check the version you have installed by running:

velocirender --version

Try it out

You can play around with and see the effects of incremental rendering without writing any code. Our example apps were written for the most popular frameworks and you can connect to them remotely.

velocirender https://bitovi.github.io/dog-things-react

Then navigate to http://localhost:8080 in your browser. You won't notice a big difference from a high-speed connection so we recommend tuning down to a 3G connection.

In Chrome Developer Tools you can do this by clicking Network and then changing the dropdown that says Online to Slow 3G instead:

Turning network down to 3G connection

Now when you compare the page load time using Velocirender vs. the client-only page you should see quite a difference of:

  • The App Shell is displayed immediately (the header, sidebar, etc).
  • Items within the product list are streamed in more quickly. This is because the API request is first made on the server.

Example apps

To make it easier getting started with Velocirender we've created React, Vue, and Angular example apps. These apps are built using the standard tooling for each framework.

React

The dog-things-react project was created using Create React App.

You can try out incremental rendering this project locally using:

velocirender https://bitovi.github.io/dog-things-react

Or clone and then run:

npm install
npm start

This will open the app in development mode. You can modify the files and it will reload the browser. To build you do:

npm run build
npm run prod

This will serve up the production build from the build/ folder.

Vue

The dog-things-vue project was created using Vue CLI.

You can try out incremental rendering this project locally using:

velocirender https://bitovi.github.io/dog-things-vue

To develop on the app you can clone it and then run:

npm run serve

Which builds the app in development mode and starts a server. To see the incremental version build for production run:

npm run build
npm run prod

The built version will be in the dist/ folder.

Browser Compatibility

Velocirender utilizes recent additions to the browser specs such as preload, fetch, and ReadableStream.

As of today incremental rendering is possible in Chrome and Safari >=12.

In browsers that don't support these technology Velocirender will fallback to the traditional SSR method of waiting for a fully rendered page. We call these separate strategies:

  • incremental strategy is for modern browsers with streaming capabilities.
  • legacy strategy is for older browsers.

Deployment

You can deploy your application to any of the many cloud Node.js hosting providers such as Google Cloud, AWS EC2 or Heroku.

Function as a service providers (sometimes called serverless) like AWS Lambda is not a viable option at this time, because none of these providers currently support streaming responses. Once they've added that capability we'll explore how Velocirender can be integrated into those platforms.

Remote vs Local

Currently it is recommended to deploy the application in the same manner you would any server-side app. How you do this will depend on your provider, but ultimately you'll want have it run the CLI command:

node_modules/.bin/velocirender path/to/index.html

Where path/to/index.html is the path to your production HTML file (React's is build/index.html for example).

Every time you want to do a new release of your application you will need to redeploy the code and restart the server.

In the future it will be possible to run Velocirender against remote URLs in your production environment. What this will do is download your application from a remote URL and cache the assets locally. This won't be practical, however, until we figure out a way to expire the cache.

What this will mean is that you will only ever need to deploy your back-end code once. From then on you can simply deploy the client-side application to some publicly accessible CDN and the server will download the new version when its cache expires.

Next Steps

We invite you to join the Bitovi Community Slack and come to the #performance room to get help from the community on setting up incremental rendering in your application.