From cc6f71746ca7f3e9822ee18dc7d7586f36f92980 Mon Sep 17 00:00:00 2001 From: Adam Plumer Date: Sat, 27 Jun 2020 16:16:29 -0500 Subject: [PATCH] fixup! docs: update issue template and Gotchas guide --- .github/ISSUE_TEMPLATE/Bug.md | 4 ++-- docs/gotchas.md | 12 ++++++++---- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/Bug.md b/.github/ISSUE_TEMPLATE/Bug.md index fcf0cf259..737982f71 100644 --- a/.github/ISSUE_TEMPLATE/Bug.md +++ b/.github/ISSUE_TEMPLATE/Bug.md @@ -1,6 +1,6 @@ <-- -**NOTE**: If you provide an incomplete template, the Universal team is liable to close your issue sight on scene. -Please provide _as much detail as possible_ in as minimal a reproduction as possible. This means no third-party +Please follow the below issue template. Issues not following the issue template will be closed. +Please provide _as much detail as possible_ in as minimal a reproduction as possible. This means no/only one third-party libraries, no application-specific code, etc. Essentially, we're looking for an `ng new` project with maybe one additional file/change. If this is not possible, please look deeper into your issue or post it to StackOverflow for support. This is a bug/feature tracker, meaning that something is actively _missing or broken_ in Angular Universal. diff --git a/docs/gotchas.md b/docs/gotchas.md index d384a8b79..4840b49af 100644 --- a/docs/gotchas.md +++ b/docs/gotchas.md @@ -11,7 +11,7 @@ destroyed until the next render. Next, the server environment inherently does no same capabilities as the browser (and has some that likewise the browser does not). For instance, the server does not have any concept of cookies. You can polyfill this and other functionality, but there is no perfect solution for this. In later sections, we'll walk -through potential mitigations to reduce the error plane when rendering on the server. +through potential mitigations to reduce the scope of errors when rendering on the server. Please also note the goal of SSR: improved initial render time for your application. This means that anything that has the potential to reduce the speed of your application in this @@ -25,7 +25,7 @@ variables in the server environment. This is because the Universal project uses [domino](https://github.com/fgnass/domino) as the server DOM rendering engine. As a result, there is certain functionality that won't be present or supported on the server. This includes the `window` and `document` global objects, cookies, certain HTML elements (like canvas), -and several others. There is no exhaustive list, so please be cognizant of the fact that if you +and several others. There is no exhaustive list, so please be aware of the fact that if you see an error like this, where a previously-accessible global is not defined, it's likely because that global is not available through domino. @@ -76,8 +76,12 @@ often invocations of the global `window` element are to get window size, or some However, on the server, there is no concept of "screen", and so this functionality is rarely needed. You may read online and elsewhere that the recommended approach is to use `isPlatformBrowser` or -`isPlatformServer`. This guidance is **incorrect**. Instead, you should use Angular's Dependency Injection (DI) -in order to remove the offending code and drop in a replacement at runtime. Here's an example: +`isPlatformServer`. This guidance is **incorrect**. This is because you wind up creating platform-specific +code branches in your application code. This not only increases the size of your application unnecessarily, +but it also adds complexity that then has to be maintained. By separating code into separate platform-specific +modules and implementations, your base code can remain about business logic, and platform-specific exceptions +are handled as they should be: on a case-by-case abstraction basis. This can be accomplished using Angular's Dependency +Injection (DI) in order to remove the offending code and drop in a replacement at runtime. Here's an example: ```ts // window-service.ts