The Web Locks API: Coordinating Work Across Same-Origin Tabs
The Web Locks API lets tabs and workers from the same origin request named locks to coordinate access and avoid duplicate work. This guide explains shared and exclusive modes, Promise-bound lock lifetime, and the API's coordination limits.
Publication & corrections: infostoa · Editorial standards
Individual author and specialist reviewer information is not provided for this article.
When several tabs update the same origin's storage or start the same background task, duplicate work and race conditions can result. The Web Locks API lets same-origin scripts in a browser request a named lock to coordinate that work. The lock coordinates browser contexts; it is not a distributed lock shared with a server or another device. The API is available in secure contexts, such as HTTPS, in supporting browsers.
1. Names and shared or exclusive modes
navigator.locks.request(name, callback) passes a lock name and a function to run. Requests are exclusive by default, coordinating so another exclusive request with the same name does not run its critical section at the same time. Work that can safely proceed together, such as reads, can request mode: 'shared'; multiple shared locks may be held concurrently. An exclusive request for that name waits until the shared holders finish.
The application chooses the logical lock name. If storage synchronization and report generation both modify the same resource, they may need to use a common name. Accidental reuse across unrelated resources creates unnecessary waiting, while different names for the same resource fail to coordinate. Keep naming rules consistent across the code that accesses a resource.
2. The callback Promise determines lock lifetime
Once a request is granted, the browser invokes its callback. The lock remains held until the Promise returned by that callback settles, whether it fulfills or rejects. Await the asynchronous work that actually needs protection inside the callback. Starting work and returning before it finishes can let the critical operation continue after the lock has been released. Conversely, holding a lock while waiting on a long network request or user input can block other tabs for too long.
3. Same-origin scope and coordination limits
Web Locks coordinates resource use among browser contexts of the same origin. It does not share a lock with a different origin, separate browser profile, or process on another device. If a tab closes or a worker terminates, its execution context can end; a lock should not be treated as a durable task queue. Persist important results in storage or on a server separately.
The API helps reduce races but is not a database transaction or a server-side idempotency key. Nested requests for several locks can wait on one another depending on acquisition order. Use narrow resource names, keep callbacks short, and design application state to recover from tab or browser termination. The lock controls access while held; it does not make every operation atomic or durable.
4. Expert perspective: skip immediately or cancel waiting
MDN's specialist request() reference explains that ifAvailable set to true invokes the callback with null instead of a Lock when the lock cannot be granted immediately. Callback invocation alone therefore does not establish that the protected section was entered. Check for null before performing protected updates. A second tab can use that branch to skip cache regeneration already being performed elsewhere, rather than start duplicate work.
An AbortSignal supplied through signal instead cancels a request that has not yet been granted. MDN documents rejection of the canceled request's Promise. This option does not automatically cancel application work in a callback that has already started. Canceling an ongoing fetch or other operation requires connecting to that operation's own cancellation interface and handling any partially completed state.
These are different policies: ifAvailable selects an immediate null branch, while signal cancels a waiting request. MDN documents NotSupportedError when signal is supplied and ifAvailable is true, so do not combine them on one request. With one tab holding the lock, test the null branch, cancellation while queued, and signaling after a callback starts separately. Those cases identify the actual boundary between waiting for access and doing the work.