Skip to content

GenericSuite for ReactJS

The GenericSuite (frontend version) has a customizable CRUD editor, menu generator, login interface, API secure communication and a suite of tools to kickstart your development process.

Features

  • Customizable CRUD editor: core CRUD (Create-Read-Update-Delete) code that can be parametrized and extended by JSON configuration files. There's no need to rewrite code for each table editor.
  • Customizable menu: menu and endpoints can be parametrized and extended by JSON configuration files in the backend side. The API will supply the menu estructure and security check based on the user's security group, and GenericSuite will draw the menu and available options.
  • Customizable Login Interface: Easily adapt the login page to match your brand identity with the App logo.
  • Development and Production Scripts: Quick commands to start development or build your application for QA, staging production environments on AWS.
  • Testing with Jest: Comes pre-configured with Jest for running tests, including an initial test for the <App /> component.

The perfect companion for this frontend solution is the backend version of The GenericSuite.

There's a version of this library with AI features: The GenericSuite AI.

Pre-requisites

You need to install these tools:

Getting Started

To get started with GenericSuite, follow these steps:

Create the git repositories

Create the git repositories in your favorite Git Platform (Github, Gitlab, Bitbucket).

One repository is for the frontend App, and the other for the configs (JSON configuration files) to be shared between the frontend and backend repos as a Git sub-module.

Once created, open a Terminal window and change to your repositories' root directory.

Clone the repos.

E.g. for a repo called exampleapp_frontend created in Github:

git clone https://github.com/tomkat-cr/exampleapp_frontend.git

And for the configs repo called exampleapp_configs created in Github:

git clone https://github.com/tomkat-cr/exampleapp_configs.git

Initiate your project

Create the ReactJs App. E.g. exampleapp_frontend:

npx create-react-app exampleapp_frontend

It automatically performs the npm init and git init, adds the ReactJS dependencies, and creates a default ReactJS project structure.

NOTE: Check the documentation here for CRA (create-react-app) alternatives.

Change to your frontend local development directory.

cd exampleapp_frontend

CRA (create-react-app) is outdated, so we use react-app-rewired to customize CRA configuration with no need to eject:

npm install --save-dev react-app-rewired

Install the GenericSuite Library

npm install genericsuite

Install additional development dependencies

npm install --save-dev \
   @babel/cli \
   @babel/core \
   @babel/plugin-proposal-class-properties \
   @babel/plugin-proposal-private-property-in-object \
   @babel/plugin-syntax-jsx \
   @babel/preset-env \
   @babel/preset-react \
   @babel/preset-stage-0 \
   @babel/preset-typescript \
   @testing-library/jest-dom \
   @testing-library/react \
   @testing-library/user-event \
   @types/jest \
   @types/react \
   babel-jest \
   babel-loader \
   babel-plugin-css-modules-transform \
   css-loader \
   file-loader \
   html-webpack-plugin \
   interpolate-html-plugin \
   jest \
   jest-environment-jsdom \
   path \
   postcss \
   postcss-loader \
   react-test-renderer \
   style-loader \
   tailwindcss \
   url-loader \
   webpack \
   webpack-cli \
   webpack-dev-server \
   whatwg-fetch

Uninstall not required dependencies

Uninstall not required dependencies installed by CRA and included in the GenericSuite library:

npm uninstall react react-dom react-scripts web-vitals

Prepare the Configuration Files

Copy the .env file template from node_modules/genericsuite:

cp node_modules/genericsuite/.env.example ./.env

And configure the variables according your needs:

  • Assign REACT_APP_APP_NAME with your App's name.

  • Assign APP_LOCAL_DOMAIN_NAME with the local development environment backend API domain name. E.g. app.exampleapp.local or localhost.
    Defaults to app.${REACT_APP_APP_NAME}.local (the REACT_APP_APP_NAME will be converted to all lowercase).

  • Assign FRONTEND_LOCAL_PORT with the local development frontend port number. Defaults to 3000.

  • Assign BACKEND_LOCAL_PORT with the local development backend API port number. Defaults to 5000.

  • Assign APP_API_URL_QA, APP_API_URL_STAGING, APP_API_URL_PROD, and APP_API_URL_DEMO with the corresponding public backend API domain names for your App environments.

  • Assign APP_FE_URL_QA, APP_FE_URL_STAGING, APP_FE_URL_PROD, and APP_FE_URL_DEMO with the corresponding public frontend domain names for your App environments.

  • Assign REACT_APP_URI_PREFIX with the App URI prefix. This will be used in all environments after the domain name. E.g. https://app.exampleapp.com/exampleapp_frontend

  • Configure your desired RUN_METHOD. Available options are "webpack" and "react-scripts". Defaults to "webpack".

  • Configure BACKEND_PATH with the path for your backend API local development repo.

  • Configure GIT_SUBMODULE_LOCAL_PATH and GIT_SUBMODULE_URL with the JSON files submodule parameters to stablish a common configuration place for both frontend and backend (used by add_github_submodules.sh).
    For example files, visit: Generic Suite Configuration Guide

  • Configure the AWS_* parameters with your AWS data (used by aws_deploy_to_s3.sh and change_env_be_endpoint.sh). You'll need an AWS account.

For more information, check the comments for each variable in the .env.example file.

Other parameters

  • REACT_APP_X_TOKEN=1 to use 'x-access-tokens' instead of 'Authorization: Bearer'. Defaults to "0"

Prepare the Makefile

Copy the Makefile template from node_modules/genericsuite:

cp node_modules/genericsuite/Makefile ./Makefile

Change Scripts in Package.json

Open the package.json:

vi ./package.json
# or
# code ./package.json

If you want to host your frontend on github.io, add the homepage parameter:

"homepage": "https://your-github-username.github.io/your-github-repository/",

NOTE: replace `your-github-username` and `your-github-repository` with your owns.

Add the following scripts:

   "scripts": {
      "start": "node server.js",
      "start-build": "./node_modules/react-app-rewired/bin/react-app-rewired.js build && node server.js",
      "start-debug": "ls -lah && node server.js",
      "start-dev": "react-app-rewired start",
      "start-dev-webpack": "npx webpack-dev-server --config webpack.config.js",
      "build-prod": "webpack --mode production",
      "build-dev": "react-app-rewired build",
      "build": "react-app-rewired build",
      "eject-dev": "react-scripts eject",
      "test-dev": "react-app-rewired test",
      "test": "jest",
      "predeploy": "npm run build",
      "deploy": "gh-pages -d build"
   },

App structure

This is a suggested App development repository structure:

.
├── .babelrc
├── .env
├── .env.example
├── .gitignore
├── CHANGELOG.md
├── LICENSE
├── Makefile
├── README.md
├── babel.config.js
├── config-overrides.js
├── jest.config.cjs
├── package-lock.json
├── package.json
├── public
├── server.js
├── src
│   ├── components
│   │   ├── About
│   │   │   └── About.jsx
│   │   ├── App
│   │   │   ├── App.jsx
│   │   │   └── App.test.tsx
│   │   ├── HomePage
│   │   │   ├── HomePage.jsx
│   │   ├── ExampleMenu
│   │   │   ├── ExampleMainElement.jsx
│   │   │   └── ExampleChildElement.jsx
│   ├── constants
│   │   └── app_constants.jsx
│   ├── images
│   │   ├── app_logo_circle.svg
│   │   └── madeby_logo_square.svg
│   ├── configs
│   │   ├── CHANGELOG.md
│   │   ├── README.md
│   │   ├── backend
│   │   │   ├── app_main_menu.json
│   │   │   ├── endpoints.json
│   │   │   ├── general_config.json
│   │   │   ├── example_main_element.json
│   │   │   └── example_child_element.json
│   │   └── frontend
│   │       ├── app_constants.json
│   │       ├── general_constants.json
│   │       ├── users_profile.json
│   │       ├── example_main_element.json
│   │       └── example_child_element.json
│   ├── d.ts
│   ├── index.jsx
│   ├── input.css
│   └── setupTests.js
├── tailwind.config.js
├── tsconfig.json
├── version.txt
└── webpack.config.js

Configure the project

In the project's directory:

Suggested Tailwind configuration:

const { relative } = require('path');

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'selector',
  content: {
    relative: true,
    files: [
      "./node_modules/genericsuite/src/lib/**/*.{html,js,jsx}",
      "./src/lib/components/**/*.{html,js,jsx}",
      "./src/lib/constants/**/*.{html,js,jsx}",
                .
                .
      "./src/index.{tsx,jsx,cjs}",
      './public/index.html',
    ],
  },
  theme: {
    extend: {},
  },
  plugins: [
  ],
}

  • webpack.config.js (example)
    To configure Webpack as an alternative to CRA / react-app-rewired.
    IMPORTANT: Make sure to replace entry: './src/index.tsx' by entry: './src/index.jsx'.
    Check the documentation here.

  • tsconfig.json

To configure TypeScript. e.g.

{
  "compilerOptions": {
    "outDir": "./dist",
    "module": "ESNext",
    "moduleResolution": "node",
    "target": "es5",
    "lib": [
      "es6",
      "dom"
    ],
    "sourceMap": true,
    "allowJs": true,
    "checkJs": false,
    "jsx": "react",
    "baseUrl": "./src",
    "rootDirs": [
      "src"
    ],
    "resolveJsonModule": true,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "skipLibCheck": true,
    "declaration": true,
    "declarationDir": "types",
    "emitDeclarationOnly": true,
    "paths": {
      "src/*": ["./src/*"],
    }
  },
  "include": [
    "src/**/*",
  ]
}

Customize index.html

Option 1

If you don't have a customized public/index.html (just the default one created by CRA):

Create the index.html file:

vi public/index.html

Copy and paste this content:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta name="theme-color" content="#000000" />
    <meta
      name="description"
      content="Web site created using create-react-app"
    />
    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />
    <!-- Tailwind -->
    <link href="%PUBLIC_URL%/output.css" rel="stylesheet">
    <!--
      manifest.json provides metadata used when your web app is installed on a
      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
    -->
    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
    <!--
      Notice the use of %PUBLIC_URL% in the tags above.
      It will be replaced with the URL of the `public` folder during the build.
      Only files inside the `public` folder can be referenced from the HTML.

      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
      work correctly both with client-side routing and a non-root public URL.
      Learn how to configure a non-root public URL by running `npm run build`.
    -->
    <title>exampleapp.com</title>
    <style>
        a { cursor: pointer; }
    </style>
    <base href="/">
  </head>
  <body>
    <noscript>You need to enable JavaScript to run this app.</noscript>
    <div id="root"></div>
    <!--
      This HTML file is a template.
      If you open it directly in the browser, you will see an empty page.

      You can add webfonts, meta tags, or analytics to this file.
      The build step will place the bundled scripts into the <body> tag.

      To begin the development, run `npm start` or `yarn start`.
      To create a production bundle, use `npm run build` or `yarn build`.
    -->
  </body>
</html>

Option 2

If you already have a public/index.html file customized:

Edit the index.html file:

vi public/index.html

Make sure to add %PUBLIC_URL% to these lines:

    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />

    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />

    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />

After this line:

    <link rel="apple-touch-icon" href="%PUBLIC_URL%/logo192.png" />

... add this line:

    <link href="%PUBLIC_URL%/output.css" rel="stylesheet">

Remove the footer and credits:

    <!-- credits -->
    <div class="text-center">
      <p>
          <a href="https://exampleapp.com" target="_blank" rel="noreferrer">exampleapp.com</a>
      </p>
    </div>

Final step for any option

Finally run this command to create the src/output.css file:

npx tailwindcss -i ./src/input.css -o ./src/output.css

And copy the file generated to the public directory:

cp src/output.css public/

To keep the src/output.css file updated, during the development cycle open a new terminal and run:

make tailwind

Code examples and JSON configuration files

The main menu, API endpoints and CRUD editor configurations are defined in the JSON configuration files.

You can find examples about configurations and how to code an App in the GenericSuite App Creation and Configuration guide.

Usage

Do the first build

make build

Start Development Server

To start the development server:

make run

Deploy QA

Check the Deployment Guide for details.