Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat(platform-server): allow shimming the global env sooner #40559

Closed
wants to merge 6 commits into from
Closed

feat(platform-server): allow shimming the global env sooner #40559

wants to merge 6 commits into from

Conversation

gkalpak
Copy link
Member

@gkalpak gkalpak commented Jan 25, 2021 •
edited
Loading

@angular/platform-server provides the foundation for rendering an Angular app on the server. In order to achieve that, it uses a server-side DOM implementation (currently domino).

For rendering on the server to work as closely as possible to running the app on the browser, we need to make DOM globals (such as Element, HTMLElement, etc.), which are normally provided by the browser, available as globals on the server as well.

Currently, @angular/platform-server achieves this by extending the global object with the DOM implementation provided by domino. This assignment happens in the setDomTypes() function, which is called in a PLATFORM_INITIALIZER. While this works in most cases, there are some scenarios where the DOM globals are needed sooner (i.e. before initializing the platform). See, for example, #24551 and #39950 for more details on such issues.

This commit provides a way to solve this problem by exposing an side-effect-ful entry-point (@angular/platform-server/shims), that shims the global object with DOM globals. People will be able to import this entry-point in their server-rendered apps before bootstrapping the app (for example, in their main.server.ts file).
(See also #39950 (comment).)

In a future update, the universal schematics will include such an import by default in newly generated projects.

Closes #39950.

Related to angular/angular-cli#19869.

@gkalpak gkalpak added feature Issue that requests a new feature state: WIP area: server Issues related to server-side rendering target: minor This PR is targeted for the next minor release labels Jan 25, 2021
@ngbot ngbot bot modified the milestone: Backlog Jan 25, 2021
@google-cla google-cla bot added the cla: yes label Jan 25, 2021
@gkalpak gkalpak mentioned this pull request Jan 25, 2021
Closed
@gkalpak gkalpak force-pushed the fix-platform-server-load-domino branch from a9d33e8 to 5aae56d Compare January 25, 2021 17:41
@mary-poppins
Copy link

You can preview 5aae56d at https://pr40559-5aae56d.ngbuilds.io/.

gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Jan 25, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
1bf6cc4 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/shims`
entry-point was introduced, which can be used to shim the server
environment with APIs normally provided by the browser (such as DOM
globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.
@gkalpak gkalpak mentioned this pull request Jan 25, 2021
Merged
@gkalpak gkalpak mentioned this pull request Jan 25, 2021
Closed
@gkalpak gkalpak force-pushed the fix-platform-server-load-domino branch from 5aae56d to 6340fd7 Compare January 26, 2021 12:39
@mary-poppins
Copy link

You can preview 6340fd7 at https://pr40559-6340fd7.ngbuilds.io/.

@gkalpak gkalpak force-pushed the fix-platform-server-load-domino branch from 6340fd7 to f601f3f Compare January 26, 2021 20:44
@mary-poppins
Copy link

You can preview f601f3f at https://pr40559-f601f3f.ngbuilds.io/.

@gkalpak gkalpak force-pushed the fix-platform-server-load-domino branch from f601f3f to e8626aa Compare January 27, 2021 15:08
@mary-poppins
Copy link

You can preview e8626aa at https://pr40559-e8626aa.ngbuilds.io/.

@gkalpak gkalpak marked this pull request as ready for review January 27, 2021 15:51
@gkalpak gkalpak added action: review The PR is still awaiting reviews from at least one requested reviewer and removed state: WIP labels Jan 27, 2021
@gkalpak
Copy link
Member Author

gkalpak commented Jan 27, 2021

I have updated the example to not use @nguniversal dependencies. PTAL, @alan-agius4.

@mary-poppins
Copy link

You can preview 5392175 at https://pr40559-5392175.ngbuilds.io/.

@gkalpak
Copy link
Member Author

gkalpak commented Feb 9, 2021

Comments addressed (the main change is renaming the entry-point from shims to init).

jessicajaniuk
jessicajaniuk approved these changes Feb 9, 2021
View reviewed changes
Copy link
Contributor

@jessicajaniuk jessicajaniuk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

reviewed-for: public-api

alxhub pushed a commit that referenced this pull request Feb 9, 2021
@gkalpak @alxhub
fix(docs-infra): correctly handle entry-points with no public exports (…
9aa3e9f 
…#40737)

Previously, if an entry-point had no public exports (such as the
`@angular/platform-server/shims` introduced in #40559, which is a
side-effect-ful entry-point), it was incorrectly marked as having all
its exports deprecated (which marks the entry-point as deprecated as
well).

This commit fixes this by ensuring that an entry-point is not marked as
having all its exports deprecated if it has no public exports.

PR Close #40737
alxhub pushed a commit that referenced this pull request Feb 9, 2021
@gkalpak @alxhub
fix(docs-infra): correctly handle entry-points with no public exports (…
655b6b2 
…#40737)

Previously, if an entry-point had no public exports (such as the
`@angular/platform-server/shims` introduced in #40559, which is a
side-effect-ful entry-point), it was incorrectly marked as having all
its exports deprecated (which marks the entry-point as deprecated as
well).

This commit fixes this by ensuring that an entry-point is not marked as
having all its exports deprecated if it has no public exports.

PR Close #40737
alxhub pushed a commit that referenced this pull request Feb 9, 2021
@gkalpak @alxhub
fix(docs-infra): correctly handle entry-points with no public exports (…
4e4fcac 
…#40737)

Previously, if an entry-point had no public exports (such as the
`@angular/platform-server/shims` introduced in #40559, which is a
side-effect-ful entry-point), it was incorrectly marked as having all
its exports deprecated (which marks the entry-point as deprecated as
well).

This commit fixes this by ensuring that an entry-point is not marked as
having all its exports deprecated if it has no public exports.

PR Close #40737
jelbourn
jelbourn approved these changes Feb 9, 2021
View reviewed changes
Copy link
Member

@jelbourn jelbourn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Reviewed-for: public-api

@gkalpak gkalpak removed the request for review from alxhub February 9, 2021 19:44
@gkalpak gkalpak added action: merge The PR is ready for merge by the caretaker and removed action: review The PR is still awaiting reviews from at least one requested reviewer labels Feb 9, 2021
@gkalpak
build(platform-server): add domino to the list of dependencies
9b24e1d 
The `platform-server` package currently depends on the [domino][1]
package. This commit adds `domino` to the list of dependencies for the
`platform-server` `ng_module` target.

[1]: https://www.npmjs.com/package/domino
@gkalpak
ci: add integration test for Angular Elemens with SSR
171d9ba 
This commit adds an integration test that uses `@angular/elements` with
`@angular/platform-server` in order to highlight a current
incompatibility. The issue will be fixed in a subsequent commit.
@gkalpak
fixup! ci: add integration test for Angular Elemens with SSR
7b3d001
@gkalpak
feat(platform-server): allow shimming the global env sooner
b7dc4b2 
`@angular/platform-server` provides the foundation for rendering an
Angular app on the server. In order to achieve that, it uses a
server-side DOM implementation (currently [domino][1]).

For rendering on the server to work as closely as possible to running
the app on the browser, we need to make DOM globals (such as `Element`,
`HTMLElement`, etc.), which are normally provided by the browser,
available as globals on the server as well.

Currently, `@angular/platform-server` achieves this by extending the
`global` object with the DOM implementation provided by `domino`. This
assignment happens in the [setDomTypes()][2] function, which is
[called in a `PLATFORM_INITIALIZER`][3]. While this works in most cases,
there are some scenarios where the DOM globals are needed sooner (i.e.
before initializing the platform). See, for example, angular#24551 and angular#39950
for more details on such issues.

This commit provides a way to solve this problem by exposing a
side-effect-ful entry-point (`@angular/platform-server/init`), that
shims the `global` object with DOM globals. People will be able to
import this entry-point in their server-rendered apps before
bootstrapping the app (for example, in their `main.server.ts` file).
(See also [angular#39950 (comment)][4].)

In a future update, the [`universal` schematics][5] will include such an
import by default in newly generated projects.

[1]: https://www.npmjs.com/package/domino
[2]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/domino_adapter.ts#L17-L21
[3]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/server.ts#L33
[4]: angular#39950 (comment)
[5]: https://github.com/angular/angular-cli/blob/cc51432661eb4ab4b6a3/packages/schematics/angular/universal
@gkalpak
fixup! feat(platform-server): allow shimming the global env sooner
cb49c8f
@gkalpak
fixup! feat(platform-server): allow shimming the global env sooner
a67a720
@gkalpak gkalpak force-pushed the fix-platform-server-load-domino branch from 5392175 to a67a720 Compare February 11, 2021 17:26
@mary-poppins
Copy link

You can preview a67a720 at https://pr40559-a67a720.ngbuilds.io/.

josephperrott pushed a commit that referenced this pull request Feb 12, 2021
@gkalpak @josephperrott
ci: add integration test for Angular Elemens with SSR (#40559)
177eab2 
This commit adds an integration test that uses `@angular/elements` with
`@angular/platform-server` in order to highlight a current
incompatibility. The issue will be fixed in a subsequent commit.

PR Close #40559
josephperrott pushed a commit that referenced this pull request Feb 12, 2021
@gkalpak @josephperrott
feat(platform-server): allow shimming the global env sooner (#40559)
43ecf8a 
`@angular/platform-server` provides the foundation for rendering an
Angular app on the server. In order to achieve that, it uses a
server-side DOM implementation (currently [domino][1]).

For rendering on the server to work as closely as possible to running
the app on the browser, we need to make DOM globals (such as `Element`,
`HTMLElement`, etc.), which are normally provided by the browser,
available as globals on the server as well.

Currently, `@angular/platform-server` achieves this by extending the
`global` object with the DOM implementation provided by `domino`. This
assignment happens in the [setDomTypes()][2] function, which is
[called in a `PLATFORM_INITIALIZER`][3]. While this works in most cases,
there are some scenarios where the DOM globals are needed sooner (i.e.
before initializing the platform). See, for example, #24551 and #39950
for more details on such issues.

This commit provides a way to solve this problem by exposing a
side-effect-ful entry-point (`@angular/platform-server/init`), that
shims the `global` object with DOM globals. People will be able to
import this entry-point in their server-rendered apps before
bootstrapping the app (for example, in their `main.server.ts` file).
(See also [#39950 (comment)][4].)

In a future update, the [`universal` schematics][5] will include such an
import by default in newly generated projects.

[1]: https://www.npmjs.com/package/domino
[2]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/domino_adapter.ts#L17-L21
[3]: https://github.com/angular/angular/blob/0fc8466f1be392917e0c/packages/platform-server/src/server.ts#L33
[4]: #39950 (comment)
[5]: https://github.com/angular/angular-cli/blob/cc51432661eb4ab4b6a3/packages/schematics/angular/universal

PR Close #40559
gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Feb 12, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
c96ad79 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Feb 12, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
4283f5d 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Feb 12, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
0a63e10 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
@gkalpak gkalpak deleted the fix-platform-server-load-domino branch February 16, 2021 10:03
gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Feb 17, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
24787c3 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
gkalpak added a commit to gkalpak/angular-cli that referenced this pull request Feb 17, 2021
@gkalpak
feat(@schematics/angular): augment universal schematics to import `…
38b42c2 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
alan-agius4 pushed a commit to angular/angular-cli that referenced this pull request Feb 18, 2021
@gkalpak @alan-agius4
feat(@schematics/angular): augment universal schematics to import `…
1199205 
…platform-server` shims

In angular/angular#40559, a new `@angular/platform-server/init`
entry-point was introduced, which can be used to initialize the server
environment by providing shims for APIs normally provided by the browser
(such as DOM globals).

If the project is using a version of Angular (and thus
`@angular/platform-server`) that is known to include this new
entry-point, the newly generated `main.server.ts` file should import it
at the top in order to ensure that the shims will be available as soon
as possible (before other direct or transitive imports that may rely on
them). See also angular/angular#40559 for more details.

NOTE:
This `universal` schematic is the base for `app-shell`,
`@nguniversal/express-engine` and `@nguniversal/hapi-engine`.

Fixes angular/angular#40559
@angular-automatic-lock-bot
Copy link

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

This action has been performed automatically by a bot.

@angular-automatic-lock-bot angular-automatic-lock-bot bot locked and limited conversation to collaborators Mar 19, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@petebacondarwin petebacondarwin petebacondarwin left review comments

@mhevery mhevery mhevery approved these changes

@CaerusKaru CaerusKaru CaerusKaru approved these changes

@atscott atscott atscott approved these changes

@jelbourn jelbourn jelbourn approved these changes

@kyliau kyliau kyliau approved these changes

@alan-agius4 alan-agius4 alan-agius4 approved these changes

@AndrewKushnir AndrewKushnir AndrewKushnir approved these changes

@jessicajaniuk jessicajaniuk jessicajaniuk approved these changes

Assignees
No one assigned
Labels
action: merge The PR is ready for merge by the caretaker area: server Issues related to server-side rendering cla: yes feature Issue that requests a new feature target: minor This PR is targeted for the next minor release
Projects
None yet
Milestone
Backlog
Development

Successfully merging this pull request may close these issues.

Angular Universal: HTMLElement is not defined