webapp-rocket

React web application sample with GraphQL, Apollo Client and AxaGuilDEv Oidc Client integration.

We can also help you get started with your GraphQL server. Check out our GraphQL Rocket Generator.

This application uses Rocket Webapp Components library to allow you to create smart and friendly web application interfaces.

Installation

First, install Yeoman and @totalsoft/generator-graphql-rocket using npm (we assume you have pre-installed NodeJS Latest LTS Version. Old versions of NodeJS are also supported.)

⚠ Use the npm version supported by your installed NodeJS version.

e.g. NodeJS Latest LTS Version: 14.17.1 (includes npm 6.14.13)

npm install -g yo
npm install -g @totalsoft/generator-webapp-rocket

If you want to use this generator to scaffold a new project navigate to section: Generate new project
To upgrade an existing project that was scaffold using this WebApp Rocket Generator, see section: Upgrade existing project

Content

1. Generate new project
2. Upgrade existing project
3. What is a Generator?
4. Code formatting
5. Enforcing Coding Conventions
6. Authentication
7. Authorization
8. Notifications
9. Custom hooks
10. Internationalization
11. Multi-tenancy
12. Deployment
13. Getting To Know Yeoman

Generate new project

To scaffold your new project using our generator run:

yo @totalsoft/webapp-rocket

⚠ Make sure you have the latest version of GraphQL WebApp Generator installed, else you will be prompted the following message:

You will be prompted to introduce the following information:

1. The project name. This will also be the name of the new folder in which the new application will live. A valid project name, only includes lower and upper case letters, digits and '-' or '_' separators! No special characters and whitespace are allowed and do not start or end with a separator!
2. Project description. This will be visible in the browser tab and link details.
3. GraphQL address. By default it would be set to localhost:4000
4. Use subscription. By default is set to false. This will include the WebSocket link in ApolloClient.
5. Application theme. There is a list of available themes you can choose from.
6. Whether to generate default helm files or not.
7. If you choose to include default helm files you would also be prompted to specify a name for your helm chart. A valid helm chart name, only includes lower case letters, digits and '-' separators! No special characters and whitespace are allowed and do not start or end with a separator!
8. Use rights. By default is set to false. This will also generate a GET_USER_DATA query that loads the users rights. (see the query below)
9. Include multi-tenancy. By default is set to false.
10. Would you like to include quick start examples? If so, some end to end examples will be included in your new generated project to help you get started.
11. What package manager you wish to use to install the application dependencies. (npm or yarn).

If you would like to start the application, simply run npm start in the newly created folder, otherwise you can begin editing and writing your application!

Upgrade existing project

⚠ First, make sure you have committed everything or have a backup of your existing project.

⚠ RECOMMENDATION! ⚠

To avoid having lots of differences, make sure you have Prettier formatter installed in your project. npm install prettier --dev

Also a file named .prettierrc containing the desired formatting settings is placed in the root of the project. See Code formatting section to see the generator's default config file.

Then apply your formatting rules to the existing files by executing: prettier --write **/*.js

To upgrade an existing project that was scaffold using this generator open a console outside of your project folder ( see image below ) and run:

yo @totalsoft/webapp-rocket

Now you will be asked to answer the same questions explained in Generate new project section.

⚠ ATTENTION! ⚠

When prompted to enter the name of your project make sure you enter the name of the project you want to upgrade ( like shown in the above image ). If you enter a new name, it will generate a new project.

Mainly you have to choose all the options already included in your existing project, or you can add new ones.

⚠ If you decide not to include an option that was previously installed on your existing project (e.g. Authorization), Yeoman will not remove files or folders by its own, he just merges existing files or created new ones, and you would have to manually delete the unnecessary files or folders.

After answering all the questions, Yeoman will ask you for each file if you want to overwrite it with the latest version. You can type a, and this will automatically override all the files, and all the changes could be seen in as changes in your IDE, and it's up to you to check all the changed files before you commit everything. Or hit space to see all your options (see below image).

What is a Generator?

A Yeoman generator is a scaffolding tool. You can use Yeoman to install applications based on templates. This repository is an example of a template - an application with a build, code structure, and dependencies installed and organized for you!

Using a generator accelerates application development. You don't have to worry about best practices for foundational elements, because we've incorporated them. Our template generates a fully functional web application foundation that becomes the infrastructure of your new project. Before this miracle generator existed, this code would probably took you a few days to write, oh well... now this will be done in only 30 seconds!

We have included integrations with essential libraries, as well as pages, routes, and components that are both useful in most react web applications (like forbidden pages).

Included latest versions of the following libraries and technologies: React, GraphQL, Apollo Client, AxaGuilDEv/react-oidc, @totalsoft/jsbb, Material-UI, and many more, see generators/app/templates/infrastructure/package.json file.

Code formatting

The generated code is formatted using the Prettier formatter. A file named .prettierrc containing the formatting settings is placed in the root of the project.

For maintaining unitary style, the .prettierrc configuration file is read by other tools that run Prettier such as scripts or IDE extensions. For example if using Visual Studio Code we recommend installing the following extension Prettier formatter

In case the .prettierrc file is customized, the new settings will be used when re-running the generator. The only condition is to answer no when asked to overwrite this file.

The default prettier config file can be found here: .prettierrc

Enforcing Coding Conventions

Ensuring code quality is very important for a maintainable and scalable application. As a default, this generator automatically will install and configure ESLint and Prettier in your project, for a consistent code formatting. ( Read more about this in Code formatting section. ).

To help you enforce this standards, the generator also comes with this great library called Husky ( 🐶 woof! ).

Husky is a JavaScript package that allows you to run some code during various parts of your git workflow. Husky leverages git hooks to allow you to hook into various git events such as pre-commit and pre-push.

This application uses husky to trigger lint-staged during the pre-commit hook to automate the tedious part of your workflows, such as formatting with Prettier and/or linting with ESLint. Your code gets fixed before it ever leaves your machine, so you don’t have to wait for your CI to inform you that you forgot to run the formatter or linter.

⚠ Configuring a monorepo with multiple packages

By design, husky install must be run in the same directory as .git. If your project is a monorepo containing multiple packages, for example a Server and Client sub-folders, husky will expects your package.json to be at the root of your project.

If you don't want to add a separate package.json in your root just for this, you need to change the husky configurations in your Server and Client projects as follows:

• Change directory during prepare script and pass a subdirectory

// clientProject/package.json
"scripts": {
    "prepare": "cd .. && husky install clientProject/.husky"
}

// serverProject/package.json
"scripts": {
    "prepare": "cd .. && husky install serverProject/.husky"
}

• You'll also need to change directory in one of Client or Server hooks and write for both projects

// clientProject/.husky/pre-commit
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

cd serverProject
npx lint-staged
npm run test:ci

cd ../clientProject
npx lint-staged
npm run test:ci

• Run npm install in both projects and that’s it! Now if you try to make a commit, you will see that eslint and prettier will run and fix themselves as you would expect.

Authentication

By default, the application uses Identity SaaS. See AxaGuilDEv/react-oidc.
The authentication is executed using a secure token which will also contain information about the logged user like: user data and roles.

In order to connect your new application to an identity server, the following configuration variables must be filled in .env file:

IDENTITY_API_URL -> Identity API url, your Identity server API url 

IDENTITY_AUTHORITY -> Identity authority

IDENTITY_OPENID_CONFIGURATION -> Identity openId configuration

A user can have one or more roles from the following list:

• admin (tenant_admin)
• user (tenant_user)
• global_admin (only with multi-tenancy)

If you want to use another authentication service, the following files must be modified:

• src/index.js
• src/utils/auth
• src/providers/AuthenticationProvider.js
• src/components/routing/CustomRoute.js

⚠ RECOMMENDATION! ⚠ It is HIGHLY recommended to use <CustomRoute /> component when defining a new route. This is an enhanced version of the basic react-router-dom's <Route /> component. In addition, it allows a more deeper customization of a route and by default it comes with the following configuration parameters:

• isPrivate: if set to True, allows only the logged in users to access the route.
• roles: a list of predefined roles. For more details see Authorization;
• rights: a list of predefined rights. For more details see Authorization;
• fullWidth: if set to True, it removes the margins and paddings of the main content of the application screen

const GET_USER_DATA = gql`
query userData($externalId: ID!){
  userData(externalId: $externalId){
    id
    userName
    rights
  }
}
`

export const MY_TENANTS_QUERY = gql`
  query {
    myTenants {
    externalId
    name
    code
    tier
    isActive
    tenant {
    id
    name
    code
    }
  }
}
`