Create Localised Site

This CLI is used to generate administrative react projects for Localised. The administrative react project that is generated by this CLI was initially generated by create-react-app and therefore has the same features and setup. For more information on create-react-app please visit their documentation. The projects implements Key Cloak authentication, React Router routing as well as the Backpack component library employing the Shell and ThemeProvider components. Additionally the project borrows a lot of its setup from the project ignition-ui which also was generated by create-react-app.

Usage

To initiate the command line run:

npx @localised/create-localised-site

You will be asked the following questions:

1. What is your App Name? (Must be a valid name for a directory)

This is used for the name of the file folder of the project as well as in the package.json as the applications name. The default is my-app.

2. What is your App's Display Name? (Shown in the App's title bar)

This is used is title bar in the browser and in the header. This defaults to My App.

3. What is the Key Cloak application name? (Must be valid Keycloak name)

This is used for configuring KeyCloak with the key for the application name. This defaults to ignition-web.

4. What is the Key Cloak role key? (User role used for resource access)

This is used for configuring KeyCloak checking the authenticated user role. This defaults to ignition-access.

Generated Project Layout

public

https://create-react-app.dev/docs/using-the-public-folder/

src/components/Loading

Displayed during initial render of the application.

src/components/LoginError

Displayed if authentication through Key Cloak errors.

src/components/Scaffold

Used to wrap the applications content with a sidebar and header whom contain route links, logo, application title and logout button. Implements Backpack Shell component, useShell hook and imports routes from the router.

src/components/Theme

Implements Backpack's ThemeProvider that styles Backpack components in the application using the themeConfig in fixtures.js. Implements dark mode and light mode using the context api that toggles settings in the ThemeProvider and sets the bodies background color depending on the mode. To switch the theme use the useThemeMode hook which exports the mode and the toggleTheme function.

src/envs

Contains application enviroment variables used for production, staging, test such as for Key Cloak configuration.

src/fonts

Contains application fonts.

src/hooks/useShell.js

Generates properties to power the Scaffold including the currently selectedNavOption in the sidebar and routeHeaders to display in the header such as the App Title.

src/hooks/useThemeMode.js

Exports current mode as either light or dark and provides toggleTheme function. Used in conjunction with <Theme/> component.

src/routes/index.js

Implements react-router and renders routes config defined in routes.js.

src/routes/routes.js

Each route uses schema:

{
  path: `/`, // Route path pattern to render the route
  exact: true, // Whether the pattern of the path exactly or overlaps with similar paths
  component: Home, // Component the the route renders
  header: [
    {
      component: () => <HeaderComonent /> // componet displayed in the header of the Shell
      position: `left` // positions of `left`, `middle`, `bottom`
    }
  ],
  // Siderbar configuration object imported into backpack shell
  // Route is hidden from sidebar if property is not defined
  sidebar: { 
    tooltip: `Home`, // tooltip string of SidebarLink
    icon: `home`, // icon string of SidebarLink defined in https://fonts.google.com/icons
    position: `top`, // positions  of `top`, `middle`, `bottom`
  },
  props: {
    // properties added to component <Home {...props} />
  }
},

src/styles

Contains global style files with css variables including theme variables (custom-properties.css), browser styling reset (reset.css), and site typographytypography.css.

src/utils/authentication.js

Script for instantiating keycloak with functions such as init() to being authentication process and logout() to log user back to authentication process. The Instance of Auth is on the window object accessed as window.auth.

index.js

Root of the application which handles authentication, wraps application in theme and imports global css and renders router.