Skip to content

HelixUI with Angular

Jump to bottom
Ryan Johnson edited this page Feb 6, 2020 · 7 revisions

NOTE: I'm not familiar enough with the "correct" way to bring in 3rd party, static assets, so this guide may not contain the best solution, but id does provide a solution.

Installing

Prerequisites

  1. Latest stable NodeJS (for the npm and npx command-line utilities)
  2. helix-ui v0.18.0 or later

Assumptions

(all paths are relative to the root of the project directory)

  1. Your app was bootstrapped via @angular/cli
  2. Vendor assets live in src/assets/vendor/ (coded by 3rd party)

Instructions

1. Install NPM Assets

npm install helix-ui
npm install --save-dev vendor-copy
  • vendor-copy allows you to automatically copy bundled assets to your project after npm install.

2. Configure package.json

2.1 - Modify package.json

Include the following configurations:

{
  "scripts": {
    "postinstall": "vendor-copy"
  },
  "devVendorCopy": [
    {
      "from": "node_modules/helix-ui/node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js",
      "to": "src/assets/vendor/webcomponents-loader.js"
    },
    {
      "from": "node_modules/helix-ui/node_modules/@webcomponents/webcomponentsjs/bundles",
      "to": "src/assets/vendor/bundles"
    },
    {
      "from": "node_modules/helix-ui/dist/css/helix-ui.min.css",
      "to": "src/assets/vendor/helix-ui.min.css"
    }
  ]
}
2.2 - Copy Vendor Assets

Run the following to copy files configured via the vendorCopy configuration, above.

npx vendor-copy

NOTE: You may also want to verify that your postinstall script is working as expected, by running npm install.

3. Consuming Assets in your App

3.1 - Modify src/index.html

Add the following to the bottom of the <head> element:

<link rel="stylesheet" href="assets/vendor/helix-ui.min.css">

<!-- Required for HelixUI to function in older browsers -->
<script src="assets/vendor/webcomponents-loader.js"></script>
3.2 - Modify src/main.ts

Import HelixUI

import HelixUI from 'helix-ui';

Then, change the following:

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.error(err));

to this:

HelixUI.initialize()
  .then(() => platformBrowserDynamic().bootstrapModule(AppModule))
  .catch(err => console.error(err));
3.3 - Modify src/app/app.module.ts

By default, Angular doesn't configure your app to support custom elements and you'll see an error similar to the following.

Angular missing CUSTOM_ELEMENTS_SCHEMA

To correct this issue, add CUSTOM_ELEMENTS_SCHEMA to the list of schemas in src/app/app.module.ts (configures angular to allow 3rd-party custom elements).

import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule
  ],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [ CUSTOM_ELEMENTS_SCHEMA ]
})
export class AppModule { }

Other Notes

TBD...

Clone this wiki locally