@analogjs/astro-angular

Astro is a modern web framework designed for building fast, content-focused websites, compatible with all major frontend frameworks. Though primarily a static site generation (SSG) tool, it can also integrate dynamic components called "islands", which support partial hydration.

This package allows rendering Angular components as islands in Astro.

Setup

$3

Use the astro add command to install the integration

Using npm:

``sh
npx astro add @analogjs/astro-angular
`

Using pnpm:

`sh
pnpm astro add @analogjs/astro-angular
`

Using yarn:

`sh
yarn astro add @analogjs/astro-angular
`

This command:

- Installs the @analogjs/astro-angular package.
- Adds the @analogjs/astro-angular integration to the astro.config.mjs file.
- Installs the necessary dependencies to render Angular components on the server and client, and common Angular dependencies, such as @angular/common.

$3

The integration needs a tsconfig.app.json at the root of the project for compilation.

Create a tsconfig.app.json in the root of the project.

`json
{
"extends": "./tsconfig.json",
"compileOnSave": false,
"compilerOptions": {
"baseUrl": "./",
"outDir": "./dist/out-tsc",
"forceConsistentCasingInFileNames": true,
"strict": true,
"noImplicitOverride": true,
"noPropertyAccessFromIndexSignature": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"sourceMap": true,
"declaration": false,
"downlevelIteration": true,
"experimentalDecorators": true,
"moduleResolution": "node",
"importHelpers": true,
"noEmit": false,
"target": "es2020",
"module": "es2020",
"lib": ["es2020", "dom"],
"skipLibCheck": true
},
"angularCompilerOptions": {
"enableI18nLegacyMessageIdFormat": false,
"strictInjectionParameters": true,
"strictInputAccessModifiers": true,
"strictTemplates": true,
"allowJs": false
},
"files": [],
"include": ["src//.ts", "src//.tsx"]
}
`

Go to Defining A Component to set up an Angular component
to use in an Astro component.

Manual Installation

The integration can also be installed manually

$3

`sh
yarn add @analogjs/astro-angular
`

$3

`sh
npm install @angular/build @angular/{animations,common,compiler-cli,compiler,core,language-service,forms,platform-browser,platform-server} rxjs tslib --save
`

$3

Add the integration to the astro.config.mjs

`js
import { defineConfig } from 'astro/config';
import angular from '@analogjs/astro-angular';

export default defineConfig({
integrations: [angular()],
});
`

Go to Defining A Component

Configuration

$3

Provide an option object to configure the @analogjs/vite-plugin-angular powering this plugin.

`js
import { defineConfig } from 'astro/config';
import angular from '@analogjs/astro-angular';

export default defineConfig({
integrations: [
angular({
vite: {
inlineStylesExtension: 'scss|sass|less',
},
}),
],
});
`

$3

For better compatibility when integrating with other plugins such as Starlight, put the Angular components in a specific folder and use the transformFilter callback function to only transform those files.

`js
import { defineConfig } from 'astro/config';
import angular from '@analogjs/astro-angular';

export default defineConfig({
integrations: [
angular({
vite: {
transformFilter: (_code, id) => {
return id.includes('src/components'); // <- only transform Angular TypeScript files
},
},
}),
],
});
`

$3

To ensure Angular libraries are transformed during Astro's SSR process, add them to the ssr.noExternal array in the Vite config.

`js
import { defineConfig } from 'astro/config';

import angular from '@analogjs/astro-angular';

export default defineConfig({
integrations: [angular()],
vite: {
ssr: {
// transform these packages during SSR. Globs supported
noExternal: ['@rx-angular/**'],
},
},
});
`

Defining A Component

The Astro Angular integration only supports rendering standalone components:

`ts
import { Component, Input } from '@angular/core';

@Component({
selector: 'app-hello',
template:

Hello from Angular!!

@if (show()) {

{{ helpText() }}

}

Toggle
,
})
export class HelloComponent {
helpText = input('help');

show = signal(false);

toggle() {
this.show.update((show) => !show);
}
}
`

Add the Angular component to the Astro component template. This only renders the HTML from the Angular component.

`tsx
---
import { HelloComponent } from '../components/hello.component';

const helpText = "Helping binding";
---




`

To hydrate the component on the client, use one of the Astro client directives:

`tsx
---
import { HelloComponent } from '../components/hello.component';
---


`

Find more information about Client Directives in the Astro documentation.

$3

Outputs can be emitted by the Angular component are forwarded as HTML events to the Astro island.
To enable this feature, add a client directive and a unique [data-analog-id] property to each Angular component:

`tsx
---
import { HelloComponent } from '../components/hello.component';
---


`

Then, listen to the event in the Astro component using the addOutputListener function:

`tsx
---
import { HelloComponent } from '../components/hello.component';
---


`

Adding Component Providers

Additional providers can be added to a component for static rendering and client hydration.

These are renderProviders and clientProviders respectively. These providers are defined as static arrays on the Component class, and are registered when the component is rendered, and hydrated on the client.

`ts
import { Component, OnInit, inject } from '@angular/core';
import { provideHttpClient, HttpClient } from '@angular/common/http';

interface Todo {
id: number;
title: string;
completed: boolean;
}

@Component({
selector: 'app-todos',
template:

Todos

@for (todo of todos(); track todo.id) {

• 
  {{ todo.title }}
  

}

,
})
export class TodosComponent implements OnInit {
static clientProviders = [provideHttpClient()];
static renderProviders = [TodosComponent.clientProviders];

http = inject(HttpClient);
todos = signal([]);

ngOnInit() {
this.http
.get('https://jsonplaceholder.typicode.com/todos')
.subscribe((todos) => this.todos.set(todos));
}
}
`

Using Components in MDX pages

To use components with MDX pages, you must install and configure MDX support by following the Astro integration of @astrojs/mdx. Your astro.config.mjs should now include the @astrojs/mdx integration.

`js
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import angular from '@analogjs/astro-angular';

export default defineConfig({
integrations: [mdx(), angular()],
});
`

Create an .mdx file inside the src/pages directory and add the Angular component import below the frontmatter.

`md
---
layout: '../../layouts/BlogPost.astro'
title: 'Using Angular in MDX'
description: 'Lorem ipsum dolor sit amet'
pubDate: 'Sep 22 2022'
---

import { HelloComponent } from "../../components/hello.component.ts";



`

To hydrate the component on the client, use one of the Astro client directives:

`md
---
layout: '../../layouts/BlogPost.astro'
title: 'Using Angular in MDX'
description: 'Lorem ipsum dolor sit amet'
pubDate: 'Sep 22 2022'
---

import { HelloComponent } from "../../components/hello.component.ts";



`

> Important: In .mdx files the component import must end with the .ts` suffix. Otherwise the dynamic import of the component will fail and the component won't be hydrated.

Current Limitations

- Only standalone Angular components in version v14.2+ are supported
- Content projection to island components is not supported