Welcome to Maleo.js

Maleo.js is an un-opinionated framework to enable Universal Rendering in JavaScript using React with no hassle.

We are here to solve the time consuming setups Universal Rendering Required.

Readme below is the documentation for the canary (prerelease) branch. To view the documentation for the latest stable Maleo.js version change branch to master

Features
Setup
Component Lifecycle
Routing
Dynamic Import Component
- Tips
- Preloading
Customizable Component
- Custom Document
- Custom Wrap
Custom Configuration
Core Utilities Functions
CDN Support
Plugins
FAQ
Contributing

Features

Universal Rendering
Plugin based framework
Customizable

Setup

Install Maleo.js

for now change @airy/maleo to @airy/maleo@canary until we publish the stable version of this package

NPM

$ npm install --save @airy/maleo react

Yarn

$ yarn add @airy/maleo react

Add this script to your package.json

{
  "scripts": {
    "dev": "maleo dev",
    "build": "export NODE_ENV=production && maleo build",
    "start": "export NODE_ENV=production && maleo run"
  }
}

Create a page Root component

// ./src/Root.jsx
import React from 'react';

// Export default is required for registering page
export default class RootComponent extends React.Component {
  render() {
    return (
      <h1>Hello World!</h1>
    )
  }
}

And lastly, create a routing file on your project root directory called routes.json and register your page component

[
  {
    "path": "/",
    "page": "./src/Root"
  }
]

After that you can now run $ npm run dev and go to http://localhost:3000.

You should now see your app running on your browser.

By now you should see

Automatic transpilation and bundling (with webpack and babel)
~~Hot code reloading~~ #17
Server rendering

To see how simple this is, check out the sample app!

Component Lifecycle

Maleo.js added a new component lifecycle hook called getInitialProps, this function is called during Server Side Rendering (SSR) and during route changes on Client Side Rendering (CSR).

This is useful especially for SEO purposes.

Example for stateful component:

import React from 'react';

export default class extends React.Component {
  static getInitialProps = async (ctx) => {
    const { req } = ctx;

    // check if getInitialProps is called on server or on client
    const userAgent = req ? req.headers['user-agent'] : navigator.userAgent;

    // the return value will be passed as props for this component
    return { userAgent };
  }

  render() {
    return (
      <div>
        Hello World {this.props.userAgent}
      </div>
    );
  }
}

Example for stateless component:

const Component = (props) => (
  <div>
    Hello World {props.userAgent}
  </div>
);

Component.getInitialprops = async (ctx) => {
  const { req } = ctx;

  const userAgent = req ? req.headers['user-agent'] : navigator.userAgent;

  return { userAgent };
};

export default Component;

getInitialProps receives a context object with the following properties:

req - HTTP request object (server only)
res - HTTP response object (server only)
...wrapProps - Spreaded properties from custom Wrap
...appProps - Spreaded properties from custom App
matched - Matched routes contains list of object, which is consists of match object and route object
route - Component's route attributes on routes.json file

Routing

Routing is declared in a centralized route config. Register all the route config in routes.json file.

If you put the routes.json files on root directory, Maleo will automatically register your route. Otherwise put path to your routes on Maleo config.

Routes file has to export default the route configuration. The route object expected to have distinct key to indicate the route.

<table> <tr> <td>Key</td> <td>Type</td> <td>Description</td> </tr> <tr> <td><code>path</code></td> <td><code>String!</code></td> <td>Routes path</td> </tr> <tr> <td><code>page</code></td> <td><code>String!</code></td> <td>Path to React Component for this route path</td> </tr> <tr> <td><code>exact</code></td> <td><code>Boolean?</code> [<code>false</code>]</td> <td>To make url has to match exactly the path in order to render the component. Give <code>false</code> value if the route is a wrapper route component</td> </tr> <tr> <td><code>routes</code></td> <td><code>RouteObject?</code></td> <td>Nested route</td> </tr> </table>

For example:

[
  {
    "page": "./src/MainApp",
    "routes": [
      {
        "path": "/",
        "page": "./src/Search",
        "exact": true
      },
      {
        "path": "/search",
        "page": "./src/Search",
        "routes": [
          {
            "path": "/search/hello",
            "page": "./src/Detail",
            "exact": true
          }
        ]
      },
      {
        "path": "/detail",
        "page": "./src/Detail",
        "exact": true
      }
    ]
  }
]

Dynamic Import Component

Maleo.js supports TC39 dynamic import proposal for JavaScript.

You can think dynamic import as another way to split your code into manageable chunks. You can use our Dynamic function which utilizes react loadable

For Example

// DynamicComponent.js
import Dynamic from '@airy/maleo/dynamic';

export default Dynamic({
  loader: () => import( /* webpackChunkName:"DynamicComponent" */ './component/DynamicLoad'),
})

Preloading

For optimization purposes, you can also preload a component even before the component got rendered.

For example, if you want to load component when a button get pressed, you can start preloading the component when the user hovers the mouse over the button.

The component created by Dynamic exposes a static preload method.

import React from 'react';
import Dynamic from '@airy/maleo/dynamic';

const DynamicBar = Dynamic({
  loader: () => import('./Bar'),
  loading: LoadingCompoinent
});

class MyComponent extends React.Component {
  state = { showBar: false };

  onClick = () => {
    this.setState({ showBar: true });
  };

  onMouseOver = () => DynamicBar.preload();

  render() {
    return (
      <div>
        <button
          onClick={this.onClick}
          onMouseOver={this.onMouseOver}>
          Show Bar
        </button>
        { this.state.showBar && <DynamicBar /> }
      </div>
    )
  }
}

Customizable Component

Custom Document

Highly inspired by what Next.js has done on their awesome template customization.

Maleo.js also enable customization on Document as document's markup. So you don't need to include tags like <html>, <head>, <body>, etc.

To override the default behavior, you'll need to create a component that extends the Document React class provided by Maleo.

// document.jsx
import React from 'react';
import { Document, Header, Main, Scripts } from '@airy/maleo/document';

export default class extends Document {
  render() {
    return (
      <html>
        <Header>
          <title>Maleo JS</title>
          <meta charset="utf-8" />
          <meta name="description" content="Maleo.js is awesome!" />

          <style>
            {` body { background-color: #fff } `}
          </style>
        </Header>

        <body>
          <Main />

          <Scripts />

          <ReduxScript />
        </body>
      </html>
    );
  }
}

Custom Wrap

Maleo.js uses the Wrap component to initialize pages. Wrap contains React Router's Component. You can add HoC here to wrap the application and control the page initialization. Which allows you to do amazing things like:

Persisting layour between page changes
Keeping state when navigating pages
Custom error handling using componentDidCatch
Inject additional data into pages (like Redux provider, etc)

To override the default behavior, you'll need to create a component that extends the Wrap React class provided by Maleo.

// wrap.jsx
import React from 'react';
import { Wrap } from '@airy/maleo/wrap';

// Redux plugin for Maleo.js
// Hoc that creates store and add Redux Provider
import { withRedux } from '@airy/maleo-redux-plugin';

// Custom Wrapper that will be rendered for the whole Applic

Maleo.js

Install / Use

README