Skip to content

Latest commit

 

History

History
240 lines (210 loc) · 14.2 KB

README.md

File metadata and controls

240 lines (210 loc) · 14.2 KB

fe-service-desktop-app-template

This repository is a template for service desktop apps. When a new app needs to be added, use this template to generate the repository.

AUTOMATED SET UP

Currently, fe-customer-desktop and fe-worker-desktop has a script which will automatize the set-up of the new app. You will just need to run:

npm run add-app

This will require some questions: the app name, port number (either autogenerated or manually entered), ticket number to set up and if you want to use the GitHub Cli to create the PRs at the end of the script.

Please see more on these links:

  • Customer Desktop: here.
  • Worker Desktop: here.

Creating a new Application

IMPORTANT: WHEN ADDING A NEW APP, PLEASE CREATE A DEVOPS TICKET FOR THE CREATION OF A NEW BUILD PIPELINE. FAILURE TO DO THIS WILL BREAK THE APPLICATION.

IMPORTANT: This template is for multiple desktops, to it should change the name of the app according to the desktop. Current desktops:

IMPORTANT: Please follow the instructions according to the desktop the app should be located.

  1. Create a DevOps ticket to create a new repository based on this template. The repository name should follow the usual pattern: fe-service-desktop-[APPNAME], fe-customer-desktop-[APPNAME] or fe-worker-desktop-[APPNAME]. DevOps should know to use the template for the repository, but it may be a good idea to mention it in the ticket just in case.

  2. Locate everywhere it says "sample" to your [APPNAME]. You will find all these locations here:

    1. ./package.json. Update name and description.
    2. ./webpack.common.js. Update ModuleFederationPlugin references and output.
    3. ./webpack.dev.js. Change the port to a unique port number. You can see what port isn't taken by looking at the Applications table below.
    4. ./webpack.prod.js. Update appName in S3BuildArtifactWebpackPlugin plugin instances (both of them) to be the name of your app (without fe-service-desktop, fe-customer-desktop or fe-worker-desktop)
    5. ./webpack.hotfix.js. Update appName in S3BuildArtifactWebpackPlugin plugin instances to be the name of your app (without fe-service-desktop, fe-customer-desktop or fe-worker-desktop)
    6. ./jest.config.js. Update Sample in coveragePathIgnorePatterns.
    7. ./src/XXXXX.tsx. Rename the main component that gets exported.
      1. Update SampleApp on the Material UI method createGenerateClassName.
      2. Update sample-app on the ErrorBoundary (If you use it)
      3. Update sample-app on the ConfigProvider (If you use it)
    8. ./src/bootstrap.tsx. Update the references to new component.
  3. Update the following files in core with your application.

    1. Add your app to the ModuleFederationPlugin > remotes on the file ./core/webpack.common.js
    2. Import your file and register your application with registerApplication() in the file ./core/src/index (this is only if the app will be a page, not for small MF will be inside other MF). Also add your app to applicationsEnum. See 6.3 & 6.4 for setup of app flags.
    3. Add your app to ./app.json or apps.json copying the format from the other apps.
  4. Adding a new port to host you app

    1. Check a unique port number to use in the core documentation to use in your app and add a new row in the documentation table with your app name, port number and repository url
      • Service Desktop wiki
      • Customer Desktop wiki
      • Worker Desktop wiki
    2. Add new port number in your app object on the core apps (step 3.iii) on the local key
    3. Add you port number on your projects ./webpack.dev.js
  5. Add configs for git - We clone and ignore your module to allow for local building

    1. Add your sub-project to the .gitignore file on core

      • Service Desktop (NO NEEDED FOR SERVICE DESKTOP) .gitignore
      • Customer Desktop (NO NEEDED FOR CUSTOMER DESKTOP) .gitignore
      • Worker Desktop (NO NEEDED FOR WORKER DESKTOP) .gitignore
    2. Add your sub-project name and git clone command on the Makefile on core

      1. Add your app to the following ./Makefile script: make install
      2. Add your app to the following ./Makefile script: make copy-core-defs
        • (NO NEEDED FOR SERVICE DESKTOP)
  6. Languages, Constants and Feature flags. Run on configs project npm run add-apps and follow the questions. Otherwise, add it manually

    1. Add your App configs
    2. Instructions will be in that repo.
    3. Add your app to the core config in all apps and partners. Set flag to false for all environments except dev while developing app. This is still a manual process.
    4. Add your app to the Apps interface.
  7. run npm run start from the project root:

    1. Host the entire app by browsing to your path to verify your app is being imported correctly in the following hosts.
      • Service Desktop https://localhost:8080/
      • Customer Desktop https://localhost:9000/
      • Worker Desktop https://localhost:7000/
    2. You can also open your new app with the port defined for the app (your unique port)
      • Service Desktop Ex. http://localhost:8084/
      • Customer Desktop Ex. http://localhost:9002/
      • Worker Desktop Ex. http://localhost:7002/
  8. Add your app details into this README.md for other developers 🙂

    • Add new app details to the Service Desktop App models in token-interceptor project
      • Service Desktop app on ./src/modules/serviceDesktop.ts.
      • Customer Desktop app on ./src/modules/customerDesktop.ts.
      • Worker Desktop app on ./src/modules/workerDesktop.ts.
  9. Update ./src/core/defs.d.ts file on your apps from the latest on core

  10. ONLY CUSTOMER DESKTOP - Pass i18next instance from core to the props of the ConfigProvider of @swipejobs/react-hook on you file ./src/XXXXX.tsx.

        <ConfigProvider app="sample-app" i18next={i18next}>
            {...}
        </ConfigProvider>
  11. ONLY CUSTOMER DESKTOP AND WORKER DESKTOP - Use the main share components on the library @swipejobs/fe-core-elements (You will need to do npm i @swipejobs/fe-core-elements)

    1. Use the ErrorBoundary on @swipejobs/fe-core-elements. Then remove the local './src/components/ErrorBoundary' and test on './src/components/** tests**'.
    2. Use the share wrapper on the view PageViewContainer on @swipejobs/fe-core-elements. This should be used as the first wrapper './src/components/SampleComponent.tsx.
  12. ONLY CUSTOMER DESKTOP AND WORKER DESKTOP - Use the local create theme method from @swipejobs/react-hook to handle different languages. Import on the file ./src/XXXXX.tsx the method useLocaleTheme and use the method createLocaleTheme inside to create the theme.

    import { ConfigProvider, useLocaleTheme } from '@swipejobs/react-hooks';
    
    const Sample: React.FC<CoreProps<ConfigData, FlagsData, LangData>> = (props) => {
        const { singleSpa, muiTheme, i18next } = props;
        const { createLocaleTheme } = useLocaleTheme({ i18next });
    
        const theme = createLocaleTheme(muiTheme);
    
        return (
            <ThemeProvider theme={theme}>
                {...}
            </ThemeProvider>
        );
    }
  13. ONLY CUSTOMER DESKTOP AND WORKER DESKTOP - If you want to use the module @swipejobs/permissions-conditional to check the permissions. You will need to use the version 2.

    1. Add the PermissionsProvider on ./src/XXXXX.tsx . doc
        import React from 'react';
    
        const Sample: React.FC<CoreProps<ConfigData, FlagsData, LangData>> = (props) => {
            const { singleSpa, muiTheme, i18next } = props;
    
            return (
                <PermissionsProvider desktopType={"customer"}>
                  {...}
                </PermissionsProvider>
            );
        }
  14. ONLY CUSTOMER DESKTOP AND WORKER DESKTOP - If you are using a date library as luxon please add it on ./webpack.common.js shared libraries of the ModuleFederationPlugin. This will handle the language changes on the library.

    module.exports = {
      plugins: [
        new ModuleFederationPlugin({
          shared: {
            ...,
            'react-i18next': {
              singleton: true,
            },
            luxon: {
              singleton: true,
              requiredVersion: dependencies.luxon,
            },
            'single-spa': {
              singleton: true,
            },
            ...
          }
        }),
        ...
      ]
    }

About this template

TS

This template uses strict Type Checking. It also uses a webpack plugin that will break the build if TS errors are not resolved. Please fix any TS errors before pushing, or the pipeline will fail.