React

In this section, we will quickly describe how to start using LiveUI with a React Web application.

If you are interested in React Native you can skip to the react native section.

Prerequisites

• node >= 8
  
• npm >= 5
  

Creating an App with Remotable Components

First, we need to install liveui wizard to create a new LiveUI app. To install the new package, use one of the following commands. You need administrator privileges to execute these unless npm was installed on your system through a Node.js version manager (e.g. n or nvm).

npm install @eclipse-muto/liveui -g

After installation, you will have access to the liveui binary in your command line. You can verify that it is properly installed by simply running liveui, which should present you with a help message listing all available commands.

npx @eclipse-muto/liveui can be run for the same purpose.

To create a new LiveUI app with remotable components, you may choose one of the following methods:

liveui

or

liveui create

This prompt runs the LiveUI project wizard and will ask a project type and a project name. For this example, choose the project type as react and follow the wizard instructions. The wizard will generate your project and start to install the required packages. When it's done you can start to develop your first LiveUI project. This project will contain a component that can be consumed by other web apps.

Once the installation is done, you can open your project folder:

cd <project-name>

The initial project structure:

your-liveui-app
│
├── README.md
├── internals
│   └── index.js
├── package-lock.json
├── package.json
├── public
│   └── index.html
└── src
    └── index.js

No configuration or complicated folder structures are created, only the files you need to build your app are added.

Inside the newly created project, you can now run the following commands:

npm start

Runs the app in development mode and serve the initial remote component.

When you start the application open http://localhost:5000 to test your new app in the browser. You will see just a basic component that displays 'This is the Foo component..'. This application is no different from a traditional React application. However, LiveUI has added a remote configuration for component that is running on http://localhost:5001 and it is ready to be used in other React applications for development or deployment. Edit src/index.js to change the initial remote component and see the browser to view your changes.

npm run build

Builds the remote component(s) for production to the docker folder. It correctly bundles the remote component in production mode and optimizes the build for the best performance.

Note: This command is only responsible for building the remote component(s) not the whole application.

Your remote component is ready to be deployed.

At this point you can run npm run docker to generate a docker image.

In the next steps, you will learn more about how to use remote components.

Using Remote Components

In the previous sections we demonstrated how to create and run a basic LiveUI project that contains a remote component. In this section we will demonstrate how to consume these remote component(s).

First we need an application (called host) to make use of our remote components. For the simplicity we will use create-react-app to create a React project.

npx create-react-app my-app
cd my-app

After creating the project we should use some npm packages to use remote components.

npm install @eclipse-muto/liveui-core @eclipse-muto/liveui-react

These packages are responsible for initializing LiveUI in the host app and consuming components that are running locally or remotely.

Next, we will create a file that is used to configure the host.

Create a liveui.config.js under the src folder with the following command:

liveui init

The newly created config file will have a content similar to the following:

src/liveui.config.js

module.exports = {
    // ...
    // other configuration options
    shares: {
        react: require('react'),
        'react-dom': require('react-dom'),
    },
    remotes: {
        foo: 'http://localhost:5001/foo',
    }
}

We created the config file under the src folder because of Create React App does not support relative imports outside of src/. If you use something else like react-boilerplate it's recommended that create the config file under the root folder.

In the above config, we define the shares configuration option to tell what libraries, packages, components, or static files will be commonly used between the host application and remotes. This will optimize the bundles that are used in runtime by avoiding duplications of libraries in the host and remote packages.

The remotes option is where we specify the name and URL of our component. If you remember, in the previous section when we start the application the remote component was running on http://localhost:5001/foo.

Open index.js under the src folder and edit to initialize the the host app with the LiveUI config:

src/index.js

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import * as serviceWorker from './serviceWorker';
+ import liveuiConfig from './liveui.config';
+ import liveui from '@eclipse-muto/liveui-core';

+ liveui.initializeApp(liveuiConfig);


ReactDOM.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
  document.getElementById('root')
);

// If you want your app to work offline and load faster, you can change
// unregister() to register() below. Note this comes with some pitfalls.
// Learn more about service workers: https://bit.ly/CRA-PWA
serviceWorker.unregister();

Open App.js under the src folder and edit it as follows:

src/App.js

import React from 'react';
import logo from './logo.svg';
import './App.css';
+ import RemoteComponent from '@eclipse-muto/liveui-react';

+ const Foo = props =>  <RemoteComponent name="foo" {...props} />

function App() {
  return (
    <div className="App">
      <header className="App-header">
        
        <img src={logo} className="App-logo" alt="logo" />
        <p>
          Edit <code>src/App.js</code> and save to reload.
        </p>
        <a
          className="App-link"
          href="https://reactjs.org"
          target="_blank"
          rel="noopener noreferrer"
        >
          Learn React
        </a>
      </header>
+      <Foo />
    </div>
  );
}

export default App;

We define our remote component as follows:

const Foo = props =>  <RemoteComponent name="foo" {...props} />

The 'name' prop is should be the same in the config we defined.

Save changes and start the application. At the same time you should start the LiveUI app created in the previous section to see our first remote component.

That's it! You created your first LiveUI Web App. But there’s more! You can use different styles to organize your codebase, customizing the liveui.config allows you to use working with different codebases, deployment of multiple components, etc. Read to learn more about LiveUI and explore the documentation!