How to setup a Typescript project to use Wake Lock API.

Introduction

The Wake Lock API provides a way for developers to request a device from dimming or locking a screen.

There are many cases that may need to do this such as following a recipe where a user are generally busy and need to refer back to your page occasionally or a games where long animation sequences takes place.

Prior to this API developers used resource intensive ways to keeps screens for turning off. I have use such methods as by playing a hidden video to force the browser from turning off the screen. This would lead to higher battery usage and even devices getting hot for a simple task of keeping the screen on.

Compatibility

Most major browsers have a working implementation with only Firefox outstanding. See here for more details.

Project setup

Since this is a new feature, Typescript needs the Wake Lock API types setup in order for it to compile.

This setup will fix the following error messages.

TS2339: Property 'wakeLock' does not exist on type 'Navigator'.
TS2304: Cannot find name 'WakeLockSentinel'.

Step 1.
Types for Wake Lock need to be added to the typescript compile settings.
To do this the following package is needed to be installed.

npm i @types/dom-screen-wake-lock -D

This package contains type definitions for w3c Screen Wake Lock API

Step 2.
In the tsconfig.json add the following.

"compilerOptions": {   
  "types": ["dom-screen-wake-lock"]
}

After this you can use all the Wake Lock API functions.

Wake Lock API Code

function isWakeLockSupported() {
  return "wakeLock" in navigator;
}

Use the code above to determine if the API is supported.

async function requestWakeLock() {
  let wakeLock: WakeLockSentinel | null = null;
  // Surround with try/catch since browser can reject the request.
  try {
    // Request a wake lock
    wakeLock = await navigator.wakeLock.request("screen");
    // Listen if lock has been released.
    wakeLock.addEventListener("release", () => {
      console.log("Screen Wake Lock released:", wakeLock?.released);     
    });    
  } catch (err) {
    // The Wake Lock request has failed - usually system related, such as battery. 
  }
  return wakeLock;
}

The Wake Lock API uses promise interface to request a lock from the browser.
The navigator.wakeLock.request takes one parameter ‘screen’. For now this is the only property available.
The browser can reject the request for a few reasons such as if the battery is low.
By surrounding the API call in try-catch statement gives you more details on why the request was rejected.
The browser can release the wake lock at any time. In order to know if the lock has been released, there is a release event to listen to.
The returned WakeLockSentinel also has a released property that is set to false immediately on creation and then set to true if the lock has been released.

async function releaseWakeLock(){
  return await wakeLock?.release();
}

When you are done and no longer need to keep the screen wake. You can call the release function.

The browser is tied to the page visibility and as soon as the user navigates away from the page the lock will be released.
You can listen to page visibility changed and re-lock if need be like so:

document.addEventListener("visibilitychange", () => {
  if (document.visibilityState === "visible") {
    // You can do some state checks to determine if you want to reactivate wake lock
    requestWakeLock();    
  }
});

Conclusion

The Wake Lock API provides a powerful solution for developers to prevent screens from dimming or locking, ensuring a seamless user experience in various scenarios such as reading recipes or engaging in interactive games. With growing compatibility across major browsers, including pending implementation in Firefox, now is the perfect time to explore and integrate the Wake Lock API into your projects.

By following the simple setup steps outlined in this blog post, including adding the necessary TypeScript types and incorporating the provided code snippets, you can easily leverage the Wake Lock API in your projects.
With the Wake Lock API, you can efficiently keep the screen awake without resorting to resource-intensive workarounds, reducing battery usage and device overheating.

To see a practical implementation of the Wake Lock API, check out the accompanying sample project on GitHub: Here

Resources

The header image used in this blog post is by Matt Seymour on Unsplash.

For more information on the Wake Lock API, refer to the following resources:

• Screen Wake Lock API — MDN Web Docs
• Wake Lock API — Chrome Developers