diff --git a/README.md b/README.md index c81a3a6c..e2faa7e1 100644 --- a/README.md +++ b/README.md @@ -1,211 +1,4 @@ - +# Netlify Angular Runtime -# Angular Runtime - -
- -This build plugin implements Angular Support on Netlify. - -## Table of Contents - -- [Installation and Configuration](#installation-and-configuration) -- [Accessing `Request` and `Context` during Server-Side Rendering](#accessing-request-and-context-during-server-side-rendering) -- [Request handling](#request-handling) - - [Customizing request handling](#customizing-request-handling) - - [Limitations](#limitations) -- [CLI Usage](#cli-usage) -- [Getting Help](#getting-help) -- [Contributing](#contributing) -- [License](#license) - -## Installation and Configuration - -Netlify automatically detects Angular projects and sets up the latest version of this plugin. - -### For Angular 17 and Angular 18 - -There's no further configuration needed from Netlify users. - -### For Angular 19+ - -If you are using Server-Side Rendering you will need to install Angular Runtime in your Angular project to be able to import required utilities to successfully deploy request handler to Netlify. See [Manual Installation](#manual-installation) for installations details. See [Request handling](#request-handling) for more information about request handler. - -### Manual Installation - -If you need to pin this plugin to a specific version or if you are using Server-Side Rendering with Angular 19+, you will need to install the plugin manually. - -Install it via your package manager: - -```bash -npm install -D @netlify/angular-runtime -# or -yarn add -D @netlify/angular-runtime -``` - -## Accessing `Request` and `Context` during Server-Side Rendering - -During server-side rendering (SSR), you can access the incoming `Request` object and the Netlify-specific `Context` object via providers: - -```ts -import type { Context } from "@netlify/edge-functions" - -export class FooComponent { - - constructor( - // ... - @Inject('netlify.request') @Optional() request?: Request, - @Inject('netlify.context') @Optional() context?: Context, - ) { - console.log(`Rendering Foo for path ${request?.url} from location ${context?.geo?.city}`) - // ... - } - -} -``` - -Keep in mind that these will not be available on the client-side or during [prerendering](https://angular.dev/guide/prerendering#prerendering-parameterized-routes). - -To test this in local development, run your Angular project using `netlify serve`: - -```sh -netlify serve -``` - -### App Engine usage - -With App Engine accessing `Request` and `Context` objects is streamlined. Instead of custom Netlify prefixed providers, you should use the standardized injection tokens for those provided by `@angular/core` instead: - -```diff -+import { REQUEST, REQUEST_CONTEXT } from '@angular/core' -import type { Context } from "@netlify/edge-functions" - -export class FooComponent { - - constructor( - // ... -- @Inject('netlify.request') @Optional() request?: Request, -- @Inject('netlify.context') @Optional() context?: Context, -+ @Inject(REQUEST) @Optional() request?: Request, -+ @Inject(REQUEST_CONTEXT) @Optional() context?: Context, - ) { - console.log(`Rendering Foo for path ${request?.url} from location ${context?.geo?.city}`) - // ... - } - -} -``` - -Note that App Engine in Angular 19 is in Developer Preview and requires explicit opt-in. - -## Request handling - -Starting with Angular@19. The build plugin makes use of the `server.ts` file to handle requests. The default Angular scaffolding generates incompatible code for Netlify so the build plugin will swap it for compatible `server.ts` file automatically if it detects default version being used. - -Make sure you have `@netlify/angular-runtime` version 4.0.0 or later installed in your project. Netlify compatible `server.ts` file imports utilities from this package and Angular Compiler need to be able to resolve it and it can only do that if it's installed in your project and not when it's auto-installed by Netlify. - -### Customizing request handling - -If you need to customize the request handling, you can do so by copying one of code snippets below to your `server.ts` file. - -If you are using `@angular/ssr@21.2.9+` with AppEngine: - -```ts -import { AngularAppEngine, createRequestHandler } from '@angular/ssr' -import { getAllowedHosts, getContext, getTrustProxyHeaders } from '@netlify/angular-runtime/app-engine.js' - -const angularAppEngine = new AngularAppEngine({ - allowedHosts: getAllowedHosts(), - trustProxyHeaders: getTrustProxyHeaders(), -}) - -export async function netlifyAppEngineHandler(request: Request): Promise