Getting Started

FastUI is a methodology for creating monorepo React applications. It offers a modern build setup with no configuration.

Creating a Repository from GitHub Template

We can click on this link to generate a repository using the template: Create a new repository from QubitPi/fast-ui. Alternatively, we can visit the fast-ui repository on GitHub and click on the "Use this template" button on the top-right.

In both cases, the next steps are:

Enter a name for the new repository.
Uncheck "Include all branches".
Click on "Create repository from template".

For more details on how to create repositories using template, read the article on the GitHub website: Creating a repository from a template.

caution

If the repository is public, GitHub offers unlimited free build minutes. If it's a private repository, however, billing policy applies

After Creating the Repository

At this point, A ReactJS project with just what we need to start quickly has been generated. Developer can now start adding business value and get work done much faster in a standard way. The following sections of this documentation contain further details on how to proceed next.

note

The following steps apply to the newly created repository, not the QubitPi/fast-ui template repository.

Quick Start

yarn
yarn start

Then open http://localhost:3000/ to see the app. When we are ready to deploy to production, create a minified bundle with

yarn build

That's it. We don't need to install or configure tools like webpack or Babel. They are preconfigured and hidden so that we can focus on the code.

Scripts

Inside the newly created project, we can run some built-in commands:

`yarn start`

Runs the app in development mode. Open http://localhost:3000 to view it in the browser. The page automatically reloads if we make changes to the code. we will see the build errors and lint warnings in the console.

`yarn test`

Runs the unit tests

`yarn cypress:open` and `yarn e2e`

Opens Cypress End-to-End test console and runs the End-to-End tests, respectively

`yarn build`

Builds the app for production to the build folder. It correctly bundles React in production mode and optimizes the build for the best performance. The build is minified and the filenames include the hashes.

Our app is ready to be deployed.

Enabling Automatic Deployment to GitHub Pages

Navigate to .github/workflows/ci-cd.yaml and change the documentation-ci-cd to a new definition called deploy as follows:

---
name: CI/CD

"on":
  pull_request:
  push:
    branches:
      - master

env:
  USER: MyGitHubUsername
  EMAIL: myemail@email.com
  NODE_VERSION: 18

jobs:
- documentation-ci-cd:
-   name: Test and Deploy Documentation to GitHub Pages
-   needs: e2e-tests
-   runs-on: ubuntu-latest
-   defaults:
-     run:
-       working-directory: docs
-   steps:
-     - uses: actions/checkout@v3
-     - uses: actions/setup-node@v3
-       with:
-         node-version: ${{ env.NODE_VERSION }}
-     - name: Install nexusgraph dependencies so that TypeDoc process source files properly
-       run: cd ../ && yarn install
-       env:
-         YARN_ENABLE_IMMUTABLE_INSTALLS: false
-     - name: Install doc dependencies
-       run: yarn install
-       env:
-         YARN_ENABLE_IMMUTABLE_INSTALLS: false
-     - name: Build documentation
-       run: yarn build
-     - name: Load CNAME
-       run: echo fastui.qubitpi.org > build/CNAME
-     - name: Deploy to GitHub Pages
-       if: github.ref == 'refs/heads/master'
-       uses: peaceiris/actions-gh-pages@v3
-       with:
-         github_token: ${{ secrets.GITHUB_TOKEN }}
-         publish_dir: ./docs/build
-         enable_jekyll: false
-         user_name: ${{ env.USER }}
-         user_email: ${{ env.EMAIL }}
+ deploy:
+   name: Deploy to GitHub Pages
+   needs: e2e-tests
+   runs-on: ubuntu-latest
+   steps:
+     - uses: actions/checkout@v3
+       with:
+         fetch-depth: 0
+     - name: Set node version to ${{ env.node_version }}
+       uses: actions/setup-node@v3
+       with:
+         node-version: ${{ env.node_version }}
+     - name: Install dependencies
+       run: npm install -g yarn@1.22.19 && yarn
+     - name: Test production build
+       run: yarn build
+     - name: Load CNAME
+       run: cp CNAME dist
+     - name: Deploy to GitHub Pages
+       if: github.ref == 'refs/heads/master'
+       uses: peaceiris/actions-gh-pages@v3
+       with:
+         github_token: ${{ secrets.GITHUB_TOKEN }}
+         publish_dir: dist
+         enable_jekyll: false
+         user_name: ${{ env.USER }}
+         user_email: ${{ env.EMAIL }}

Please replace MyGitHubUsername and myemail@email.com accordingly
The CNAME file will be the domain where the React app will be hosted. If no domain is planned to be attached at this moment, simply remove this step please

Enabling Argos Visual Testing

To enable the Argos, create an Argos project first. To upload snapshot to Argos CI, an ARGOS_TOKEN is required and can be obtained after creating the Argos project.

After getting the ARGOS_TOKEN token, add it as a repository secret:

In the newly created repository, select Settings
In the left sidebar, click Secrets and variables followed by Actions
Press the button New repository secret
Enter the name of the secret as ARGOS_TOKEN
Paste the token from the project on Argos CI
Be sure there are no spaces before or after the token and/or linebreaks after the token
Save the secret by selecting Add secret

info

For more information on GitHub Secrets, please refer to the GitHub documentation: Using secrets in GitHub Actions.

Enabling sentry.io Application Monitoring

Creating a Sentry Project

In order to capture errors and other events, we need to have a project set up in Sentry. This section walks through how to create a new project in our Sentry account. We need to have a project set up in Sentry in order to capture errors and other events.

tip

For more information, see sentry.io's documentation on best practices for creating projects.

Follow the steps below to create a new Sentry project for a our React application:

Log in to your Sentry organization.
Select Projects from the left side navigation menu to display the list of all our projects.
Click Create Project and configure it as appropriate for our application:

Choose your platform: Select the language or framework for our project based on the code we wish to monitor. In this case, choose React .
Set your alert frequency: For the purpose of our setup, select I'll create my own alerts later.

tip
Learn more about how to set up your alerts in Alerts Best Practices
Name your project and assign it a team: Name the project in the Project name field and assign a team by selecting one in the Team dropdown (or click + to create a new team).
Click Create Project. This takes us to the quick Configure React SDK guide, which provides an overview of how to configure the SDK. This section covers the SDK setup in more detail.

Copy the DSN key and keep it handy. Each project has a unique DSN (Data Source Name). The DSN tells the SDK where to send events, so events are associated with the right project. We'll need to paste the DSN key into our source code later so the errors generated in the React app go to our new project.

We can also find a project's DSN anytime in [Project] > Settings > Client Keys (DSN).

UI Walkthrough

Adding the Sentry SDK to Project

Open src/index.tsx and change the following lines of code as follows:

  Sentry.init({
-   dsn: "https://5e82dcf741091e63d616982f0cbcf0e5@o4505480921022464.ingest.us.sentry.io/4508702863589376",
+   dsn: "<your_DSN_key>",

where <your_DSN_key> is the DSN obtained in previous step.

The template configuration enables Sentry's error monitoring feature, as well as its Performance (tracing) and Session Replay features.

Configuring Source Maps Upload

FastUI supports uploading source maps to sentry.io with webpack plugin. We only need to configure an Organization Auth Token and FastUI will do all of the rests. After getting the SENTRY_AUTH_TOKEN token, add it as a repository secret:

In the newly created repository, select Settings
In the left sidebar, click Secrets and variables followed by Actions
Press the button New repository secret
Enter the name of the secret as SENTRY_AUTH_TOKEN
Paste the token
Be sure there are no spaces before or after the token and/or linebreaks after the token
Save the secret by selecting Add secret

At last, add the following CI/CD config to the automatic deployment logic:

    name: Deploy to GitHub Pages

    ...

      - name: Test production build
        run: yarn build
+       env:
+         SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
      - name: Load CNAME

    ...

Developing App

Automatically Formatting Codebase

When CI/CD complains about "Code style check" as the following:

Simply run the following command at project root which will auto formatting the codebase using Prettier:

yarn prettier --ignore-path .gitignore . --write

tip

It's always a good practice to auto-formatting code whenever convenient

Importing SVG

import MySvg from "./example.svg"

function MyComponent(): JSX.Element {
  return (
    <div className="svgIcon">
      <img src={MySvg} alt="MySvg" />
    </div>
);
}

Creating a Repository from GitHub Template​

After Creating the Repository​

Quick Start​

Scripts​

yarn start​

yarn test​

yarn cypress:open and yarn e2e​

yarn build​

Enabling Automatic Deployment to GitHub Pages​

Enabling Argos Visual Testing​

Enabling sentry.io Application Monitoring​

Creating a Sentry Project​

UI Walkthrough​

Adding the Sentry SDK to Project​

Configuring Source Maps Upload​

Developing App​

Automatically Formatting Codebase​

Importing SVG​