What is ribbitJS?

Ribbit aims to be a sensible, extensible, CLI tool for server-side rendering. All it takes is a bit of configuration to generate contentful markup (and internal CSS!) for your SPA. Serve your routes using the generated routes manifest file, and your users will never suffer a blank page again!

Universal rendering, deconstructed

Universal rendering for SPAs can be split up into 6 phases*:

1. Routing: Mapping the routes in the SPA.

2. Serializing: Exporting state/data required for render from the client side

3. Execution: Converting the bundled JavaScript file to markup.

4. Render:
   Constructing a template literal of an HTML file with injected stringified app bundle, scripts, and interpolating any additional template data. Then writing the HTML template literal strings to file aka the HTML static assets.

5. Response

In the case of ribbit, the response is generating a JSON manifest file that maps routes to the static assets created in the rendering phase.

6. Deserializing & Attaching

Ensuring that when the SPA adds event handlers to the page, its data/store get hydrated with the data/state sent with the server response.

*Credit to Jason Strimpel for defining these phases in his book, Building Isomorphic JavaScript Apps

Using ribbit

1. ribbit init

After installation (npm install ribbit), run npx ribbit init from within your app folder. This will launch a series of simple prompts, after which two configuration will be generated (ribbit.config.js and ribbit.routes.json), both of which will need to be filled in.

2. ribbit.config.js

Parts of ribbit.config.js will be filled in by the answers given to the prompts in ribbit init. The fields in the config are as follows:

‘appRoot’ The app root is the folder the topmost component is located in. For example, with the following folder structure:

src/
    components/
	    App.js

appRoot would be 'src/components'.

With the following folder structure:

src/
    App.js

appRoot would be 'src'.

‘app’ App refers to the name of the file containing highest component in the application. This is the highest component in your SPA that imports all other components. Do note, this is NOT the JS file that injects your application into the DOM. In the example above, app would be 'App.js'.

‘bundleRoot’ bundleRoot refers to the folder the JS bundle file is contained in. With the following folder structure:

dist/
    bundle.js

bundleRoot would be 'dist'.

‘bundle’ Refers to the actual bundled JS filename. In the example above, bundle would be 'bundle.js.

‘bundler’ Refers to the bundler used: only webpack is currently supported, but gulp/browserify support is planned for the near future.

‘presets’ Refers the frontend framework being used. Currently only React is officially supported, although Vue and Angular support is planned for the near future.

‘rules’ Allows the user to choose whether they want to enable internal/external CSS [coming soon].

‘dependencies’ Place each bundling dependency (loaders, plugins, etc.) as a string in the dependencies array. Please ensure that all of these dependencies have already been installed in your main application.

‘webpackSettings’ This setting will hold all the necessary webpack settings aside from entry and output - mainly the modules section - to bundle your application.

‘plugins’ [coming soon]

3. ribbit.routes.json

Ribbit.routes.json will be generated in the directory listed in appRoot. This file will be a single array of objects (one object for each route in the SPA), all of which will need to be filled in by the user.

Take for example:

[
	{
		"route": "/",
		"assetName": "index",
		"component": "./one.js"
	},
	{
		"route": "/about",
		"assetName": "about",
		"component": "./about.js"
	}
]

The route field in each object refers to the actual route in the SPA. assetName is simply the name for the static file that will be generated by ribbit for that route. component is the path to the actual component that takes care of that route in the SPA.

4. ribbit build

Running ribbit build (or ribbit b) within your app folder will generate pre-loaded HTML files for each component of your webapp in the “ribbit.statics” folder.

5. Serve your files

In the ribbit.statics folder, ribbit will have generated a ribbit.manifest.json file listing the HTML file for each route in the SPA. This file can be used to set up your server accordingly.

6. Features to come

• Additional presets for Vue and Angular
• Documentation

Credit: Brian Hon, Malika Butler, Marlon Wiprud, Raphael Ram