Skip to content

SJCProduction/Helium.js

Repository files navigation

alt text

Making your React application lighter! 🎈

npm dependencies NSP Status Codacy Badge GitHub stars License: MIT contributions welcome

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.

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

Table of Contents

Installation

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

Local Installation

$ npm install --save helium.js

Global Installation

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

$ npm install -g --save helium.js

Usage

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' 
);

(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' 
);

Rendering on Server Side

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

Image of CLI

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);

(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);

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",
},

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'],
        }
      },
    },
  },
}
  1. 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"
  1. Follow the two steps above.

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%
    } 
  }

Contributing

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

Versioning

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

Authors

License

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