debian-image-builder-frontend/README.md

# image-builder-frontend

## Table of Contents
1. [How to build and run image-builder-frontend](#frontend-development)
   1. [Frontend Development](#frontend-development)
   2. [Backend Development](#backend-development)
2. [File structure](#file-structure)
3. [Style Guidelines](#style-guidelines)
4. [Test Guidelines](#test-guidelines)

## How to build and run image-builder-frontend

### Frontend Development

To develop the frontend you can use a proxy to run image-builder-frontend locally
against the chrome and backend at console.redhat.com.

Working against the production environment is preferred, as any work can be released without
worrying if a feature from stage has been released yet.

#### Nodejs and npm version

Make sure you have npm@7 and node 15+ installed. If you need multiple versions of nodejs check out [nvm](https://github.com/nvm-sh/nvm).

#### Webpack proxy

1. run `npm ci`

2. run `npm run prod-beta`. This command uses a prod-beta env by default. Configure your
   environment by the `env` attribute in `dev.webpack.config.js`.

3. Secondly redirect a few `prod.foo.redhat.com` to localhost, if this has not been done already.

```bash
echo "127.0.0.1 prod.foo.redhat.com" >> /etc/hosts
```

4. open browser at `https://prod.foo.redhat.com:1337/beta/insights/image-builder`

#### Webpack proxy (staging) -- *Runs with image-builder's stage deployment*

1. run `npm ci`

2. run `npm run stage-beta`. This command uses a stage-beta env by default. Configure your
   environment by the `env` attribute in `dev.webpack.config.js`.

3. Secondly redirect a few `stage.foo.redhat.com` to localhost, if this has not been done already.

```bash
echo "127.0.0.1 stage.foo.redhat.com" >> /etc/hosts
```

4. open browser at `https://stage.foo.redhat.com:1337/beta/insights/image-builder`

#### Insights proxy (deprecated)

1. Clone the insights proxy: https://github.com/RedHatInsights/insights-proxy

2. Setting up the proxy

    Choose a runner (podman or docker), and point the SPANDX_CONFIG variable to
    `profile/local-frontend.js` included in image-builder-frontend.

    ```
        sudo insights-proxy/scripts/patch-etc-hosts.sh
        export RUNNER="podman"
        export SPANDX_CONFIG=$PATH_TO/image-builder-frontend/profiles/local-frontend.js
        sudo -E insights-proxy/scripts/run.sh
    ```

3. Starting up image-builder-frontend

    In the image-builder-frontend checkout directory

    ```
        npm install
        npm start
    ```

The UI should be running on
https://prod.foo.redhat.com:1337/beta/insights/image-builder/landing.
Note that this requires you to have access to either production or stage (plus VPN and proxy config) of insights.

#### API endpoints

API endpoints are programmatically generated with the RTKQ library. This
sections overview the steps to add new APIs and endpoints.

##### Add a new API

For an hypothetical API called foobar

1. Download the foobar api openapi json or yaml representation under
`api/schema/foobar.json`

2. Create a new "empty" api file under `src/store/emptyFoobarApi.ts` that has for
content:

```{ts}
import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';

import { FOOBAR_API } from '../constants';

// initialize an empty api service that we'll inject endpoints into later as needed
export const emptyFoobarApi = createApi({
  reducerPath: 'foobarApi',
  baseQuery: fetchBaseQuery({ baseUrl: FOO_BAR }),
  endpoints: () => ({}),
});
```

3. Declare the new constat `FOOBAR_API` to the API url in `src/constants.js`

```
export const FOOBAR_API = 'api/foobar/v1'
```

4. Create the config file for code generation in `api/config/foobar.ts` containing:

```
import type { ConfigFile } from '@rtk-query/codegen-openapi';

const config: ConfigFile = {
  schemaFile: '../schema/foobar.json',
  apiFile: '../../src/store/emptyFoobarApi.ts',
  apiImport: 'emptyEdgeApi',
  outputFile: '../../src/store/foobarApi.ts',
  exportName: 'foobarApi',
  hooks: true,
  filterEndpoints: ['getFoo', 'getBar', 'getFoobar'],
};
```

5. Update the `api.sh` script by adding a new line for npx to generate the code:

```
npx @rtk-query/codegen-openapi ./api/config/foobar.ts &
```


6. Update the `.eslintignore` file by adding a new line for the generated code:

```
foobarApi.ts
```

7. run api generation

```
rpn run api
```

And voilà!

##### Add a new endpoint

To add a new endpoint, simply update the `api/config/foobar.ts` file with new
endpoints in the `filterEndpoints` table.


#### Unleash feature flags for the frontend

Your user needs to have the corresponding rights, do the
same as this MR in internal gitlab https://gitlab.cee.redhat.com/service/app-interface/-/merge_requests/79225
you can ask on the slack channel https://redhat-internal.slack.com/archives/C023YSA47A4 for a merge if your MR stays unchecked for a little while.

Then connect to the following platforms:
* https://insights-stage.unleash.devshift.net/ for stage
* https://insights.unleash.devshift.net prod

Once you have a toggle to work with, on the frontend code there's just need to
import the `useFlag` hook and to use it. You can get some inspiration from
existing flags:

https://github.com/RedHatInsights/image-builder-frontend/blob/c84b493eba82ce83a7844943943d91112ffe8322/src/Components/ImagesTable/ImageLink.js#L99

##### Mocking flags for tests

Flags can be mocked for the unit tests to access some feature. Checkout:
https://github.com/RedHatInsights/image-builder-frontend/blob/c84b493eba82ce83a7844943943d91112ffe8322/src/test/Components/CreateImageWizard/CreateImageWizard.test.js#L74

If the two possible code path accessible via the toggles are defined in the code
base, then it's good practice to test the two of them. If not, only test what's
actually owned by the frontend project.


##### Cleaning the flags

Unleash toggles are expected to live for a limited amount of time, documentation
specify 40 days for a release, we should keep that in mind for each toggle
we're planning on using.

### Backend Development

To develop both the frontend and the backend you can again use the proxy to run both the
frontend and backend locally against the chrome at cloud.redhat.com. For instructions
see [devel/README.md](devel/README.md).

## File Structure

### Quick Reference
| Directory                                                                                                            | Description                                |
| ---------                                                                                                            | -----------                                |
| [`/api`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/api)                                     | API schema and config files                |
| [`/config`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/config)                               | webpack configuration                      |
| [`/devel`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/devel)                                 | tools for local development                |
| [`/src`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/src)                                     | source code                                |
| [`/src/Components`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/src/Components)               | source code split by individual components |
| [`/src/test`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/src/test)                           | test utilities                             |
| [`/src/test/mocks`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/src/test/mocks)               | mock handlers and server config for MSW    |
| [`/src/store`](https://github.com/RedHatInsights/image-builder-frontend/tree/main/src/store)                         | Redux store                                |
| [`/src/api.js`](https://github.com/RedHatInsights/image-builder-frontend/blob/main/src/api.js)                       | API calls                                  |

## Style Guidelines

This project uses eslint's recommended styling guidelines. These rules can be found here:
https://eslint.org/docs/rules/

To run the linter, use:
```bash
npm run lint
```

Any errors that can be fixed automatically, can be corrected by running:
```bash
npm run lint --fix
```

All the linting rules and configuration of eslint can be found in [`.eslintrc.yml`](https://github.com/RedHatInsights/image-builder-frontend/blob/main/.eslintrc.yml).

### Additional eslint rules
There are also additional rules added to enforce code style. Those being:
- `import/order` -> enforces the order in import statements and separates them into groups based on their type
- `prefer-const` -> enforces use of `const` declaration for variables that are never reassigned
- `no-console` -> throws an error for any calls of `console` methods leftover after debugging

## Test Guidelines

This project is tested using the [Jest](https://jestjs.io/docs/getting-started) framework, [React Testing Library](https://testing-library.com/docs/react-testing-library/intro), and the [Mock Service Worker](https://mswjs.io/docs/) library.

All UI contributions must also include a new test or update an existing test in order to maintain code coverage.

### Running the tests

To run the unit tests, the linter, and the code coverage check run:
```bash
npm run test
```

These tests will also be run in our Travis CI when a PR is opened.

## API endpoints 

API slice definitions are generated using the [@rtk-query/codegen-openapi](https://redux-toolkit.js.org/rtk-query/usage/code-generation) package.

OpenAPI schema for the endpoints are stored in `/api/schema`. Their
corresponding configuration files are stored in `/api/config`. Each endpoint
has a corresponding empty API slice and generated API slice which are stored in
`/src/store`.

To generate or update API slice definitions, run:
```bash
npm run api
```