# angular-elements-router

> A libary to enable the usage of the router module within Angular projects defining custom elements

Latest version **0.0.7** (published 2020-11-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install angular-elements-router
pnpm add angular-elements-router
yarn add angular-elements-router
bun add angular-elements-router
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.7 |
| Published | 2020-11-08 |
| First published | 2020-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 186 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 34 |
| Author | Fabian Böller |
| Maintainers | fboeller |
| Keywords | angular, router, routing, web-components, custom-elements, angular-elements, micro-frontends |

## Links

- npm: https://www.npmjs.com/package/angular-elements-router
- Repository: https://github.com/fboeller/angular-elements-router
- Homepage: https://github.com/fboeller/angular-elements-router#readme
- Issues: https://github.com/fboeller/angular-elements-router/issues
- npm.io page: https://npm.io/package/angular-elements-router

## Dependencies (1)

- [tslib](https://npm.io/package/tslib.md) ^2.0.0

## Alternatives

- [express-promise-router](https://npm.io/package/express-promise-router.md) — 736.1K weekly downloads
- [next-usequerystate](https://npm.io/package/next-usequerystate.md) — 29.8K weekly downloads
- [@bitkyc08/opencodex](https://npm.io/package/@bitkyc08/opencodex.md) — 4.6K weekly downloads
- [lynkr](https://npm.io/package/lynkr.md) — 575 weekly downloads
- [baremetal.js](https://npm.io/package/baremetal.js.md) — 42 weekly downloads

## Recent versions

- 0.0.7 (latest) — 2020-11-08
- 0.0.6 — 2020-11-08
- 0.0.5 — 2020-11-08
- 0.0.1 — 2020-11-08
- 0.0.3 — 2020-11-07
- 0.0.2 — 2020-11-07

## README

# Angular Elements Router

![License](https://img.shields.io/github/license/fboeller/angular-elements-router) ![Build](https://img.shields.io/github/workflow/status/fboeller/angular-elements-router/CI) ![Version](https://img.shields.io/npm/v/angular-elements-router)

The angular elements router is a libary for using the Angular Router within Angular Elements.

- **Lazy loading** — The bundle is loaded when the route of the micro frontend is activated.

- **Non-intrusive** — Use only the features you need, easy opt-out once Angular starts supporting the router in Angular Elements out of the box.

- **No dependencies** — Besides Angular this library does not include any dependencies.

## Installation

```
$ npm install --save angular-elements-router
```

## Prerequisites

You have an Angular application that acts as a [platform](./projects/example-platform) and an Angular application that acts as a [micro frontend](./projects/example-micro-frontend).
A build of the micro frontend results in a single build that registers custom elements on loading.

## Usage

### Create a host component

To be able to reference your custom element in the routes, you need to create a host component.
You can use the `aerRouting` on the custom element to pass route changes to the micro frontend and to allow the micro frontend to pass route changes to the platform.

```typescript
import { Component } from "@angular/core";

@Component({
  selector: "app-host",
  template: `<mf-entry aerRouting></mf-entry>`,
})
export class MicroFrontendHostComponent {}
```

### Create a host module

To lazy load your custom element, you need to create a host module in the platform.
Import `AngularElementsRouterModule` to be able to use the `aerRouting` directive.
Use the schema `CUSTOM_ELEMENTS_SCHEMA` to make Angular accept the custom element in the host component.
Use the path `**` to pass all sub paths to the custom element.

```typescript
import { AngularElementsRouterModule } from "angular-elements-router";
import { MicroFrontendHostComponent } from "./micro-frontend-host.component";

const routes: Routes = [
  {
    path: "**",
    component: MicroFrontendHostComponent,
  },
];

@NgModule({
  declarations: [MicroFrontendHostComponent],
  imports: [RouterModule.forChild(routes), AngularElementsRouterModule],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class MicroFrontendHostModule {}
```

### Bind the micro frontend to a route

Choose a route under which your micro frontend should be loaded.
Use the `LoadBundleGuard` to load the bundle of your micro frontend on the first activation of the route.

```typescript
import { LoadBundleGuard } from "angular-elements-router";

const routes: Routes = [
  {
    path: "micro-frontend",
    canActivate: [LoadBundleGuard],
    data: {
      bundleUrl: "http://localhost:4201/main.js",
    },
    loadChildren: () =>
      import("./micro-frontend-host/micro-frontend-host.module").then(
        (m) => m.MicroFrontendHostModule
      ),
  },
];
```

### Register routing in the micro frontend

Use the `EntryRoutingService` in the Angular component representing the custom element.
This way, route changes are passed to the Angular router in the micro frontend and in the other direction to the platform.

```typescript
import { EntryRoutingService } from 'angular-elements-router';

@Component({
  selector: 'mf-angular-entry',
  template: `<router-outlet></router-outlet>`,
})
export class EntryComponent implements OnChanges, OnDestroy {
  @Input() route?: string;
  @Output() routeChange = new EventEmitter<string>();

  route$ = new Subject<string | undefined>;
  private destroyed$ = new Subject<void>();

  constructor(private entryRoutingService: EntryRoutingService) {
    this.entryRoutingService.registerRouting(this.routeChange, this.route$, this.destroyed$);
  }

  ngOnDestroy() {
    this.destroyed$.next();
  }

  ngOnChanges() {
    this.route$.next(this.route);
  }
```

### Create a custom element from the entry component

The module in your micro frontend needs to define the custom element in the browser on bootstrap of the module.

```typescript
import { EntryComponent } from "./entry.component";
import { createCustomElement } from "@angular/elements";

@NgModule({
  declarations: [EntryComponent],
  imports: [BrowserModule],
  providers: [],
})
export class AppModule {
  constructor(private injector: Injector) {}

  ngDoBootstrap() {
    const customElement = createCustomElement(EntryComponent, {
      injector: this.injector,
    });
    window.customElements.define("mf-entry", customElement);
  }
}
```

### Define the /root route in the micro frontend

To resolve the ambiguity of '/' within the micro frontend, you can reserve `/root` to reference the root of the platform and `/` to reference the root of the micro frontend.
This way, you can navigate to links outside of the micro frontend from within the micro frontend.

```typescript
import { NoComponent } from "angular-elements-router";

const routes: Routes = [
  { path: "root", children: [{ path: "**", component: NoComponent }] },
  ...otherRoutes,
];
```

### Prevent direct access to the browser url

By default, the Angular router within the micro frontend tries to update the browser url.
Use the `NoopLocationStrategy` to prevent this, such that the platform has the only access.

```typescript
import { NoopLocationStrategy } from "angular-elements-router";

@NgModule({
  imports: [RouterModule.forRoot(routes)],
  providers: [{ provide: LocationStrategy, useClass: NoopLocationStrategy }],
  exports: [RouterModule],
})
export class AppRoutingModule {}
```

### Setup a dev platform within the micro frontend

For the independent development of the micro frontend, a minimal dev platform consisting of an index.html with some Javascript can be of advantage.
This dev platform can be used both locally and also be deployed and used together with the bundle.

To use it, include the `dev-platform.js` in the scripts of your micro frontend in the `angular.json`.

```json
{
"build": {
  "builder": "ngx-build-plus:build",
  "options": {
    "singleBundle": true,
    "outputHashing": "none",
    ...,
    "scripts": [
      "node_modules/angular-elements-router/src/dev-platform.js"
    ]
  },
}
```

Setup an `index.html` in the micro frontend app.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Example Micro Frontend</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
    <script src="scripts.js"></script>
  </head>
  <body>
    <button onclick="router.changeRoute('/root')">
      Go to platform main page
    </button>
    <button onclick="router.changeRoute('/')">
      Go to micro frontend main page
    </button>
    <div id="router-outlet"></div>
    <script>
      const router = registerRouting("/micro-frontend", "mf-entry");
    </script>
  </body>
</html>
```

---
_Source: https://npm.io/package/angular-elements-router · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._