dev.md

Development

a getting started guide for developers

UX / Components

patternfly is the primary UX guidance and is used for the main components store. You can find further shared components and utils by @redhat-cloud-services Thanks to the micro-frontend architecture of cloud.redhat.com, you can also consume components from other frontend apps by using the <AsyncComponent> loader, this also allows you to consume provisioning's components in a different frontend app.

API

react-query is used for managing, mutating, and caching the server's state. This approach simplifies the need of maintaining a global state for the data layer and gives out-of-the-box solutions for server-client optimizations.

How to fetch/mutate data from the server

First have a look in the API/index.js to see if there's already a fetch function for your desired data, if not:

1. Add a fetch function in the API/index.js

   export const fetchSomeList = async () => {
     const { data } = await axios.get(provisioningUrl('<endpoint>'));
     return data;
    };

2. Add a specific constant or a function for the request's key in API/keys.js, this allow caching data and prevents redundant fetching, for further information about creating a query key, see queries keys docs
3. Consume the hook useQuery in your component

    const {
      isLoading,
      isError,
      error,
      data,
    } = useQuery(MY_QUERY_KEY, fetchSomeList);

There are plenty of options to choose from, i.e depended on queries, stale query, caching time, manual triggering, polling, and more. For further reading visit the useQuery API

Wizard Context

While the react-query replaces the need for managing the server's data state, there's a need to manage a client's context. For implementing a simple wizard context, we use the native useState wrapped by react-tracked which is used for optimizing the DOM and preventing enforce redundant re-renders on context values changes.

When to use the wizard context

As a rule of thumb, if a client state is required in multiple steps (wizard steps), then it makes sense to store it in a context (like the native React.Context approach), so we won't need to propagate many local state (and setters functions) deeply in the wizard tree. Try to keep the context data as primitive as you can (string, number, boolean) for preventing future optimizations issues.

How to use it

import { useWizardContext } from '../Common/WizardContext';

  const [wizardContext, setWizardContext] = useWizardContext();

  clickHandler(id) => {
    // updating the context
    setWizardContext((prevState) => ({ ...prevState, chosenItemID: id }));
}
  // using the context, `data` can be some list from the server's state
  const chosenItem = data.find(item => item.id === wizardContext.choseItemID);