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
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.
- 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
- 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
hashdue to caching issues
- A POD can be as height as it wants to be and ideally should be wrapped inside
<axa-container>. See here
- 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
- Do not override Pattern-Library classes
- Avoid overflow:auto on the root tag
position:relativeto the root tag of your application
- Please publish npm-shrinkwrap.json to your npm package to avoid problems installing unwanted sub-dependencies at webhub build
- 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-jsVersion 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
- 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 (
- Recoil in all versions
- 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
- Log into npm (make sure your account is in the axa-ch NPM org
- Run the interactive script via
create-pod-appinside 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
npm run startto start a local dev server and compiles the src (and copies your POD properties to the index.html)
npm run buildto produce the ES Module exports
npm run releaseto release to npm
npm run testto test your code. There is a dummy test already in place as example
npm run copy-podproperties-to-indexhtmlto 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).
npm run alt-releaseto release an alternative pod version to npm. For further information take a look at the README in your pod after the creation.
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
Check also Midgards Readme: https://github.com/axa-ch/midgard#midgard