30 Mar 2021
5 min

Global objects in Angular

In JavaScript we often use entities, such as window, navigator, requestAnimationFrame or location. Some of these objects have been there forever, some are parts of the ever-growing Web APIs feature set. You might have seen Location class or DOCUMENT token used in Angular. Let’s discuss why they exist and what we can learn from them to make our apps cleaner and more flexible.

DOCUMENT

DOCUMENT is a built-in Angular token. Here’s how you can use it. Instead of this:

constructor(@Inject(ElementRef) private readonly elementRef: ElementRef) {}

get isFocused(): boolean {
  return document.activeElement === this.elementRef.nativeElement;
}

You can write this:

constructor(
  @Inject(ElementRef) private readonly elementRef: ElementRef,
  @Inject(DOCUMENT) private readonly documentRef: Document,
) {}

get isFocused(): boolean {
  return this.documentRef.activeElement === this.elementRef.nativeElement;
}

In the first code snippet we accessed global variable directly. In the second example we injected it as a dependency to constructor. I’m not going to throw fancy acronyms at you or say that the first approach breaks some programming principles or patterns. To be honest, I’m not that fluent in those. Instead, I will show you exactly why token approach is better. And we will start by taking a look at where this token comes from. There’s nothing special about its declaration in the @angular/common package:

export const DOCUMENT = new InjectionToken<Document>('DocumentToken');

Inside @angular/platform-browser, however, we see it getting actual value (code snippet simplified):

{provide: DOCUMENT, useValue: document}

When you add BrowserModule to your app.browser.module.ts you register a bunch of different implementations for built-in tokens, such as RendererFactory2, Sanitizer, EventManager and our DOCUMENT. Why is it like that? Because Angular is multiplatform framework. Or rather platform agnostic. It works with abstractions and utilizes dependency injection mechanism heavily to be able to work in browser, on server or mobile platforms. To figure it out, let’s take a sneak peak at ServerModule — another bundled platform (code snippet simplified):

{provide: DOCUMENT, useFactory: _document, deps: [Injector]},

// ...

function _document(injector: Injector) {
  const config = injector.get(INITIAL_CONFIG);
  const window = domino.createWindow(config.document, config.url);

  return window.document;
}

We see that it uses domino to create an imitation of a document, based on some config it once again got from the DI. This is what you get when you, for example, use Angular Universal for server side rendering. We already see the first and most important benefit. Using DOCUMENT token would work in SSR environment whereas accessing global document will not.

Other global entities

So Angular team took care of document for us which is nice. But what if we want to check our browser with [userAgent](https://developer.mozilla.org/en-US/docs/Web/API/NavigatorID/userAgent) string? To do so we would typically access navigator.userAgent. What this actually means is that we first reach for global object, window in browser environment, and then get its navigator property. So let’s start by implementing WINDOW token. It is pretty easy to do with a factory that you can add to token declaration:

export const WINDOW = new InjectionToken<Window>(
  'An abstraction over global window object',
  {
    factory: () => inject(DOCUMENT).defaultView!
  },
);

This is enough to start using WINDOW token similar to DOCUMENT. Now we can use similar approach to create NAVIGATOR:

export const NAVIGATOR = new InjectionToken<Navigator>(
  'An abstraction over window.navigator object',
  {
    factory: () => inject(WINDOW).navigator,
  },
);

We will take it one step further and create a token for USER_AGENT the same way. Why? We’ll see later!

Sometimes making a simple token is not enough. Angular’s Location class is basically a wrapper over native location that improves our dev experience. Since we are used to RxJS streams let’s replace requestAnimationFrame with an Observable implementation:

export const ANIMATION_FRAME = new InjectionToken<
  Observable<DOMHighResTimeStamp>
>(
  'Shared Observable based on `window.requestAnimationFrame`',
  {
    factory: () => {
      const performanceRef = inject(PERFORMANCE);

      return interval(0, animationFrameScheduler).pipe(
        map(() => performanceRef.now()),
        share(),
      );
    },
  },
);

We skipped PERFORMANCE token creation because it follows the same pattern. Now we have a single shared requestAnimationFrame based stream of timestamps which we can use across our app. After we replaced everything with tokens our components no longer rely on magically available items and get everything they depend on from dependency injection, which is neat.

Server Side Rendering

Now say in our app we want to do window.matchMedia('(prefers-color-scheme: dark)'). While there is certainly something in our WINDOW token on the server side, it definitely does not provide full API that Window object has. If we try the above method in SSR we would probably get undefined is not a function error. One thing we can do is wrap such cases with isPlatformBrowser checks but that’s boring. Advantage of DI is we can override stuff. So instead of handling these situation as special cases we can provide WINDOW in our app.server.module.ts with a type-safe mock object that will protect us from non-existent properties.

This showcases another important advantage this approach has: token values can be replaced. This makes it very easy to test components that rely on browser API, especially if you test in Jest where native API is not available otherwise. But mocks are dull. Sometimes we can actually provide something meaningful. In SSR environment we have request object which contains user agent data. That’s why we separated it into its own token — because we can actually obtain it separately sometimes. Here’s how we can turn request into provider:

function provideUserAgent(req: Request): ValueProvider {
  return {
    provide: USER_AGENT,
    useValue: req.headers['user-agent'],
  };
}

And use it in our server.ts when we are setting up Angular Universal:

server.get('*', (req, res) => {
  res.render(indexHtml, {
    req,
    providers: [
      {provide: APP_BASE_HREF, useValue: req.baseUrl},
      provideUserAgent(req),
    ],
  });
});

Node.js also has its own implementation of Performance which we can use on the server side:

{
  provide: PERFORMANCE,
  useFactory: performanceFactory,
}

// ...

export function performanceFactory(): Performance {
  return require('perf_hooks').performance;
}

In case of requestAnimationFrame we will not need Performance though. We probably do not want our Observable chain to run on the server so we can provide EMPTY:

{
  provide: ANIMATION_FRAME,
  useValue: EMPTY,
}

We can follow this pattern to “tokenize” all global objects that we use across our app and provide replacements for various platforms we might run it on.

Wrapping up

With this approach your code becomes well abstracted. Even if you do not run it on the server now, you might want to do it later and you will be ready. Besides, it is much easier to test code when things it relies upon can be substituted. We have created a tiny library of common tokens that we use:

[

ng-web-apis/common

A set of common utils for consuming Web APIs with Angular – ng-web-apis/common

GitHubng-web-apis

](https://github.com/ng-web-apis/common)

If you need something that is currently missing, feel free to create an issue! There is also a sidekick package with SSR versions of those tokens:

[

ng-web-apis/universal

A counterpart to common package to be used with Angular Universal – ng-web-apis/universal

GitHubng-web-apis

](https://github.com/ng-web-apis/universal)

You can explore this Rick and Morty themed project by Igor Katsuba using SSR to see all this in action. If you are interested in Angular Universal in particular, read his article about issues he faced and how to overcome them.

Thanks to this pattern our Angular components library Taiga UI was able to run on both Angular Universal and Ionic setups with no extra fuss. I hope it will be beneficial to you as well.

Frequently asked questions

How do I inject the document object in Angular instead of using the global document?

Inject the DOCUMENT token from @angular/common through the constructor with @Inject(DOCUMENT) instead of reading the global document. The token resolves to the real document in the browser and to a domino-based document during Angular Universal rendering, so the same code works in both environments. Use this.documentRef.activeElement in place of document.activeElement, which also makes the dependency easy to replace in tests.

How do I use window.matchMedia in Angular SSR without getting undefined errors?

Don't call window.matchMedia directly on the server, because the server-side WINDOW value doesn't implement the full Window API and throws an undefined is not a function error. Instead, provide WINDOW in app.server.module.ts with a type-safe mock object that stubs the properties you need. This avoids scattering isPlatformBrowser checks through components and keeps the same injection-based code working on both platforms.

Why does using the global window or document object break Angular Universal rendering?

Global window and document objects exist only in the browser, so referencing them during server-side rendering fails. Angular avoids this by providing DOCUMENT through dependency injection; on the server, the platform creates it with domino's createWindow and returns window.document. Injecting DOCUMENT, WINDOW or NAVIGATOR tokens lets the same component code run in both browser and server environments.

How do I create a WINDOW injection token in Angular?

Declare an InjectionToken<Window> whose factory returns inject(DOCUMENT).defaultView!, which gives you the window without touching the global object. You can then build similar tokens on top of it, such as NAVIGATOR with factory: () => inject(WINDOW).navigator. Because the value comes from the injector, you can override WINDOW in providers when you need a different implementation for SSR or tests.

How do I get requestAnimationFrame as an RxJS Observable in Angular?

Wrap the timing logic in an InjectionToken<Observable<DOMHighResTimeStamp>>, such as ANIMATION_FRAME, whose factory returns interval(0, animationFrameScheduler) piped to map with now() from an injected PERFORMANCE token, followed by share(). That gives your whole app one shared stream of timestamps. On the server, override the token with useValue: EMPTY so the animation chain never runs during SSR.

How do I pass the user agent from the request into Angular Universal?

Create a provider function that maps the request's user agent to a USER_AGENT token, for example with useValue: req.headers['user-agent'], and add it to the providers when rendering in server.ts. Components can then inject USER_AGENT instead of reading navigator.userAgent, which doesn't exist on the server. Keeping it as a separate token makes sense because the user agent is only available from the incoming request.

Share this post

Sign up for our newsletter

Stay up-to-date with the trends and be a part of a thriving community.