Creating a new React application

Prerequisites

React app template uses git for version control, so make sure it is installed on your system. Also package scripts are using yarn, so you’ll need it too.

To install yarn run npm i -g yarn.

Bootstrapping

Now lets try creating our first application. Open your terminal and run this command:

omg app create my-first-app

In this tutorial we will use a React app template. It is possible to develop applications using other technologies or just in plain js+html, but for simplicity we will focus on React in this tutorial.

Select ‘React app’ template when asked.

The omg utility will now download the template and bootstrap the app.

Lets run the app now:

yarn start

The app should start in a new browser window.

The app can be debugged in a regular way, press Cmd+Option+J to display the debugger

Code structure

The React template app structure is very basic

/src - the folder containing application source code.

/build - the folder when the app gets built

/public - static files that will be bundled with the app

Main app component resides in /src/App.tsx. Lets have a look at it

import React from 'react';
import { useSettings } from '@ombori/ga-settings';
import logo from './logo.svg';
import './App.css';

import { Schema as Settings } from './schema';

function App() {
  const settings = useSettings<Settings>();

  const productName = settings?.productName;
  const productPrice = settings?.productPrice;

  if (!settings) {
    return <div className="App">Loading gridapp settings...</div>
  }

  return (
    <div className="App">
      <header className="App-header">
        <img src={logo} className="App-logo" alt="logo" />
        <p>Product name: {productName}</p>
        <p>Product price: {productPrice}</p>
      </header>
    </div>
  );
}

export default App;

Settings

When started, every application receives a settings object, that contains values that can be changed without rebuilding the app. During the local development settings are stored in /src/settings/index.json file.

Settings can be used from react components using useSettings() hook imported from @ombori/ga-settings package.

Because settings are loaded dynamically, useSettings may return falsy value when loading is not yet complete.

Settings schema

When app is used in grid console, its settings may be changed without rebuilding the app. The settings are displayed in a form, which is autogenerated from a schema file, supplied with the app. React App template uses schema in TypeScript format, which is stored in src/schema.ts. This file exports a single type, Schema that is used as a result type for useSettings call.

Lets have a look at it:

/**
 * @title Example schema
 */
export type Schema = {
  /**
   * @title Product name
   * @default "My Example Product"
   */
  productName: string;

  /**
   * @title Product price
   * @default "99 USD"
   */
  productPrice: string;
}

As you may see, the file exports one type, an object with two properties: productName and productPrice, both stings. Along to every field, in a doxygen-style comment additional metadata is specified for every object property.

@title - specifies a human-readable title for the form field

@default - specifies a default value for the field. Note that the value is a TypeScript constant, and since both properties are strings, the value is put in double quotes.

Publishing the app

Now, lets try publishing our app and see how we can deploy it to a real device.

First, we need to build the app:

yarn build

The app is build in a so-called “gridapp bundle” - basically an archive with the all the files that will be deployed with the app.

omg app publish

This command will upload the pre-built version of the app to the Grid Console, making it available for use on your devices. Make sure you have an app created in your organisation before running the publish command.