@axa-ch/create-pod-app

Create POD App for Patterns Library

This is used to easily setup a new pod.

A pod is a micro frontend for https://axa.ch/, that are usually being implemented and maintained by pod development teams. This scaffolding application makes sure that a team can start developing their SPA (Single Page Application) right away.

Please read the following steps carefully before try it!

Checklist for POD Devs

⚠ WARNING

The implementation of how PODs are integrated into axa.ch pages and processed by the Webhub CI/CD pipeline will be completely revised in 2023. The gist of the revision is that PODs will be enabled to bring their own browser-ready JavaScript bundle, and the current final bundling step in the Webhub CI/CD pipeline will be removed. As a consequence the build/bundling step of a POD will also need to be revised in the future. This means that new PODs that were set up using the current version of create-pod-add will need a one-time update of their build process once the Webhub revision is rolled out. We currently do not foresee further sourcecode changes for POD developers due to that revision, merely changes to the build.

NPM

• react >= 16.3 compatible or native JS
• Npm depedencies and devDependencies must be used correctly (devDependcy will not be installed in Midgard)
• Never add SSH or direct GitHub dependencies in your POD's package.json. This might brake AEM build
• Community based NPM Modules that export as ES6 wont work out of the box on IE11. Midgard does not convert all NPM modules as it would be too risky. If you really need to use ES6 exported NPM Modules, you must adapt your build export so that it bundles those modules into your build export or make a copy and transpile it in your export. In some rare cases, we can add a ES Module library to Midgard so that Midgard takes care of the transpilation.
• No package.json dependencies to git repos! Always and only install from npm

JS

• No direct access to Session Storage. Use bifrost store
• No DOM mutations outside the root component
• No HTML5 History API Based router. Only Hash routing is allowed
• Always use #, including for query parameters! So if you have a deeplink functionality for example, use hash due to caching issues
• A POD can be as height as it wants to be and ideally should be wrapped inside <axa-container>. See here

CSS

• No external font-faces may be loaded from the CSS via @import url("myfont.woff"), only base64 inline-converted fonts are acceptable. Style-guide fonts must be removed as they are already provided from the AEM build.
• CSS selectors must follow the pattern: .o-pod-MYPODNAME .myClassXYZ. Note that the root (<article>) tag generated for any UI-containing POD already has class="o-pod-MYPODNAME ...". By using this pattern for all selectors, your POD's CSS selectors are not just scoped to your application, but also have at least specificity (0,2,0), as you can check here. Thus, they will win over generic page-wide CSS rules that typically have only specificity (0,1,0), such as *:first-child etc.
• Do not override Pattern-Library classes
• Avoid overflow:auto on the root tag
• No position:fixed.
• No position:absolute without setting position:relative to the root tag of your application

Bundling

• Please publish npm-shrinkwrap.json to your npm package to avoid problems installing unwanted sub-dependencies at webhub build midgard
• No External npm modules in the bundled file (This is only relevant if you DON'T use create-pod-app)
• We have to stick to core-js Version 2 because a lot of packages have not done the migration yet and having 2 breaking versions on axa.ch is very dangerous.
• Bundled or just plain Babel transpiled ES modules are ok (This is only relevant if you DON'T use create-pod-app)
• Assets must be hosted from the POD Developers OR added in the POD as Base64. The create-pod-app build is already set for this.
• Ideally, CSS and JS should be bundled starting from the root component.
• PODs must always release accordingly to semver

Forbidden NPM repos

• react-intl in version 2.x.x
• react-select-search in all versions
• react-compound-slider in all versions
• rollup-plugin-react-svg needs special care in your rollup build. Add this extensions: ['js', 'jsx', 'svg'], in the babel plugin as option (babel({...}),)
• Recoil in all versions

Best Practices

• We do not reccomend the usage of react-intl due to its bad export support. Better use i18next
• As an inspiration, have a look at our Team Best Practices. It might helps you.

Step by Step guide

• Create a git repository (without a .npmignore file).
• Check out the master branch of the newly created repo and make sure you don't add any changes.
• Install the create-pod-app script via npm install @axa-ch/create-pod-app -g. VERY IMPORTANT to use the -g ⚡ flag.
• Log into npm (make sure your account is in the axa-ch NPM org ⚡) npm login.
• Run the interactive script via create-pod-app inside the root folder of your repo. This will create the entire environment for your pod. More details in the CLI.

How to work in your newly create pod

• run npm run start to start a local dev server and compiles the src (and copies your POD properties to the index.html)
• run npm run build to produce the ES Module exports
• run npm run release to release to npm
• run npm run test to test your code. There is a dummy test already in place as example
• run npm run copy-podproperties-to-indexhtml to copy POD properties to your index.html if you have changed the POD properties. This step is included in npm run start. This copy mechanism is not exactly the same as on the live stage (see midgard documentation for details).
• run npm run alt-release to release an alternative pod version to npm. For further information take a look at the README in your pod after the creation.

Final informations

This repo creates a pod and configures your git repo. It also automatically sets all requirements for Midgard so that the integration happens "under the hood".

You only have to remember the POD type. This is needed for the manifest in Midgard: https://github.com/axa-ch/midgard/blob/develop/config.json and AEM: https://github.com/axa-ch/aem-all/blob/develop/hub-clientlibs/manifest.json

It contains a ES Module export and a "state of the art" DEV environment. It also has the release script for PODs set and ready to be used. Finally, it contains the SCSS in JavaScript build settings and Midgard will add vendor prefix and will take care of minification.

Check also Midgards Readme: https://github.com/axa-ch/midgard#midgard