Lazy Programmer's Guide to SAS Viya Application Development Part II: create-react-restaf-viya-app

[#1]

The create-react-app tool is a very popular CLI to jump start the development of react-based applications. I created the create-react-restaf-viya-app as an extension of create-react-app. The main motivation for my new tool is to help restaf users build react-based Viya applications. restaf  is a  framework for building applications with SAS REST APIs, supported with SAS Viya and is composed of the following components: 

• restaf

• restaflib

• restaf-server

Benefits

The key benefits of using the create-react-restaf-viya-app CLI to jump start your SAS Viya Applications are:

1. You retain all the benefits of using create-react-app, which are well documented.

2. You are automatically authenticated to the Viya Server.

3. You can start making API calls right away during development just as you would in production.

Note that this cli does not restrict you to using restaf - you are free to use your favorite library to access SAS Viya REST APIs.

A note on making API calls

The recommended way to make the REST API calls is using restaf and restaflib. If for some reason (the author can think of few-to-none) you prefer to hand-code the REST API calls you can do that too. Remember that the session is authenticated using authorization_code flow and you'll need to code your calls accordingly.

Creating your React application

Issue the command below to create the default application.

npx create-react-restaf-viya-app react-appname --webapp webapp-name  --title webapp-title --script scriptTags-file

Example:
npx create-react-restaf-viya-app mycoolapp

Only the react-appname is required. The optional parameters are:

• webapp – this is the user-friendly application name; defaults to viyademo

• title – the text for the title tag in index.html; defaults to SAS/Viya Application

• script – a file which has some HTML script tags to be inserted into index.html; default is a comment line file

• i    –   specify additional modules to install (ex: --i  "@material-ui/core prettyjson")

Using the generated application

Once the app is created, you can start your development.

Key assumption

The application authenticates using authorization_code flow.

Configuration

Set the following in the .env file:

• CLIENTID – the default value is viyademo
• CLIENTSECRET – the default value is secret
• VIYA_SERVER – no defaults.You must specify this (e.g., http://myviya.com)

Some defaults

1. The app server runs on localhost:5000/viyademo
2. The clientid redirect is http://localhost:5000/viyademo
3. The create-react-app server runs on its standard port(3000)

For more detailed configuration options, see https://github.com/sassoftware/restaf-server/wiki

Application development

1. Modify App.js to suit your needs.
2. Install any additional packages your app might need.

Running in development mode

Run this command to have HMR enabled.

cd to-the-app-directory
yarn dev

The flow of the application on the yarn dev command is show below.

• Step 1 : The user invokes the application at http://localhost:5000/viyademo.

• Step 2: The restaf-server authenticates with the Viya Server. The user is prompted for credentials.

• Step 3a: The status of the initialization is displayed in the browser.

• Step 3b: restaf-server runs the create-react-app’s npm start script, which launches your react application in a second tab of your browser.

At this point you can view your application, edit your code and see the updated application. The session is authenticated -so you can make REST API calls to SAS Viya using restaf or any other library. Refer to the flow below for more details.

Running in Application mode

Run the commands shown below. Note the create-react-app dev server will not start in this mode.

cd to-the-app-directory
yarn build
yarn app

React Context - AppContext

By default a react context named AppContext is created. To access the data code something like this:

import React,{useContext} from 'react';
import {AppContext} from '../providers';

let appContext = useContext(AppContext);

let {store, appOptions} = appContext;

let {appenv, logonPayload} = appOptions;

The store is the restaf store object you use to make the API calls. The logonPayload has the following form:

{
    authType: 'server'
    host    : "your Viya hostname"
}

The host value is useful if you are making use of Visual Analytics SDK and/or if you are coding the REST API calls without restaf.

Importing restaf and restaflib in your application

These two libraries are part of the installed dependencies. To access them in your react components do these as follows:

let restaf = require('@sassoftware/restaf/dist/restaf.js');
let restaflib = require('@sassoftware/restaflib/dist/restaflib.js');

or

import * as restaf from '@sassoftware/restaf/dist/restaf.js';
import * as restaflib from '@sassoftware/restaf/dist/restaflib.js';

In all probability you will not refer directly to restaf in your code. Instead, use the store object in the AppContext (see above). This value is set as part of the application startup.

Finally

The create-react-restaf-viya-app CLI tool helps jump start your application development. Feel free to clone the repository and make enhancements.