@netlify/angular-runtime

Angular Runtime

This build plugin implements Angular Support on Netlify.

Table of Contents

• Installation and Configuration
• Accessing Request and Context during Server-Side Rendering
• Customizing request handling
  • Limitations
• CLI Usage
• Getting Help
• Contributing
• License

Installation and Configuration

Netlify automatically detects Angular projects and sets up the latest version of this plugin. There's no further configuration needed from Netlify users.

Manual Installation

If you need to pin down this plugin to a fixed version, install it manually.

Create a netlify.toml in the root of your project. Your file should include the plugins section below:

[[plugins]]
  package = "@netlify/angular-runtime"

Install it via your package manager:

npm install -D @netlify/angular-runtime
# or
yarn add -D @netlify/angular-runtime

Read more about file-based plugin installation in our docs.

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:

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.

To test this in local development, run your Angular project using netlify serve:

netlify serve

App Engine Developer Preview usage with Angular@19

If you opt into the App Engine Developer Preview 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:

+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}`)
    // ...
  }
  
}

Customizing request handling

Starting with Angular@19. The build plugin makes use of server.ts file to handle requests. The default Angular scaffolding does generate incompatible code for Netlify so build plugin will swap it for compatible server.ts file for you automatically if it detects default one being used. 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 did not opt into the App Engine Developer Preview:

import { CommonEngine } from '@angular/ssr/node'
import { render } from '@netlify/angular-runtime/common-engine'

const commonEngine = new CommonEngine()

export async function netlifyCommonEngineHandler(request: Request, context: any): Promise<Response> {
  return await render(commonEngine)
}

If you opted into the App Engine Developer Preview:

import { AngularAppEngine, createRequestHandler } from '@angular/ssr'
import { getContext } from '@netlify/angular-runtime/context'

const angularAppEngine = new AngularAppEngine()

export async function netlifyAppEngineHandler(request: Request): Promise<Response> {
  const context = getContext()

  const result = await angularAppEngine.handle(request, context)
  return result || new Response('Not found', { status: 404 })
}

/**
 * The request handler used by the Angular CLI (dev-server and during build).
 */
export const reqHandler = createRequestHandler(netlifyAppEngineHandler)

Limitations

The server.ts file that's part of the Angular scaffolding is meant for deploying to a VM, and is not compatible with this Netlify build plugin for Angular@17 and Angular@18. If you applied changes to that file, you'll need to replicate them in an Edge Function. See (#135)[https://github.com/netlify/angular-runtime/issues/135] for an example.

CLI Usage

Requirements

To use the Angular Runtime while building and deploying with the CLI, you need to have netlify-cli v17.0.0 installed (or a later version).

Please also make sure to use ntl deploy --build (rather than ntl build && ntl deploy).

Getting Help

We love to hear from you so if you have questions, comments or find a bug in the project, let us know! You can either:

• Open an issue on this repository
• Tweet at us! We're @Netlify on Twitter
• Or, join the community forums

Contributing

We welcome contributions ❤️ - see the CONTRIBUTING.md file for details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details

Changelog

2.2.0 (2024-11-19)

Features

• support @19 (#216) (f6776f5)

Bug Fixes

• deps: update dependency @netlify/edge-functions to ^2.8.1 (#119) (42904c1)
• deps: update dependency fs-extra to v11.2.0 (#99) (186dc1e)
• getContext() should be sync (#222) (1cb569c)