Nosferatu's Pace Maker

    @angular-component/router
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.1 • Public • Published

    Angular Component Router

    npm version

    All Contributors

    A declarative router for Angular applications.

    Install

    Use your package manager of choice to install the package.

    npm install @angular-component/router

    OR

    yarn add @angular-component/router

    Installation with ng add

    You can use ng add to install the package by using the command below.

    ng add @angular-component/router

    The above command will install the package, and add the ComponentRouterModule import in the AppModule.

    Usage

    To register the Router, add the ComponentRouterModule.forRoot() to your AppModule imports.

    import { ComponentRouterModule } from '@angular-component/router';
    
    @NgModule({
      imports: [
        // ... other imports
        ComponentRouterModule.forRoot(),
      ],
    })
    export class AppModule {}

    Or in a feature module

    import { ComponentRouterModule } from '@angular-component/router';
    
    @NgModule({
      imports: [
        // ... other imports
        ComponentRouterModule,
      ],
    })
    export class FeatureModule {}

    After your components are registered, use the Router and Route components to register some routes.

    <router>
      <!-- For nested routes use exact: false -->
      <route path="/blog" [exact]="false">
        <app-blog *routeComponent></app-blog>
      </route>
      <route path="/posts/:postId">
        <app-post *routeComponent></app-post>
      </route>
      <route path="/about">
        <app-about *routeComponent></app-about>
      </route>
      <route path="/" redirectTo="/blog"> </route>
      <route path="/" [exact]="false">
        <app-page-not-found *routeComponent></app-page-not-found>
      </route>
    </router>

    Route sorting

    Angular routing is sorting the routes upon registration, based on priority. The order in which the routes are defined in your template is therefore not important.

    The following two examples will give the same results

    <router>
      <route path="/blog" [exact]="false">
        <app-blog *routeComponent></app-blog>
      </route>
      <route path="/" redirectTo="/blog"></route>
      <route path="/" [exact]="false">
        <app-page-not-found *routeComponent></app-page-not-found>
      </route>
    </router>

    and

    <router>
      <route path="/" [exact]="false">
        <app-page-not-found *routeComponent></app-page-not-found>
      </route>
      <route path="/" redirectTo="/blog"></route>
      <route path="/blog" [exact]="false">
        <app-blog *routeComponent></app-blog>
      </route>
    </router>

    The sorting algorithm has only a few rules (ordered by importance):

    • Named routes (e.g. /blog) have priority over root route (/)
    • Static routes (e.g. /blog/view) have priority over parametrized (e.g. /blog/:id)
    • Exact route (with exact set to true or omitted) has priority over non-exact (with exact set to false)
    • Longer paths have priority over shorter

    Route restrictions

    Implementing the route restriction is as simple as adding a structural directive on a route component

    <router>
      <route path="/admin" *ngIf="user.isAuthenticated$ | async">
        <app-admin *routeComponent></app-admin>
      </route>
      <route path="/admin" *ngIf="!(user.isAuthenticated$ | async)">
        <app-login *routeComponent></app-login>
      </route>
    </router>

    The restriction doesn't stop the navigation. It simply removes the route from the configuration so the next eligible route will pick it up.

    Navigating with Links

    Use the linkTo directive with a full or relative path to register links handled by the router.

    <a linkTo="/">Home</a>
    <a linkTo="/about">About</a>
    <a linkTo="/blog">Blog</a>
    <a linkTo="../other"></a>

    Adding classes to active links

    To add classes to links that match the current URL path, use the linkActive directive.

    <a linkTo="/" linkActive="active">Home</a>
    <a linkTo="/about" linkActive="active">About</a>
    <a linkTo="/blog" linkActive="active" [activeOptions]="{ exact: false }"
      >Blog</a
    >

    Using the Router service

    To navigate from a component class, or get global route information, such as the current URL, or hash fragment, inject the Router service.

    import { Component } from '@angular/core';
    import { Router } from '@angular-component/router';
    
    @Component({...})
    export class MyComponent {
      constructor(private router: Router) {}
    
      ngOnInit() {
        this.router.url$.subscribe();
        this.router.hash$.subscribe();
      }
    
      goHome() {
        this.router.go('/');
      }
    
      goForward() {
        this.router.forward();
      }
    
      goBack() {
        this.router.back();
      }
    }

    Using Route Params

    To get the route params, inject the RouteParams observable. Provide a type for the shape of the route params object.

    import { Component } from '@angular/core';
    import { RouteParams } from '@angular-component/router';
    
    @Component({...})
    export class MyComponent {
      constructor(
        private routeParams$: RouteParams<{ postId: string }>
      ) {}
    
      ngOnInit() {
        this.routeParams$.subscribe(console.log);
      }
    }

    Using Query Params

    To get the route params, inject the QueryParams observable. Provide a type for the shape of the query params object.

    import { Component } from '@angular/core';
    import { QueryParams } from '@angular-component/router';
    
    @Component({...})
    export class MyComponent {
      constructor(
        private queryParams$: QueryParams<{ debug: boolean }>
      ) {}
    
      ngOnInit() {
        this.queryParams$.subscribe(console.log);
      }
    }

    Lazy Loading Modules

    To lazy load a module, use the load binding on the route component.

    import { Component } from '@angular/core';
    
    @Component({
      template: `
        <router>
          <route path="/lazy" [exact]="false" [load]="modules.lazy"> </route>
        </router>
      `,
    })
    export class MyComponent {
      modules = {
        lazy: () => import('./lazy/lazy.module').then((m) => m.LazyModule),
      };
    }

    Register a component to register the child routes.

    import { Component } from '@angular/core';
    
    @Component({
      template: `
        <router>
          <route path="/">
            <app-lazy *routeComponent></app-lazy>
          </route>
          <route path="/" [exact]="false" redirectTo="/404"> </route>
        </router>
      `,
    })
    export class LazyRouteComponent {}

    Implement the ModuleWithRoute interface for the route component to render after the module is loaded.

    import { NgModule } from '@angular/core';
    import { ModuleWithRoute } from '@angular-component/router';
    
    @NgModule({
      declarations: [LazyRouteComponent, LazyComponent],
    })
    export class LazyModule implements ModuleWithRoute {
      routeComponent = LazyRouteComponent;
    }

    Lazy Loading Components

    To lazy load a component, use the load binding on the route component.

    import { Component } from '@angular/core';
    
    @Component({
      template: `
        <router>
          <route path="/lazy" [load]="components.lazy"> </route>
        </router>
      `,
    })
    export class MyComponent {
      components = {
        lazy: () => import('./lazy/lazy.component').then((m) => m.LazyComponent),
      };
    }

    Contributors

    Thanks goes to these wonderful people (emoji key):


    Brandon

    💻 📖 ⚠️

    Miroslav Jonaš

    💻 📖 ⚠️

    Santosh Yadav

    💻 📖

    Kyle Cannon

    💻

    This project follows the all-contributors specification. Contributions of any kind welcome!

    Install

    npm i @angular-component/router

    DownloadsWeekly Downloads

    13

    Version

    0.4.1

    License

    MIT

    Unpacked Size

    480 kB

    Total Files

    96

    Last publish

    Collaborators

    • brandonroberts