Helium.js

<p style="text-align:center">Making your React application lighter! 🎈</p>

What is Helium.js?

Helium.js is a node package that helps make your React application isomorphic and optimized.

Leveraging server-side rendering can significantly improve first page load performance: render JavaScript templates on the server to deliver fast first render, and then use client-side templating once the page is loaded. However, performance benefits depend on the use case and server-side rendering is not a one size fits all design.

• <b>Currently</b>:
  • Includes server side rendering with support for React Router v4 and Redux v3 using React Fiber - v16
  • Perfomance metrics CLI
• <b>Coming Soon:</b> Optimization for webpack bundles

Table of Contents

• Authors

• Installation

  • Prerequisites
  • Locally
  • Globally

• Usage

  • Client Side
    • with Redux
  • Server Side
    • CLI
    • DIY
      • with Redux

• Running Your Application

• Getting Production Ready

• Performance Testing

• More

<a name="installation"></a>Installation

<a name="pre-req"></a>Prerequisites

You will need to have react 16/react-dom, the babel-cli, and two babel presets: env and react installed as dependencies.

$ npm install --save react react-dom babel-cli babel-preset-env babel-preset-react

<a name="local-installation"></a>Local Installation

$ npm install --save helium.js

<a name="global-installation"></a>Global Installation

You can additionally install globally for direct usage of CLI commands in your terminal.

$ npm install -g --save helium.js

Usage

<a name="usage-on-client-side"></a>Hydrating on Client Side

/* Replace render with helium method
inside the index file of React application */

import helium from 'helium.js/react';

helium(
  <BrowserRouter>
    <App/>
  </BrowserRouter>, 
  'root' 
);

<a name="usage-on-cl-with-redux"></a>(with Redux)

/* Replace render with helium method
inside the index file of React application */

import helium, { getStore } from 'helium.js/react';

// import your reducer

helium(
  <Provider store={ getStore(reducer) }>
    <BrowserRouter>
      <App/>
    </BrowserRouter>
  </Provider>,
  'root' 
);

(with Redux and Middlewares)

/* Replace render with helium method
inside the index file of React application.
Declare your middlewares as usual and pass 
in as a second parameter to getStore invocation */

import helium, { getStore } from 'helium.js/react';

// import your reducer
// declare your middlewares

helium(
  <Provider store={ getStore(reducer, middleware) }>
    <BrowserRouter>
      <App/>
    </BrowserRouter>
  </Provider>, 
  'root' 
);

<hr>

<a name="usage-on-server-side"></a>Rendering on Server Side

<a name="cli"></a>Option 1: Automation with CLI

Have your server file automatically generated by answering questions using our CLI.

To start up the CLI, do one of the following:

1. Type this command directly into your terminal

$ ./node_modules/.bin/he

2. Add a script to your package.json and run the script

"scripts": {
  "helium": "he",
},

$ npm run helium

3. Install globally and run the command

$ he

<a name="diy"></a>Option 2: Do it Yourself

/* Include this in your server file 
(the file in which you initialize your 
express application) */

// import your root component
import App from './src/components/App.js';
const helium = require('helium.js');

// initialize your express application here

helium.init({
  // indicate the path to your main html file
  html: 'index.html',
  // specify the id to which your React application will be mounted on
  id: 'root',
  App,
});

// input api routes here

app.get('*', helium.serve);

<a name="usage-on-s-with-redux"></a>(with Redux)

/* Include this in your server file 
(the file in which you initialize your 
express application) */

// import your root component and your reducer
import App from './src/components/App.js';
import reducer from './src/reducers';
const helium = require('helium.js');

// initialize your express application here

helium.init({
  // indicate the path to your main html file
  html: 'index.html',
  // specify the id to which your React application will be mounted on
  id: 'root',
  App,
  reducer,
});

// input API routes here

app.get('*', helium.serveRedux);

<a name="running"></a>Running Your Application

If CLI was not used, add a script to your package.json to run your serverfile using babel-node.

"scripts": {
    "helium:start": "nodemon [server file name].js --exec babel-node --presets es2015",
},

<a name="production"></a>Getting Production Ready

With the CLI:

The CLI would have automatically added threee scripts including helium:start, helium:build, helium:serve.

1. Run helium:build to bundle your dynamically generated server file.
2. Run helium:serve to serve your production ready file.

Without the CLI:

1. Add an additional configuration to your webpack file to target the server file

{
  entry: path.join(__dirname, '[server file name].js'),
  target: 'node',
  output: {
    path: path.resolve(__dirname),
    filename: '[bundled server file name].js',
    libraryTarget: 'commonjs2',
  },
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        loader: 'babel-loader',
        exclude: /node_modules/,
        query: {
          presets: ['env', 'react'],
        }
      },
    },
  },
}

2. Add the following scripts to your package.json.

"helium:build": "webpack --config ./prod/helium.webpack.conf.js",
"helium:serve": "node ./prod/[server file name].prod.js"

3. Follow the two steps above.

<a name="testing"></a>Performance Testing

You can also perform simple Critical Rendering Path testing after setting up server-side render with helium using the following:

1. Start your client-side application as usual

$ npm run start

2. Run lift -csr in a seperate terminal window and walk through the CLI interface

$ lift -csr

3. After evaluating your application, you will receive results for the client-side rendering instance in your terminal

$  "csr": {
    "webapi": {
      "DOMLoading": 34,
      "DOMContentLoaded": 75,
      "DOMComplete": 125
    }
  }

4. Repeat steps 1-3 running your server-side application instead

$ npm run helium:start

$ lift -ssr

$ "ssr": {
   "webapi": {
      "DOMLoading": 10,
      "DOMContentLoaded": 56,
      "DOMComplete": 112
    }
  }

5. After receiving results for both instances, run lift -diff.

$ lift -diff

# To run your application, type the following into your terminal
$ "diff": {
   "webapi": {
      "DOMLoading": 70.5882%,
      "DOMContentLoaded": 25.3333%,
      "DOMComplete": 6.25%
    } 
  }

<a name="contributing"></a>Contributing

If you would like to contribute, submit a pull request and update the README.md with details of changes.

<a name="versioning"></a>Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

<a name="authors"></a>Authors

• Shachy Rivas
• Chris Li
• Julie Moon

<a name="license"></a>License

This project is licensed under the MIT License - see the LICENSE file for details