benwinding/ngext

Better routing for Angular

A routing framework for angular inspired by React's next.js.

Introduction

Ngext is a tool which abstracts an angular application and drastically simplifies the routing. It has the following features:

• File-based routing (no more routing modules!)
• All lazy loaded modules generation
• Dynamic configurations (no more static angular.json files)
• Declarative route layouts
• Server-side rendering, (HTML file for each page!)
• Compatible with all your existing angular files @NgModules, @Components, ...etc

Links

• Documentation

Get Started

Install

npm i -g ngext

Usage

Usage: ngext [options] [command]

Options:
  -v, --version      output the version number
  -h, --help         display help for command

Commands:
  new [ProjectName]  Creates a new project
  build              Builds the ngext app
  export             Exports the ngext app with SSR
  dev                Runs the ngext app locally
  help [command]     display help for command

Why use this?

Angular has many elegant abstractions, @Component, @Module, @Injectable. However, the routing in Angular is not a simple abstraction.

In order to add a new page, Angular routing requires that you edit 3 places; add a component file, declare component in a module, and add a route to a routing module.

This project attempts to encapsulate this into a single abstraction @PageComponent, which contains the component, dependencies and the route path which is generated from the page location. Making it easier than ever to add new pages to Angular apps.

ngext's Issues

Feature request: option to integrate with an Angular CLI / Nx project

Hey Ben, I just saw this project on Twitter and it looks super interesting. I've been working on a prototype with a very similar goal, with file based routing generating all the repetitive code as needed, but you took it a few steps further!

I like how you added the imports key to the Component directive.

I'm wondering if you have considered trying to implement this using a plugin that could be hooked into a normal Angular CLI (or Nx CLI) workspace, maybe by extending the webpack config or using a custom builder.

I think having the ability to integrate with a common Angular project would be ideal as it leaves folks in a common structure and allows to do things like monorepos.

If it sounds interesting, I'd be happy to talk about collaborating on that effort. In case you're not aware, there is an Angular Community on Discord where you can find me with the same username.

[FR] Implement SSR via Angular Universal

What makes nextjs great is the ability to render all pages of the react app as separate html pages which can be loaded fast and indexed by search engines.

Initially I thought that SSR with Angular Universal was complex and hard to implement, but a few blog posts show that it could be quite easy

• Reference: https://stackoverflow.com/questions/56448676/is-angular-universal-still-a-spa

Initial Plan

• Only SSR with ngext build --ssr or possibly on by default
• Additional build steps:
  1. Generate a small express server
  2. Crawl through every route in the app and SSR render the page on the express server.
  3. Copy output to dist directory

Question: How to do parameterized routes

Thank you for sharing this idea with the world!

How do we create a parameterized page route using ngext?

From pages/README.md:

---

PAGES

This directory contains your application pages.
Each page file is mapped to a url route in your application.

~/pages/page.ts          ->  /page
~/pages/folder/index.ts  ->  /folder
~/pages/folder/page.ts   ->  /folder/page

Compiled routes are found in ~/.ngext/src/routes.ts

How would we do /page/{id}?

Figure out how to Circumvent the Angular Code Analysis

Angular's Compilation Steps

According to angular documentation. There's 3 main steps of compilation:

• Phase 1 is code analysis. In this phase, the TypeScript compiler and AOT collector create a representation of the source. The collector does not attempt to interpret the metadata it collects. It represents the metadata as best it can and records errors when it detects a metadata syntax violation.

• Phase 2 is code generation. In this phase, the compiler's StaticReflector interprets the metadata collected in phase 1, performs additional validation of the metadata, and throws an error if it detects a metadata restriction violation.

• Phase 3 is template type checking. In this optional phase, the Angular template compiler uses the TypeScript compiler to validate the binding expressions in templates. You can enable this phase explicitly by setting the fullTemplateTypeCheck configuration option; see Angular compiler options.

Adding Another Type Of @NgModule

We want to add our own keyword decorator @PageModule which is a new type of @Module.

import { PageModule } from './page';

@PageModule({
  template: `<h1>Welcome</h1>`
})
export class TestPage {}

Problem

The problem is it fails at Phase 1 and throws the error that it's not a known type.

ERROR in : Unexpected value 'TestComponent in /home/ben/projects/ng-ts-transformations/src/app/test.component.ts' 
  declared by the module 'AppModule in /home/ben/projects/ng-ts-transformations/src/app/app.module.ts'. 
  Please add a @Pipe/@Directive/@Component annotation.

Hack Solution

So it turns out we can just stop the error by returning early from the check

But is there a better way to tell the angular compiler - during phase 1: code analysis - that @PageModule is a valid type?

core: decide Component abstraction name and typing

In the documentation there is a reference to @PageComponent while in the generated application and core source code we're using Component instead as in import { Component } from 'ngext'. What would eventually be updated, the documentation or the exported interface name?

Also, shouldn't the Component interface in 'ngnext' extend the Component interface from @angular/core and only add the page components specific metadata (imports, guards..)? While transforming, only the latter would be extracted out to @angular/core abstractions while the others would remain the same (providers, viewProviders...)

Awesome project!