Creating a React Component

Added in 24.06.

Learn about how to create a React component using Commands for your Aurora Community.

React components are created by adding code to your community’s Git repository and displayed in your community by adding them to a page quilt. We will make a Cat Fact React component and display it as a button in the UI.

Requirements

To create a React component, you must meet the following requirements:

1. Access to your community’s Git repository
2. Admin role to add the React component to a page in your community.

Contents of a React Component

The React component folder in the Git repository must have these mandatory files:

• A text file (text.en.json) to provide translated text to the custom component
• .component.json - A component descriptor file
• .tsx - The Typescript React component
• package.json - Specifies any additional NPM libraries your component might need

Command Actions

1. Sign in to your community’s git repository.
2. Ensure your community’s Git repository has a /src folder. If there is no src folder, create one using:

   mkdir src

3. Create a components folder under the src folder:

   mkdir components

4. Create a CatFactToast folder under your components folder.
5. Create a text folder under the CatFactToast folder.
   Add a file text.en.json with the following content:

   {
     "button.title": "Cat fact!"
   }
   

6. Inside the CatFactToast folder, create a CatFactToast.component.json file with the following code:

   {
     "id": "CatFactToast",
     "markupLanguage": "REACT",
     "defaults": {
       "config": {
         "applicablePages": [],
         "description": "This example component calls the custom CatFact endpoint and displays a toast with the result."
       },
       "props": []
     },
     "components": [
       {
         "id": "custom.widget.CatFactToast"
       }
     ],
     "grouping": "CUSTOM"
   }
   

7. Create a CatFactToast.tsx file with the following code inside the CatFactToast folder:

   import type { CustomComponentProps } from 'aurora/externalContext';
   import React from 'react';
   
   /**
    * This example component calls the custom CatFact endpoint and displays a toast with the result.
    */
   const CatFactToast: React.FC<CustomComponentProps> = ({ auroraContext }) => {
     const { components, utils } = auroraContext;
     const { log, i18n, addToast, postToInternalApi } = utils;
     const { Button, Panel, PanelBody, enums } = components;
     const { ToastVariant, ToastAlertVariant } = enums;
   
     function showToast(
       toastTitle: string,
       toastMessage: string,
       toastVariant = ToastVariant.FLYOUT,
       toastAlertVariant = ToastAlertVariant.SUCCESS
     ) {
       addToast({
         id: 'catfact-toast',
         title: toastTitle,
         message: toastMessage,
         toastVariant,
         alertVariant: toastAlertVariant
       });
     }
   
     async function fetchCatFact() {
       try {
         const endpoint = '/endpoints/catfact';
         const factResponse = await postToInternalApi(endpoint);
         if (factResponse.ok) {
           const json = await factResponse.json();
           const [toastTitle, toastMessage] = json.message.split(':');
           showToast(toastTitle, toastMessage, ToastVariant.BANNER, ToastAlertVariant.INFO);
         } else {
           log.warn('Unable to call endpoint at %s: %s', endpoint, factResponse.statusText);
         }
       } catch (error) {
         log.error(error, 'Error fetching cat fact');
       }
     }
   
     return (
       <div>
         <Panel>
           <PanelBody>
             <p>
               <Button onClick={() => fetchCatFact()}>{i18n.formatMessage('button.title')}</Button>
             </p>
           </PanelBody>
         </Panel>
       </div>
     );
   };
   
   export default CatFactToast;
   

8. Create a package.json file with the following content:

   {
     "name": "@customer/catfact-toast-component",
     "version": "0.0.1",
     "private": true,
     "devDependencies": {
       "@types/react": "^18.2.22"
     },
     "dependencies": {
       "react": "^18.2.0"
     }
   }
   

9. Commit and push these changes to a branch of your plugin in your community.
10. Create a pull request to merge these changes into the main branch of your plugin (<phase>-main, not main). The pull request must be merged.

Add a React Component to a Page

1. Sign in to your community.
2. Open the Account menu and select Designer.
3. Go to Page Templates and select the page where you want to add the custom component.
4. Select the "+" symbol to add the component.
5. Select Custom under Other.

   

6. Select the CatFactToast component.
   This will add your React component to your page quilt.

   

7. Select Save and Publish.
   The component is displayed on the page.

   

8. In your browser, navigate to the page where the component was published.
9. In a new terminal shell, run:

   npm run dev

   This will start the dev server process. The process can be stopped using Ctrl+C.
10. In your browser, reload the page with the component.
    The sample React component will now load from your local dev server (http://localhost:3002).
11. Edit the src/components/ReactComponent/Component.tsx file.
12. In your browser, reload the page with the component.
    Your changes will be reflected on the component.
    After the dev process stops, all changes are cleared. Note that the temporary changes are only visible while logged in.
13. To continue development on a separate branch, create a new branch of your plugin from qa-main.
14. After this is complete, you can safely remove the custom component from the page where it was added from the Designer. It will still appear on the page as long as you specify your branch as the Active Branch in Dev Tools (/admin/dev in your community).