URL resolution

Some metadata values need a URL as value. Like canonical URL metadata. And in some cases, an absolute URL is required or preferred. For instance standard module's canonical URL or Open Graph module's URL

Both URLs mentioned can be set at the same time

By using mentioned canonical URL global metadata. See metadata values JSON guide for more info

Providing an absolute URL over and over could be repetitive. For instance:

const fooPageMetadata: GlobalMetadata = {
  canonicalUrl: 'https://example.com/app/foo',
}
const barPageMetadata: GlobalMetadata = {
  canonicalUrl: 'https://example.com/app/bar',
}

The same URL prefix repeats around https://example.com/app.

But don't worry, got you covered 😉 Set up URL resolution and the problem will be over

Set up

To avoid repeating the same URL prefix over and over, the library provides a way to configure a base URL. This way, when specifying a relative URL where an absolute URL is required or preferred, the base URL will be prepended. So that eventually an absolute URL appears as metadata value.

For standalone, module-free appsFor non-standalone, module-based apps

Standalone, module-free apps

This is the default approach for authoring Angular projects generated with Angular CLI v17 and above. It's also the recommended way to author Angular projects right now. Using standalone APIs is the preferred and recommended way to do so. You can use standalone APIs too despite the application is still module-based. Learn more about standalone at standalone components guide and standalone migration

Add withNgxMetaBaseUrl as a provideNgxMetaCore feature to your standalone app's app.config.ts file providers.

app.config.ts

import {provideNgxMetaCore, withNgxMetaBaseUrl} from '@davidlj95/ngx-meta/core';

export const appConfig: ApplicationConfig = {
  // ...
  providers: [
    // ...
    provideNgxMetaCore(
      withNgxMetaBaseUrl('https://example.com/app')
    ),
    // ...
  ],
}

Non-standalone, module-based apps

This is the default and traditional approach for authoring Angular projects generated with Angular CLI before v17. It's not the preferred or recommended way to author Angular projects right now. Using standalone APIs is the preferred and recommended way to do so. You can use standalone APIs too despite the application is still module-based. Learn more about standalone at standalone components guide and standalone migration. You can anyway keep using the module-based equivalent APIs for now if you prefer to do so.

Add withNgxMetaBaseUrl as an NgxMetaCoreModule.forRoot feature in app.module.ts file.

app.module.ts

import {NgxMetaCoreModule, withNgxMetaBaseUrl} from '@davidlj95/ngx-meta/core';

@NgModule({
  // ...
  imports: [
    // ...
    NgxMetaCoreModule.forRoot(
      withNgxMetaBaseUrl('https://example.com/app'),
    ),
    // ...
  ],
  // ...
})
export class AppModule {}

Usage

With a relative URL

Once set up, you can specify a relative URL as URL and the absolute URL will be resolved for you behind the scenes. The initial example setting some canonical URLs could now be reduced to:

const fooPageMetadata: GlobalMetadata = {
  canonicalUrl: 'foo', // value will be 'https://example.com/app/foo'
}
const barPageMetadata: GlobalMetadata = {
  canonicalUrl: 'bar', // value will be 'https://example.com/app/bar'
}

Pretty neat, isn't it?

With Angular router's URL

What if the relative URL you want to use is the same one used for the Angular's router route? In that case, you can provide the magic value ANGULAR_ROUTER_URL. This will instruct the library to use the current Angular's router URL as relative URL. Which in turn will be resolved into an absolute URL.

const routes = [
  {
    path: 'foo',
    component: FooComponent,
  },
  // ...
]
const fooPageMetadata: GlobalMetadata = {
  canonicalurl: ANGULAR_ROUTER_URL, // value will be 'https://example.com/app/foo'
}

URL resolution must be enabled to use Angular router URL

Otherwise an invalid URL will be used as metadata value. Specifically, the ANGULAR_ROUTER_URL symbol converted to string.

Recipes

Using defaults

You can also use the previous ANGULAR_ROUTER_URL value as a default value for some metadata. This way the Angular router's URL will be used as default if no other value is specified.

For standalone, module-free appsFor non-standalone, module-based apps

Standalone, module-free apps

This is the default approach for authoring Angular projects generated with Angular CLI v17 and above. It's also the recommended way to author Angular projects right now. Using standalone APIs is the preferred and recommended way to do so. You can use standalone APIs too despite the application is still module-based. Learn more about standalone at standalone components guide and standalone migration

app.config.ts

import {provideNgxMetaCore, withNgxMetaBaseUrl} from '@davidlj95/ngx-meta/core';

export const appConfig: ApplicationConfig = {
  // ...
  providers: [
    // ...
    provideNgxMetaCore(
      withNgxMetaDefaults(
        {
          canonicalUrl: ANGULAR_ROUTER_URL,
        } satisfies GlobalMetadata
      )
    ),
    // ...
  ],
}

Non-standalone, module-based apps

This is the default and traditional approach for authoring Angular projects generated with Angular CLI before v17. It's not the preferred or recommended way to author Angular projects right now. Using standalone APIs is the preferred and recommended way to do so. You can use standalone APIs too despite the application is still module-based. Learn more about standalone at standalone components guide and standalone migration. You can anyway keep using the module-based equivalent APIs for now if you prefer to do so.

app.module.ts

import {NgxMetaCoreModule, withNgxMetaDefaults, ANGULAR_ROUTER_URL} from '@davidlj95/ngx-meta/core';

@NgModule({
  // ...
  imports: [
    // ...
    NgxMetaCoreModule.forRoot(
      withNgxMetaDefaults({
        canonicalUrl: ANGULAR_ROUTER_URL,
      } satisfies GlobalMetadata),
    ),
    // ...
  ],
  // ...
})
export class AppModule {}

Implementation notes

The provided base URL string will be prepended to the relative URL value. The only adjustments that are made are:

Double slashes are avoided. Base URL https://example.com/app/ (trailing slash) + relative URL /foo (leading slash) will result in https://example.com/app/foo
Slash is added when needed. Base URL https://example.com/app (no trailing slash) + relative URL foo (no leading slash) will result in https://example.com/app/foo
No trailing slash for home is fine. Base URL https://example.com/app (no trailing slash) and an empty string relative URL will result in https://example.com/app (base URL as is). Beware that if using ANGULAR_ROUTER_URL the router root URL is /. So if using the previous base URL, the result for the home / root page would be https://example.com/app/ (with trailing slash).