Below are instructions for adding Orion compatibility to your Angular application. These instructions are intended for projects that were bootstrapped with Angular CLI. They are written from the perspective of a newly generated project, but it should be clear where to add these lines in an existing project. If your project is using a custom Webpack config, see the Vanilla JS demo app and instructions.
The following steps will let you start using Web Components in your Angular application across all supported browsers.
-
Install the necessary packages by running
npm install --save-dev @alaskaairux/ods-button @alaskaairux/orion-design-tokens focus-visible @webcomponents/webcomponentsjs
in a terminal.@alaskaairux/ods-button
is the button component itself.@alaskaairux/orion-design-tokens
andfocus-visible
are required dependencies for tokens and focus styles, respectively.@webcomponents/webcomponentsjs
contains polyfills for browsers that don't support Web Components. -
Add an entry to the build assets (
architect.build.options.assets
) inangular.json
to copy the Web Components polyfills to thedist/webcomponents
folder."assets": [ "src/favicon.ico", "src/assets", { "glob": "**/*.js", "input": "node_modules/@webcomponents/webcomponentsjs", "output": "webcomponents/" } ],
-
Add a reference to
webcomponents-loader.js
in the head ofsrc\index.html
. This will detect whether the user's browser supports Web Components and will polyfill any required features. Make sure you include thedefer
attribute -- conflicting polyfills may prevent the app from loading otherwise.<script src="webcomponents/webcomponents-loader.js" defer></script>
-
Add a file called
webcomponents.ts
in thesrc
directory. You will add any additional Web Component imports here. After you import a component here, you can use it throughout the rest of your application. For now, just importods-button
.import '@alaskaairux/ods-button';
-
Next, update
main.ts
to import the Orion Components once the polyfills have loaded. This guarantees that Web Components are not defined until the browser polyfills are ready.// add this line window.addEventListener('WebComponentsReady', () => { return import('./webcomponents'); });
-
In
app.module.ts
, import and applyCUSTOM_ELEMENTS_SCHEMA
to allow the use of HTML elements with dash case.import { BrowserModule } from '@angular/platform-browser'; import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; // update this line import { AppComponent } from './app.component'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule ], providers: [], bootstrap: [AppComponent], schemas: [ CUSTOM_ELEMENTS_SCHEMA ] // add this line }) export class AppModule { }
-
Now you can use
ods-button
. Add a click handler inapp.component.ts
and reference the component inapp.component.html
.export class AppComponent { handleClick() { alert("I've been clicked!") } }
<ods-button (click)="handleClick()">Hello World</ods-button>
-
In
styles.css
, import the Orion Design Tokens from the npm package. The design tokens need to be available for the component to render.@import '~@alaskaairux/orion-design-tokens/dist/tokens/CSSTokenProperties.css';
This example project uses Sass to integrate with the Orion Web Core Stylesheets. See
styles.scss
in this project for an example. You will need tonpm install @alaskaairux/orion-web-core-style-sheets
for access to the stylesheets. -
Run the application with
npm start
. The button should render and trigger an alert when clicked.
Some additional steps must be taken to get your Angular app working in IE11.
-
Add
ie 11
to thebrowserslist
file. If this is a freshly generated project, you may need to remove thenot IE 9-11
line. -
Set
target
toes5
intsconfig.json
. -
Run the following command in a terminal:
npm install --save-dev @angular-builders/custom-webpack @babel/core @babel/plugin-transform-runtime @babel/preset-env @babel/runtime @types/node babel-loader
. This install the necessary packages to transpile modern Javascript to something IE11 will understand. -
Create the file
custom-webpack.config.js
in the root directory. Set its contents to the following. Sinceods-button
and some of its dependencies are shipped as ES6 modules, we need to compile them to ES5 using babel for legacy browser support.const path = require('path'); module.exports = (config, options) => { config.module.rules.push({ test: /\.js$/, include: [ path.resolve(__dirname, 'node_modules/lit-element'), path.resolve(__dirname, 'node_modules/lit-html'), path.resolve(__dirname, 'node_modules/@alaskaairux') ], use: { loader: 'babel-loader', options: { presets: ['@babel/preset-env'], plugins: [ [ '@babel/plugin-transform-runtime', { "corejs": false, "helpers": false, "regenerator": true, "useESModules": false } ] ] } } }); return config; };
-
Update
angular.json
to use the custom webpack config. Setarchitect.build.builder
to"@angular-builders/custom-webpack:browser"
andarchitect.serve.builder
to"@angular-builders/custom-webpack:dev-server"
. Add the propertycustomWebpackConfig
toarchitect.build.options
and point it at the custom webpack config we created."customWebpackConfig": { "path": "custom-webpack.config.js", "mergeStrategies": { "externals": "replace" } },
You should now be able to run the app in IE11 without errors. Run npm start
in the terminal and view the application in IE11.