NexusUI Create React App (CRA) Template

Create React App (CRA) is an officially supported method for creating React single-page applications. The two default templates provided by CRA give you a very minimal scaffold to work from. Typical applications need to add many additional libraries and configurations to make the app useful, which is time consuming and leads to apps being set up in different ways by different teams. We provide this custom NexusUI template — @nexusui/cra-template-typescript — to streamline the process for NexusUI applications. The template comes out of the box with the following integrations:

• React(18)
• React Router
• React Redux
• ESLint
• Prettier
• Jest(unit testing)
• React Testing Library (unit testing)
• Playwright (E2E testing)
• Auth0
• Material UI (MUI) component library
• Nexus UI components & theme
• Application Insights
• Localization

Installation

Run the following command to initialize your repository:

# With yarn
yarn create react-app my-app --template @nexusui/typescript

# With npx
npx create-react-app my-app --template @nexusui/typescript

If you are using yarn version 3 and encounter errors during installation and / or running, you can resolve them by following these steps:

• 1. Delete the yarn.lock, .pnp.cjs, and .pnp.loader.mjs files
• 2. Add .yarnrc.yml file in root folder with following content: nodeLinker: node-modules
• 3. Run yarn install to reinstall dependencies

Start

Once you have properly initialized your project and installed dependencies, you can start your application with the following command:

```sh
# With yarn
yarn start

# With npm
npm start
```

Test

1. Unit test

   • React Testing Library is already integrated in the nexus template project as the preferred unit testing framework. You can run your unit test cases by running the following command:

     # With yarn
     yarn test
     
     # With npm
     npm test

2. E2E test

   • Playwright is already integrated in the nexus template project as the preferred e2e testing framework. In order to use Playwright, you will need to update the /e2e/config/env.json file with your account credentials.

   • Run your e2e test by executing the following commands:

     npx playwright install
     npx playwright test

Auth0

Auth0 is the authentication and authorization platform used by NexusUI projects. This template automatically includes the auth0 SDK and provides a temporary client ID. For your production application, you will need to request your own auth0 ClientID and replace the temporary id in .env.development. This template provides basic auth0 usage, but you can customize auth0 login logic / behavior to suit your specific needs.

Application Insights

Application Insights is an extension of Azure Monitor and provides Application Performance Monitoring. This template automatically includes the necessary dependencies and setup. For your production application, you will need to request an Application Insights key and update the value in .env.development.

Localization

This template automatically integrates react-i18next which is used for translation / localization as well as the NexusUI localization utility script, which conveniently delivers your language resource file to LanguageWire for human translation services.

Nexus developers can see the full instructions for using the localization scripts here. Most of these steps have already been integrated into the template — you only need to take the following additional steps:

1. In package.json, replace the dummy key in the translate script with your proper FULL key: "translate": "nexus-localize translate --key FULL-XXXXXXXXXXXXXXXXXXXXXXXXXXXX"

2. Update your team name and project info in the src/locales/project.json

3. Then you can run the translate script to deliver your en-US language file to the LanguageWire service for translation.

Folder Structure Conventions

├── /e2e                             # E2E directory
│   ├── /config                      # Configuration for account credentials       
│   ├── /pages                       # Encapsulates each page related operations
│   ├── /testcase                    # Contains each page E2E test cases 
│   │   ├── global-setup.ts          # A global setup to set something up once before running all tests
│   ├── /testdata                    # Contains E2E test data   
│   └── /utils                       # Contains utility function for e2e testing 
│   │   ├── commonUtils.ts           
├── /public                          
│   ├── favicon.ico                  # Contains application icon
│   ├── index.html                   # The entry html page which loads single page application
│   ├── manifest.json                # Provides metadata used when your web app is installed on a user's mobile device or desktop
│   ├── robots.txt                   # Manages crawler traffic
│   └── staticwebapp.config.json     # Configuration for Azure Static Web Apps, https://learn.microsoft.com/en-us/azure/static-web-apps/configuration
├── /src
│   ├── /assets                      # Contains top-level CSS, images, and font files     
│   ├── /components                  # Contains reusable, common components throughout    
│   ├── /config                      # Contains configuration for your application
│   │   ├── index.ts                 # A ts variable configuration mapped to `.env.development`
│   ├── /hooks                       # Contains every single custom hook in your entire project         
│   ├── /layout                      # Contains application general page layout         
│   ├── /locales                     # Contains application localization related files
│   │   ├── de-DE.json               # German English localization resource file       
│   │   ├── en-GB.json               # UK English localization resource file
│   │   ├── en-US.json               # US English localization resource file
│   │   ├── fr-FR.json               # French localization resource file
│   │   ├── index.ts                 
│   │   ├── it-IT.json               # Italian localization resource file
│   │   ├── project.json             # Credentials used to deliver your language resource file to LanguageWire for human translation services
│   ├── /pages                       # Contains application pages
│   ├── /redux                       # Contains redux related files
│   │   ├── /migration               # Contains migration logic from existed redux structure to new redux structure    
│   │   ├── /reducers                # A combination of every single reducer     
│   │   ├── /slices                  # Contains each slices which automatically generates action creators and action types corresponding to reducers and states              
│   ├── /router                      # Contains react router related operations
│   │   ├── GlobalHistory.tsx        # Export a global navigate, which could be used outside of component
│   ├── /types                       # Contains typescript type declarations
│   ├── /utils                       # Contains utility methods used in the project
│   │   ├── handleException.ts       # Exception handle related logic
│   ├── App.tsx                      # Contains top-level global context and layout
│   ├── AppInsights.ts               # Contains the setup of Application Insights
│   ├── i18n.ts                      # Contains the setup of react-i18next configuration
│   ├── index.tsx                    # Renders the root "entry point" of the application
│   ├── jest.mock.ts                 # A global mock before before running all tests
│   ├── react-app-env.d.ts
│   ├── reportWebVitals.ts
│   └── setupTests.ts                # Unit test setup
├── .env.development                 # Configuration for development environment
├── .eslintignore                    # Eslint ignore file
├── .eslintrc.json                   # Eslint configuration file
├── .gitignore                       # Git ignore file
├── .prettierignore                  # Prettier ignore file
├── package.json                     # package json file
├── playwright.config.ts             # Configuration for playwright
├── README.md                        # Readme file for project
└── tsconfig.json                    # The typescript configuration

FAQ

N/A