This project is part of the new strategy for further development of the current Xena UI.
It is a wrapper project for exposing lazyloaded modules as webcomponents for use in Xena. It allows for developing parts of the Xena UI in Angular and use them in the existing Xena UI as webcomponents with the smallest possible bundle size possible for each view. This is done by making sure that we:
- only load the parts needed for the specific view in Xena and only WHEN needed.
- load the Angular codebase only once.
- combine all modules in one build to ensure we benefit the most from tree-shaking.
It is strongly encouraged to use(and enhance) the Xena Design System for dumb components (button, dropdowns, inputs etc.) - both in Angular components and in the existing Xena UI. This will further shrink the overall bundle size of the page as the same dumb-components can be reused and hence loaded only once.
The following diagram shows how it comes together:
In order to install all packages, you need to have a valid personal access token for your Github profile ready. This is because this project depends on @eg-brs/eg.ng.element which is hosted together with its repo on Github. The personal access token needs only to be able to read packages. When you have it ready, this is how you do:
- Create/Edit your ~/.npmrc (
~
means you home folder, for WindowsC:/Users/XXXXX
) - Add
//npm.pkg.github.com/:_authToken=TOKEN
to the file and replaceTOKEN
with your personal access token.
- Find token / create token in Github (Setting-> Developer settings -> Personal access tokens) https://github.com/settings/tokens
- Under Generate new token select(read:packages Download packages from GitHub Package Registry)
- Run
npm install
- Run
npm start
- Voila!
When you need to create a new component, you need to figure out where to put it. The following questions can help you decide that:
- If it is a smart component, then it should be added as a new module in the Xena.WebComponents repository.
- If it is a dumb component then it should be created as a Stenciljs Component in Xena.DesignSystem repository. Then that component will be usable in both Xena Core UI as well as in Angular components.
Adding a new module to the Xena.WebComponents repository is quite simple. You go to the folder containing the Xena.WebComponents project and type this:
ng g m my-component-name
Afterwards you can easily create a new component under that module like this:
ng g c my-component-name/my-component-name
In your module you can define one (and only one) component to expose as a webcomponent. You do that by defining a conventional property called customElementComponent.
export class MyComponentModule {
customElementComponent: Type<any> = MyComponent;
}
Final step is to add the selector for your component in the main module of Xena.WebComponents. You do that by expanding the lazyConfig in app.module. You can do it like this:
const lazyConfig:: LazyComponentRegistry = {
definitions: [
createDef('sign', () => import('./sign/sign.module').then(m => m.SignModule)),
createDef('my-component', () => import('./my-module/my-module.module').then(m => m.MyModule))
],
....
}
Remark: Your selector will always be prefixed with xwc-
as defined in the lazyConfig.
Run npm start
for a dev server. Navigate to http://localhost:4200/
. The app will automatically reload if you change any of the source files.
Run npm run host
to build a development release and host it locally on http://localhost:8081
.
Change value of XenaWebComponentsUrl
in src/Xena.Web/Web.config
to http://127.0.0.1:8081/{lang}/xena-webcomponents.js
<add key="XenaWebComponentsUrl" value="http://127.0.0.1:8081/{lang}/xena-webcomponents.js" />
Remark: Don't commit these changes
Run ng test
to execute the unit tests.
Run ng test --watch
to watch tests. Will run when files change.
se teset on web http://localhost:9876/
Run ng test --code-coverage
to run tests with coverage. This will also generate the Code Coverage report coverage/index.html
.
(your path)
~/Xena.WebComponents/coverage/webstall/index.html
See advanced options here: https://angular.io/cli/test
- Create a new release of Xena.WebComponents by merging into master branch.
- In the Xena repository update the value of
XenaWebComponentsUrl
insrc/Xena.Web/Web.config
to point to the newest version like:
<add key="XenaWebComponentsUrl" value="https://cdn.jsdelivr.net/npm/@xenabiz/xena-webcomponents@1.0.18/dist/prod/{lang}/xena-webcomponents.js" />
This solution has been added to i18n script! So you wont need to manually run it!
Running npm run i18n
will result in Error: error:0308010C:digital envelope routines::unsupported
error
This is due to our old Angular version and the new Node version (nodejs v17+) isn't compatible.
Fix this by going to Visual Studio Code open a terminal run export NODE_OPTIONS=--openssl-legacy-provider