From f615f4f90d3a053de2f273f6bd6d3e00ebfbb790 Mon Sep 17 00:00:00 2001 From: Charles Lyding <19598772+clydin@users.noreply.github.com> Date: Wed, 1 Nov 2023 14:24:30 -0400 Subject: [PATCH] docs: additional application builder SSR conversion information (#52485) This change updates the new build system migration guide with additional information regarding the steps needed to convert an existing SSR project to use the new integrated SSR capabilities. PR Close #52485 --- aio/content/guide/esbuild.md | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/aio/content/guide/esbuild.md b/aio/content/guide/esbuild.md index a8f4f069442..c86f0416729 100644 --- a/aio/content/guide/esbuild.md +++ b/aio/content/guide/esbuild.md @@ -111,7 +111,9 @@ Many of the warnings will provide suggestions on how to remedy that problem. If it appears that a warning is incorrect or the solution is not apparent, please open an issue on [GitHub](https://github.com/angular/angular-cli/issues). Also, the later sections of this guide provide additional information on several specific cases as well as current known issues. -For applications that are already using SSR, additional manual adjustments to code will be needed to update the SSR server code to support the new integrated SSR capabilities. +For applications new to SSR, the [Angular SSR Guide](/guide/ssr) provides additional information regarding the setup process for adding SSR to an application. + +For applications that are already using SSR, additional manual adjustments will be needed to update the application server to support the new integrated SSR capabilities. The `application` builder now provides the integrated functionality for all of the following preexisting builders: * `app-shell` @@ -119,7 +121,28 @@ The `application` builder now provides the integrated functionality for all of t * `server` * `ssr-dev-server` -The [Angular SSR Guide](/guide/ssr) provides additional information regarding the new setup process for SSR. +The `ng update` process will automatically remove usages of the `@nguniversal` scope packages where some of these builders were previously located. +The new `@angular/ssr` package will also be automatically added and used with configuration and code being adjusted during the update. +The `@angular/ssr` package supports the `browser` builder as well as the `application` builder. +To convert from the separate SSR builders to the integrated capabilities of the `application` builder, there are several required manual steps. +However, as each application is different, there may be more application specific changes needed beyond these to complete the process. + +1. Combine the options for the above mentioned SSR builders into the `application` builder options within the `angular.json` file. +The previously used builders and their target configurations can then be fully removed from the file. +2. Combine server TypeScript configuration from `tsconfig.server.json` into `tsconfig.app.json`. +The `types` and `files` options are typically the only setting that needs to be combined but others may be needed based on application specific customizations. +You should also add the TypeScript option `"esModuleInterop": true` to ensure `express` imports are [ESM compliant](#esm-default-imports-vs-namespace-imports). +The `tsconfig.server.json` can then be removed as it will no longer be used during builds. +3. Remove and/or update any `npm` scripts referencing the now removed builder targets. +The `ng build` and `ng serve` commands provide equivalent functionality when using the `application` builder. +4. Update application server code to remove Webpack specific elements. +5. Update application server code to use new bootstrapping and output directory structure. +An example of the changes for a v16 project that has been converted can be found [here](https://github.com/alan-agius4/angular-cli-use-application-builder/commit/1defdb93a7f508662bc427439e51505668bf84cd#diff-1ba718c1eb8aa39cd20c2562d92523068c734d75f54655e97d652b992d9b4259). +6. Remove any CommonJS assumptions in the application server code such as `require`, `__filename`, `__dirname`, or other constructs from the [CommonJS module scope](https://nodejs.org/api/modules.html#the-module-scope). +All application code should be ESM compatible. +This does not apply to third-party dependencies. + +In the future, a schematic will make this migration process easier for existing applications. ## Executing a build