Put the knife down and take a green herb, dude. (c) Ruffin Bailey 2001-2021

if you mess around long enough in Angular, you're going to see a module other than RouterModule -- that is, a module that's under your control -- with a static forRoot method. It's about this time that you look up the docs for NgModule and discover that, contrary to your expectations from RouterModule's own forRoot, forRoot isn't a part of all @NgModules. It's just something RouterModule contains whose return value can be used in a module's imports.

What the heck is going on here?

Well, the quick answer is that chances are very good it's because you're lazy loading a module. Lazy loading is when you spare the user from loading all of your code until they ask for it. And they ask for it by trying to access a route that requires it.

That's the when, but that's not the "why" we use forRoot. Why is forRoot used?

Answers are a dime a dozen on the net, and I had a hard time getting it all straight until I ran into a particularly good description in this Angular training book from Rangle.io.

Let's run through the topic with a little help from Rangle quickly.

Different modes of injection

In an example in the Rangle book, we've got an Angular app set up to use two almost identical components -- but one is eagerly loaded (and called EagerComponent) and the other is loading lazily (you got it -- LazyComponent).

Each of the components has a very simple CounterService injected into their constructors. The CounterService manages a trivial state: a counter.

@Injectable()
export class CounterService {
  counter = 0;
}

From in the Angular docs, we learn that when a module is lazy loaded, it creates its own "child" ModuleInjector since the module wasn't around to get hooked up to the original injector. The new injector is created a little like the Object.assign process. If a service was in the root injector, it'll be copied over to the child injector too. But if the child has the same service listed in its definition, the root's version will be replaced with a new one scoped to the child.

That means that, if we don't do anything to anticipate it, the CounterService, a service we expect to be a singleton, will be created twice, and its state won't be shared between the root, or parent, context (the context that includes EagerComponent) and the child (the context which contains LazyComponent).

Here are the scenarios the Rangle Angular 2 training book covers. The results prove, give or take, our claim: Importing a provider in a lazy loading child module creates a second instance of the service with its own state.

Link to Rangle scenario	Lazy module providers	Lazy imports	AppModule imports	`SharedModule` used?	SharedModule providers	Result
First	`[CounterService]`	N/A	N/A	No	N/A	Error
Second	N/A	`SharedModule`	`SharedModule`	Yes	`[CounterService]`	Two injectors, two service instances
Third	N/A	`SharedModule`	`SharedModule .forRoot()`	Yes	None!	Singleton injector for `CounterService`

To round things out, there's also a "Fourth" possibility, though it isn't any more viable possibility than the first.

First: Have CounterService in lazy module only -- no way to get into the eagerly loaded component! Error!
Second: Have CounterService in a shared module that provides providers everywhere it's imported. Duplicate services!
Third: Have CounterService in a shared module that only provides providers via forRoot Happiness
Fourth: Have CounterService in the main app module only, unshared -- no way to import into the lazy module's constructor. Error!

From duplicated to shared services

Let's look a little closer at what had to change to get our lazy loaded module's component to use the same service that was set up in the root injector's when we eagerly loaded our first component.

NOTE: If you'd like to look through what the code looks like, this medium post was nice enough to include a stackblitz with code that exactly matches the examples for the pages in the Rangle book that cover dependency injection that we linked to, above!

You can take a look at the stackblitz here, though we'll run through the high notes here.

And then I've extended that code with more StackBlitzes for different scenarios that can be found here:

With SharedModule from separate injectors, stand-alone routing classes removed

With SharedModule from root injector only

If you review the table, above, there are two changes that needed to be made to go from our Second scenario to our Third, which will brings us from two CounterService instances to one singleton shared service from the root injector [with a reference to the same service in the child injector too]:

You need to pull the CounterService out of the SharedModule's providers (see the "SharedModule providers" column in table) so the service isn't automatically registering with each module's import.
You need to create a forRoot method to, in effect, remedy the loss of the CounterService provider from step 1 when it's imported into the root module.

That is, our root module needs the provider for the CounterService. But our lazy/child module can't know CounterService is a provider or it'll try to create one of its own.

In other words, we create two avenues to import the same SharedModule...

One avenue via forRoot that gives us the ModuleWithProviders.
The other that's is our conventional import, but now with the SharedModule's providers removed! It's, in effect, now a "ModuleWithOUTProviders".

Let's go to the video tape...

Here's SharedModule. Old version on the left, and new version, now with a static forRoot method, on the right...

	SharedModule Second Scenario		SharedModule Third Scenario
1	`import { NgModule } from '@angular/core';`	1	`import { NgModule, ModuleWithProviders } from '@angular/core';`
2	`import { CounterService } from './counter.service';`	2	`import { CounterService } from './counter.service';`
3		3
4	`@NgModule({`	4	`@NgModule({})`
5	`providers: [ CounterService ]`
6	`})`
7	`export class SharedModule {`	5	`export class SharedModule {`
		6	`static forRoot(): ModuleWithProviders {`
		7	`return {`
		8	`ngModule: SharedModule,`
		9	`providers: [CounterService]`
		10	`};`
		11	`}`
8	`}`	12	`}`

Note that the providers section was removed from SharedModule, but it was stealthily moved to the new forRoot method.

Aside: It's interesting to keep in mind a lesson we can learn from this answer at stackoverflow.com:

By convention, the forRoot static method both provides and configures services at the same time. It takes a service configuration object and returns a ModuleWithProviders.

Emphasis there is mine. BY CONVENTION, you use forRoot. What's important is that you're returning a ModuleWithProviders<T>. NgModule.imports takes a strange combination of types, but note that ModuleWithProviders<> is explicitly called out as one:

imports: Array<Type<any> | ModuleWithProviders<{}> | any[]>

As long as you're putting a ModuleWithProviders<T> into the imports array, NgModule doesn't care how you got it. You can use good ole MyModule.AwopBopAhLooWop() if you want to; the name of the function doesn't matter. The name is a convention only, suggested by RouterModule.forRoot which, you guessed it, also returns ModuleWithProviders<T>, where, in this case, returns RouterModule for T.

And then here are the related changes in AppModule, which, as you can see, is only that we no longer import the module directly, but import the module WITH ITS PROVIDERS, which is what ModuleWithProviders<SharedModule> gives us.

This name, ModuleWithProviders, is not a coincidence. You can think of the direct module as a "ModuleWithOUTProviders" -- which isn't really a thing, but is a good mnemonic.

	AppModule Second		AppModule Third
1	`@NgModule({`	1	`@NgModule({`
2	`imports: [`	2	`imports: [`
3	`BrowserModule,`	3	`BrowserModule,`
4	`SharedModule,`	4	`SharedModule.forRoot(),`
5	`RouterModule.forRoot(routes)`	5	`RouterModule.forRoot(routes)`
6	`],`	6	`],`
7	`declarations: [ AppComponent, EagerComponent ],`	7	`declarations: [ AppComponent, EagerComponent ],`
8	`bootstrap: [ AppComponent ]`	8	`bootstrap: [ AppComponent ]`
9	`})`	9	`})`
10	`export class AppModule { }`	10	`export class AppModule { }`
11		11

Here, we get a ModuleWithProviders from forRoot to add to the root module's imports. So it's getting essentially what it was getting before, just after it's been laundered by the forRoot method.

And then, finally, the changes in LazyModule.

This is a trick question.

	LazyModule Second		LazyModule Third
1	`import { NgModule } from '@angular/core';`	1	`import { NgModule } from '@angular/core';`
2	`import { SharedModule } from '../shared/shared.module';`	2	`import { SharedModule } from '../shared/shared.module';`
3	`import { LazyComponent } from './lazy.component';`	3	`import { LazyComponent } from './lazy.component';`
4		4
5	`import { Routes, RouterModule } from '@angular/router';`	5	`import { Routes, RouterModule } from '@angular/router';`
6		6
7	`const routes: Routes = [`	7	`const routes: Routes = [`
8	`{ path: '', component: LazyComponent }`	8	`{ path: '', component: LazyComponent }`
9	`];`	9	`];`
10		10
11	`@NgModule({`	11	`@NgModule({`
12	`imports: [`	12	`imports: [`
13	`SharedModule,`	13	`SharedModule,`
14	`RouterModule.forChild(routes)`	14	`RouterModule.forChild(routes)`
15	`],`	15	`],`
16	`declarations: [LazyComponent]`	16	`declarations: [LazyComponent]`
17	`})`	17	`})`
18	`export class LazyModule {}`	18	`export class LazyModule {}`
19		19

Don't see any changes? That's because there aren't any! Now that there are no providers in the module, the lazy loaded module gets our "ModuleWithOUTProviders" type by default.

That is, as detailed in this StackOverflow answer:

The common pattern to achieve that is not to expose providers directly on the @NgModule declaration but in a static forRoot function (the name is not mandatory, it's a convention)

Next Level Dependancy Injection for Children

So for some reason, this has been one of the more difficult posts I've put together, so I'm going to cut scope a bit. But the next level topics would include a few interesting follow-ons, like...

There is one way to signal that we're intentionally importing the SharedModule withOUT providers: Use forChild. RouterModule does this, for instance, and it's probably responsible for all the third-party forRoot. Why not forChild too?

The CLI also adds RouterModule.forChild(routes) to feature routing modules. This way, Angular knows that the route list is only responsible for providing additional routes and is intended for feature modules. You can use forChild() in multiple modules.
The forRoot() method takes care of the global injector configuration for the Router. The forChild() method has no injector configuration. It uses directives such as RouterOutlet and RouterLink.

That does exactly what you'd expect. If forRoot is ModuleWithProviders, this is a ModuleWithProvider without any providers [sic]!

It would be fun to write two variations of the StackBlitzes, above

One that used forChild and forRoot where we'd change the LazyModule trivially so that it called a new SharedModule.forChild() function instead of importing the SharedModule directly.
Another that used the default SharedModule for the AppModule (the root) and a forChild for the LazyModule to see what trouble you could get in backwards. I can't honestly tell if you would or not. If the default has providers and forChild doesn't, aren't you okay? Or does the providers array in an NgModule have some extra voodoo that means only forRoot works by itself?

And just to make things more complicated, there is yet another way out of this conundrum:

Set the providedIn property of the @Injectable() to "root"....
import { Injectable } from '@angular/core';

@Injectable({
  providedIn: 'root',
})
export class UserService {
}

So that's fun.

The bottom line, however, remains the same. If you don't want lazy-loaded module specific instances of services but want to only use the root version as a singleton everywhere, you have to remove the services from your child modules' provider array and inject them in the root module with something -- convention dictates forRoot -- that returns a ModuleWithProviders.

Get it? A module. With providers. Because in the children, you're just returning the module "without providers" when it's imported. The providers come from the root.

Programming is Hard (c) 1842.

Labels: angular, howto

This is part of a series explaining how to use VueJS to create a transplation-free client-side templating architecture. I'm not claiming this is The Best Way to create a UI, but it's a good thought experiment for minimizing ceremony.

Part 1: VueJS introduction -- Progressive, observables, loops, & ifs
Part 2: Components, Templates Types, and SPAs (unedited)
Part 3: Using Render Functions & HTML Files (to come)

I heard about VueJS a while back on from Shawn Wildermuth guesting on Yet Another Podcast, and figured I'd take a look. The most interesting thing about it was its claim to be a "progressive framework"...

From vuejs.org:

Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. Unlike other monolithic frameworks, Vue is designed from the ground up to be incrementally adoptable. The core library is focused on the view layer only, and is easy to pick up and integrate with other libraries or existing projects. On the other hand, Vue is also perfectly capable of powering sophisticated Single-Page Applications when used in combination with modern tooling and supporting libraries.

Incremental adoption, you say? As in, I could use its templating without any other libraries? RLY? I mean, Vue bills itself to be a pretty mature lib. Heck, you can go full-bore, Babel and JSX with VueJS if you want to. That marks a sort of max progression. Can we find a similarly minimally progressive stack?

Once burned...

Last year, I spent most of my time working on a system that used React, JSX, and MobX using Babel for transpilation. It wasn't a horrible client-side stack, but I've never wasted so much time on build systems since I was new to ant. We updated and debugged with each new release of anything of those three, and it drove me crazy with what Shawn Wildermuth calls the "ceremony" of coding -- all the magic incantations and rituals you have to go through and maintain before working code comes out.

Using transpilation and riding the bleeding edge instead of writing deployable code means everything you do costs you -- let's say -- an extra 10%, and, in the wrong hands, more. Do you really get that time back with transpilation?

Just because everyone else is putting together complex JavaScript build processes (and they are. Projects that don't include "the dev who maintains the build" are becoming few and far between, and that dev is always front and center on interview calls pretending their role is absolutely critical to a project's success), do we have to go full Cranberries? (pro tip: see album title, young'uns)

I don't think so. I'm not against transpilation, if it's well managed. But if I can use a library that doesn't require transpilation, but can still give me a good templating system, I'm curious. Just for fun, let's see if VueJS can keep us transpilation-free.

How progressive is VueJS, exactly?

NOTE: If you already know Vue, stay with me. Skim the balance of this so you know where I'm coming from, and then stop at the end, where I start talking about what's missing. Then tune in next time, for Part 2, where I fill in what's missing & seal the deal.

Let's take the minimal VueJS setup as described in their introductory guide, where we assume zero libraries other than Vue are present.

What's below is the minimal Vue setup from their guide, with just enough changed so that we...

Have something that'll work in a live example
Include a form element to test our binding
Have a button to access our data programmatically (standing in for a call back to the server)
Wait until the DOM has loaded before initializing to begin templating
- If we were using true Vue templates, we wouldn't have to do this. More on that in Part 2.
Some gymnastics to pass JSLint.

Excuse the last. It's an unshakeable addiction.

^{(That said, you should use JSLint too. ;^D)}

/*global Vue, window */
document.addEventListener("DOMContentLoaded", function() {
    "use strict";
    window.app = new Vue({
        el: '#app',
        data: {
            message: 'Hello Vue!'
        },
        methods: {
            report: function () {
                // Note that it's app.property, not app.data.property
                console.log(JSON.stringify(window.app.message, null, "    "));
            }
        }
    });
});

And the HTML needed to match is super simple.

<html>
    <head>
        <title>Look how simple</title>

        <script src="../vue.js"></script>
        <script src="./app.js"></script>
    </head>
    <body>
        <div id="app">
            {{ message }}<br />

            <input
                type="text"
                v-model="message"
            /><br />

            <button
                type="button"
                v-on:click.prevent="report"
            >Add new</button>
        </div>
    </body>
</html>

And poof! We've got an interactive, VueJS-templated web page.

What an insanely basic VueJS web page looks like

That's... great. Right?

Vue does observables right

Actually, it is great, kinda. data is just a datastore. Vue wraps it in observable overhead, so in many ways, it reminds me, at this level, of KnockoutJS. It's advantage? That we're not wasting time dealing with any of that overhead ourselves, in code or our mental model. Knockout had this horrible convention where you had to call a function to get a "raw" observable, which often threw people for loops).

Vue beats out KnockoutJS easily here. You can very simply put in properties to serve as hooks in your data object to hang all of your datastores, and when you set them, they iterate through your object models and make everything an observable too. If you set message, above, to some giant json model, all of that model would be observable. And each property would be accessible in plain old javascript object ("POJsO") notation.

/*global Vue, window */
document.addEventListener("DOMContentLoaded", function() {
    "use strict";
    window.app = new Vue({
        el: '#app',
        data: {
            payload: {
                b: { c: 2 }
            }
        },
        methods: {
            report: function () {
                // Note that it's app.property, not app.data.property
                console.log(JSON.stringify(payload.b.c, null, "    "));
            }
        }
    });

    // Pretend some event caused this.
    window.app.payload = {
        a: 1,
        b: {
            a:"a",
            b:"b",
            c:"c"
        },
        c: 2
    };
});

And then a quick change to our html...

<div id="app">
    {{ payload.b.c }}
</div>

That, I like. That's how you should do observables. It's the same mental model as a plain ole JavaScript object. There's no "oops, that's an observable! Remember to treat it like a function!" overhead. It's simply magic.

Okay, okay, I haven't looked, but it's almost certainly some getter and setter overhead, which works like magic here. That's why it's important to note that window.app.data is inaccessible. What we don't want to do is blow up our observable chain.

How not to observe...

NOTE: The follow-on from that is that you can't do this:

window.app.payload.d = "spam" and expect spam to be observable. You have to set something that's already an observable, or the extra setter logic won't fire. That just makes sense.

But you can pick up the observable train wherever you want...

NOTE: You really shouldn't be updating your data object's object model for the most part, however. That's a code smell, imo. You'll be getting nice large JSON payloads from your server, and you might have some navigation and convenience objects for managing views, but that's about it. If you make changes to data, that should be going back to the server. And if you're changing the data model on the client, that's probably a business rule that should've been handled on your server-side, not the client-side, where your interest should be almost exclusively presenting views.

Keep your interests separated.

Moving towards an SPA

There are really only two more things you need to know to get pretty close to making minimalistic single page apps (SPAs) with VueJS: conditionals and loops.

Loops with `v-for`

Loops are easy. If you have an array of objects in your datastore, you can loop through them easily with v-for, repeating the markup within that marked node as many times as you have objects.

So if you had data = { stooges: ["Larry", "Moe", "Curly", "Shemp"] }, your markup would be something similar to:

<div id="app">
    <ul>
        <li v-for="stooge in stooges">
            {{ stooge }}
        </li>
    </ul>
</div>

Easy. And if your stooges were objects instead of strings, that's done just like you'd expect, thanks to the POJsO setup Vue supports.

data = { 
    stooges: [
        { name: "Larry", desc: "the curly-headed one." },
        { name: "Moe",   desc: "the relatively smart one." },
        { name: "Curly", desc: "the bald one. See what they did there, with Larry having the curly hair?" },
        { name: "Shemp", desc: "the one nobody knew in the 70s, but somehow everyone did starting around 1990." }
    ]
};

And change the markup to match:

<div id="app">
    <ul>
        <li v-for="stooge in stooges">
            {{ stooge.name }} is {{ stooge.desc }}
        </li>
    </ul>
</div>

Conditionals with `v-if`

Now let's look at conditionals. If you only want something to be rendered when some condition is true, you plant that portion of your markup in a conditional.

 <html>
    <head>
        <title>Animal types and examples</title>

        <script src="../vue.js"></script>
        <script src="./app.js"></script>
    </head>
    <body>
        <div id="app">

            Display all animals of type: <input
                type="text"
                v-model="activeUi"
            /><br />

            <div v-if="activeUi === 'cats'">
                <h3>Cats</h3>
                <ul>
                    <li v-for="cat in cats">
                        {{ cat }}
                    </li>
                </ul>
            </div>

            <div v-else-if="activeUi === 'dogs'">
                <h3>Dogs</h3>
                <ol>
                    <li v-for="dog in dogs">
                        {{ dog }}
                    </li>
                </ol>
            </div>

            <div v-else>
                <h3>Neither dogs nor cats</h3>
                <ul>
                    <li v-for="x in others">
                        {{x.name}}, a {{x.type}}

                        <!-- And note that we can embed ad infinitum, natch -->
                        <ul v-if="x.type === 'rooster'">
                            <li>"That's a joke, I say, that's a joke son!"</li>
                        </ul>
                    </li>
                </ul>
            </div>

        </div>
    </body>
</html>

You're half-way there. To an SPA, that is.

If you use conditionals with reckless aplomb, you could force your way to a complete SPA. No, really, you're done. You could have every portion of your app in some div marked with the proper conditional, and have everything appear iff it's supposed to.

There're just two problems. At some point, it's going to be very difficult to keep this DRY. You will eventually want to use the same markup (HTML) and business logic (JavaScript) in two places that are each embedded deep within some other portion of HTML.

And, well, that's HTML is already a mess. It's sprawling and difficult to grok quickly, which means it'll be difficult to maintain.

Wouldn't it be nice if we could cut that previous html down with some custom components, like this?

 <html>
    <head>
        <title>Animal types and examples</title>

        <script src="../vue.js"></script>
        <script src="../components.js"></script>
        <script src="./app.js"></script>
    </head>
    <body>
        <div id="app">

            Display all animals of type: <input
                type="text"
                v-model="activeUi"
            /><br />

            <cats store="cats" v-if="activeUi === 'cats'" />
            <dogs store="dogs" v-else-if="activeUi === 'dogs'" />
            <other store="others" v-else />

        </div>
    </body>
</html>

... and to do it without transpilation?

We can. And we will. In Part 2.

Labels: howto, javascript, transpilation, VueJS

Add p/React to any legacy client codebase

State & Events Up

Notes, warnings, and caveats

Recipe to move es5 codebase to modern JS (with snowpack, webpack, & babel)

Suggested initial `snowpack.config.js`

Suggested initial `webpack.config.js`

Custom `build.js` script

Different modes of injection

From duplicated to shared services

Let's go to the video tape...

Next Level Dependancy Injection for Children

Unraveling a Promise

Unraveling a Promise with a `finally`

Promise wrapping

TL;DR

Old markup:

Pros and Cons for VueJS Template Types

1. String

2. Template Literals

3. X-Templates (script tags)

4. Inline templates :^P<######

5. Render Function: Spoilers

6. JSX & 7. Single file components.

For Users New to Module Build Systems in JavaScript

Once burned...

How progressive is VueJS, exactly?

Vue does observables right

How not to observe...

Moving towards an SPA

Loops with `v-for`

Conditionals with `v-if`

You're half-way there. To an SPA, that is.

Add p/React to any legacy client codebase

State & Events Up

Notes, warnings, and caveats

Recipe to move es5 codebase to modern JS (with snowpack, webpack, & babel)

Suggested initial snowpack.config.js

Suggested initial webpack.config.js

Custom build.js script

Different modes of injection

From duplicated to shared services

Let's go to the video tape...

Next Level Dependancy Injection for Children

Unraveling a Promise

Unraveling a Promise with a finally

Promise wrapping

TL;DR

Old markup:

Pros and Cons for VueJS Template Types

1. String

2. Template Literals

3. X-Templates (script tags)

4. Inline templates :^P<######

5. Render Function: Spoilers

6. JSX & 7. Single file components.

For Users New to Module Build Systems in JavaScript

Once burned...

How progressive is VueJS, exactly?

Vue does observables right

How not to observe...

Moving towards an SPA

Loops with v-for

Conditionals with v-if

You're half-way there. To an SPA, that is.

Suggested initial `snowpack.config.js`

Suggested initial `webpack.config.js`

Custom `build.js` script

Unraveling a Promise with a `finally`

Loops with `v-for`

Conditionals with `v-if`