Library shim override strategy in gotchas.md doesn't seem to work

🐞 Bug report

What modules are related to this issue?

• aspnetcore-engine
• builders
• common
• express-engine
• hapi-engine

Is this a regression?

Probably

Description

The “library shim” strategy described in https://github.com/angular/universal/blob/master/docs/gotchas.md for fixing “window is not defined” errors doesn’t seem to work for Angular 13. This has caused me to get stuck as I cannot find a way around these errors for my own app (proprietary Universal-incompatible library used in a proprietary app).

This is related to #1675 but specifically focuses on the incorrect documentation.

🔬 Minimal Reproduction

Going by the example snippets in gotchas.md, the compiler will throw an error if LibraryComponent cannot be resolved via the imports from AppModule alone.

To create a reproduction, assume for the sake of argument that @angular/material’s mat-checkbox component is not Universal-compatible - it becomes our library-component.

Here is a reproduction that tries to be as close as possible to the instructions in gotchas.md. The steps i followed to create it were:

• Create a new project via ng new
• ng add @angular/material
• ng add @nguniversal/express-engine
• ng g c homepage --skip-import
• ng g c example --skip-import
• Edit ExampleComponent’s template to be <mat-checkbox></mat-checkbox>
• Edit HomepageComponent’s template to be <app-example></app-example>
• Add ExampleComponent and HomepageComponent to declarations of AppModule (the shared module), but don’t import MatCheckboxModule
• Create browser-app.module.ts with imports of AppModule and MatCheckboxModule (i.e. providing the in-browser implementation for the Universal-incompatible component in the browser-specific module)
• Configure routes as [{path: '', component: HomepageComponent}]
• Run ng serve or ng build to compile the app in browser mode

This results in a compilation error:

Error: src/app/example/example.component.html:1:1 - error NG8001: 'mat-checkbox' is not a known element:
1. If 'mat-checkbox' is an Angular component, then verify that it is part of this module.
2. If 'mat-checkbox' is a Web Component then add 'CUSTOM_ELEMENTS_SCHEMA' to the '@NgModule.schemas' of this component to suppress this message.

1 <mat-checkbox></mat-checkbox>
  ~~~~~~~~~~~~~~

  src/app/example/example.component.ts:5:16
    5   templateUrl: './example.component.html',
                     ~~~~~~~~~~~~~~~~~~~~~~~~~~
    Error occurs in the template of component ExampleComponent.




× Failed to compile.

The error suggests that an implementation for mat-checkbox must be provided in AppModule, and that it’s too late to fill it in in BrowserAppModule as the docs suggest.

(Note: there are a couple of other typos in the snippets ignoring the issues mentioned above - app.module.ts and browser-app.module.ts are missing their classes, server.app.module.ts should probably be renamed server-app.module.ts, and a main.ts snippet should probably be added to illustrate that it should point to browser-app.module.ts)

🔥 Exception or Error

See above

🌍 Your Environment

Angular CLI: 13.1.1                                             
Node: 14.17.6                                                   
Package Manager: npm 7.21.0                                     
OS: win32 x64                                                   
                                                                
Angular: 13.1.0                                                 
... animations, cdk, common, compiler, compiler-cli, core, forms
... material, platform-browser, platform-browser-dynamic        
... platform-server, router                                     
                                                                
Package                         Version                         
---------------------------------------------------------       
@angular-devkit/architect       0.1301.1                        
@angular-devkit/build-angular   13.1.1                          
@angular-devkit/core            13.1.1                          
@angular-devkit/schematics      13.1.1
@angular/cli                    13.1.1
@nguniversal/builders           13.0.1
@nguniversal/express-engine     13.0.1
@schematics/angular             13.1.1
rxjs                            7.4.0
typescript                      4.5.4

[CaerusKaru]

@benelliott I’ll take a closer look at that question; I was the original author so I’ll re-evaluate the strategy in a fresh environment.

[alan-agius4]

Oh I see the problem now.

The documentation does seem to be wrong in this case. In general, I think the best action would be to inform the library authors that their Angular library is not SSR compatible.

Will need to look into alternatives, as right of the bet I don’t exactly know a good way around this. Maybe @CaerusKaru knows?