Share

Modern Web Weekly #78

I received quite a few questions lately about push notifications coming from PWAs that only display in the notification tray on Samsung phones, but not on the lock screen. This means that there is only a small icon shown in the status bar of the screen, but the notification itself isn’t.

This is a problem because this way, it’s not always clear that a push notification was received. This limitation doesn’t apply to native apps, only PWAs, so to put it bluntly, it sucks.

This especially pertains to Samsung phones since they’re running One UI, which is Samsung’s customized software interface for its Galaxy phones and tablets. It has aggressive battery and notification management features that intentionally suppress push notifications coming from web apps to prevent malicious web apps from spamming users.

After some research, I found out this can be solved by explicitly setting notification categories for PWAs.

On your Samsung phone, go to Settings > Apps > [your PWA] > Notifications and look for Notification categories:

If you don’t see Notification categories, first go to Settings > Notifications > Advanced settings:

Inside Advanced settings, enable Manage notification categories for each app:

Now go back to Settings > Apps > [your PWA] > Notifications, and you should see Notification categories:

If you tap Notification categories, you may see:

This means your PWA hasn’t received any push notifications yet.

Send a push notification to your PWA and then open Notification categories again. You should now be able to enable the General category:

If you now send a push notification again, it should show up on the lock screen:

Make sure you have also correctly set the other options for your app’s notifications:

You may first see a push notification that looks collapsed and that only expands to show its content when you tap it. If you want push notifications to be expanded by default, go to Settings > Notifications > Notification pop-up style:

Here you can enable Detailed, so the notification will be expanded by default:

Now Really Deprecated:
<meta name=”apple-mobile-web-app-capable” content=”yes”>

On iOS 26.5, you no longer need to add the meta tag

<meta name="apple-mobile-web-app-capable" content="yes">  

to show splash screens on iOS.

It has been required for years on iOS devices to make sure an installed web app would get a standalone layout without any browser controls, but has been officially deprecated in 2011 in favor of display: standalone in manifest.json.

For iOS, it was deprecated since iOS 11.3, but it was still needed to show splash screens on iOS. Since iOS 26.5, I noticed, this is no longer the case: splash screens are displayed on iOS without this meta tag.

Nevertheless, I strongly advise you to keep it around in your PWA for some years to make sure people running an iPhone with a version < 26.5 also get to see the splash screen of your PWA.

Why You Should Prefer cache.match() Over caches.match()

caches.match() seems like a handy convenience method to quickly find a response in any of the caches your service worker controls, and I admit I always used it until recently.

It is functionally equivalent to this:

const cacheNames = await caches.keys();

let response;

for (const cacheName of cacheNames) {
  const cache = await caches.open(cacheName);
  response = await cache.match(request);

  if (response) {
    return response;
  }
}

Personally, I always preferred caches.match() and didn’t have any issues with it, but you may run into subtle bugs with it.

The problem is that caches.match() tries to find a response in all caches that the service worker controls. This doesn’t have to be a problem per se, but if you have versioned cache names (you should!) and your PWA doesn’t take good care of cleaning up outdated caches, it may serve content from an old cache.

Imagine your PWA has a cache named my-pwa-cache-123 where 123 is the version number. If you release a new version and the version number becomes 124, the name of the new cache will be my-pwa-cache-124.

But if your PWA doesn’t correctly delete the cache my-pwa-cache-123, you end up with two caches: my-pwa-cache-123 and my-pwa-cache-124.

If you now call caches.match() to look for a response, it will look in both caches, and it may pick a possibly outdated response from my-pwa-cache-123.

Your PWA should, of course, take care of deleting any outdated caches, but if this fails for whatever reason, caches.match() may return an outdated response. So for that reason, it’s better to use cache.match(), even if it’s a little more code.

Ship A PWA Users Can Trust

I recently launched PWA Today, an automated auditing service for progressive web apps.

When you deploy a new version of your PWA, you want to have the confidence that it doesn't quietly break offline support, serve stale files, or leave the service worker stuck somewhere in its lifecycle.

The PWA Today Runtime Audit helps you make sure your PWA looks, feels, and behaves like a real app. It finds runtime failures under real-world conditions, before your users do.

It checks:

• if your PWA is installable

• if it works offline, including a cold start while offline

• if URLs you configure still work when the app is offline

• if it continues to work correctly after an update, online and offline

• if the service worker continues to serve the correct content after an update

• if requests that were made while offline are retried when the app is back online

• if the service worker cache is correctly populated after an update and serves the correct content

• if manifest.json has the correct configuration

• if icons and screenshots are reachable and correctly configured

• if your PWA contains all other configurations to make it look, feel, and behave like a real app

When you purchase a subscription or the prepaid Audit Pack, you get access to the PWA Today Console, where you can view your audit history, configure and schedule audits, and dig deep into the diagnostic output of each audit to analyse the evidence behind each finding.

You can run audits from the console or integrate the audit into your CI/CD pipeline so you can run fully automated audits whenever you release a new version of your PWA.

Find examples of how to integrate the runtime audit into Github, Gitlab, Bitbucket, Azure, CircleCI, and Jenkins on the docs on the PWA Today website.

The console is a PWA itself, so you can install it on your phone or desktop and receive a push notification when an audit completes.

You can start with the free pwa-check CLI tool to run a quick check of your PWA or run a deep analysis using the PWA Runtime Audit.

Share

Modern Web Weekly #77

One of the best features of native apps is that they can capture links within their scope to enable deep linking.

For example, when I have the Instagram app installed on my phone and someone sends me a link to an Instagram post and I click it, it will open the Instagram app instead of a browser.

PWAs also have this capability, but unfortunately, the story of where this works and when is a bit complicated. It differs on various OSes and browsers, so it’s not always easy to know when deep linking will work.

To help understand deep linking into PWAs, I tested all options, and here are my findings.

Web App link handling

Chromium-based browsers like Chrome and Edge support the handle_linksmember of the manifest.json file that enables PWAs to capture links within their scope, which simply means that the URL is within the scope as defined in manifest.json.

So when the scope of a PWA is “https://www.example.com/” and the URL of the clicked link is “https://www.example.com/foo”, then it will be captured by the PWA.

When a PWA wants to use this behavior, the handle_links member should be added to manifest.json:

"handle_links": "preferred"

The handle_links member can hold the following values:

• “preferred”: the user agent should handle links using matching PWAs and may promote link handling behavior.

• “not-preferred”: the user agent should not handle links using matching PWAs and may not promote link handling behavior.

• “auto”: default value if handle_links is not found in the manifest. The user agent may choose between “preferred” and “not-preferred”.

See the explainer for details.

I tested the behavior of this on all platforms in all major browsers by sending a link in an email to myself and then clicking that link.

Android

PWA installed with Chrome
When I click the link in the GMail app or in Chrome, it’s always opened in the PWA, even when Chrome is not the default browser.

When the email is opened in Edge through the GMail website, and I click the link, it opens in Edge but also offers to open it in the PWA:

PWA installed with Edge
When I click the link in the GMail app, the link is not opened in the PWA but in an in-app browser powered by the default browser:

When the email is opened in any browser through the GMail website, and I click it, it’s opened in the same browser that the GMail website was opened with.

PWA installed with Firefox
Here, the behaviour is the same as when the PWA is installed with Edge: when I click the link in the GMail app, the link is not opened in the PWA but in an in-app browser powered by the default browser.

Conclusion for Android: capturing links clicked in other apps only works reliably when the PWA is installed with Chrome.

iOS

On iOS, there is unfortunately no support for deep linking. All clicked links open in the default browser, regardless of whether a PWA is installed and with which browser.

ChromeOS

On ChromeOS, the PWA can only be installed with Chrome, and deep linking works reliably.

macOS

PWA installed with Chrome
When I click the link in the Mail app, it opens in the default browser. When it’s opened in Chrome, it offers to open it in the PWA instead:

When I click the link on a website inside a Chrome tab that’s not the domain of the PWA, it opens in the PWA. Interestingly, there is an app setting in addition to handle_links to define if links should open in the app or Chrome.

You can access the app settings for a PWA by opening the PWA and clicking the triple-dot menu in the top-right corner, and then clicking “App Info”:

In the App Info menu, click Settings:

This will open a new tab in Chrome where you can set whether or not links should open in the app or Chrome:

Currently, this setting overrides handle_links when it has the value “preferred”, so when you set handle_links to “preferred” to open links in the app, but choose “Open in Chrome Browser” for this setting, links will no longer open in the app.

Even worse, when handle_links has the value “not-preferred” or “auto” or is not even present in manifest.json, links will always open in the browser, and this setting has no effect.

To complicate matters further, when an in-scope link is opened in Chrome while the app (without handle_links in its manifest.json) is installed, a button will show in the address bar to open the link in the app instead:

When users click this button, the link will open in the app, and a dialog will show up to inform them that there is a setting to make links open in the app:

But unless handle_links has the value “preferred”, the setting has no effect, which is confusing.

When an installed app does have handle_links in its manifest.json and an in-scope link is opened in Chrome, the button to open the link in the app will also show in the address bar. When the user clicks this link, and the app opens, a similar alert will show in the app to inform users of the link-capturing setting:

When the email is opened in any browser other than Chrome through the GMail website, and I click it, it’s opened in the same browser the GMail website was opened with.

PWA installed with Edge
When I click the link in the Mail app, it opens in the default browser. When it’s opened in Edge, it offers to open it in the PWA instead:

Web app added to Dock with Safari
When I click the link in the Mail app, it opens in the default browser. When it’s opened in Safari, it offers to open it in the web app added to the Dock instead:

But when the web app that was added to the Dock has been interacted with for a while, most notably, when it has been opened directly from the Dock at least once, clicked links open in the web app consistently.

On macOS, PWAs can’t be installed with Firefox.

Conclusion for macOS: capturing links clicked in other apps only works reliably when the web app is added to the Dock with Safari. Chrome can only capture links that are clicked in a Chrome browser tab.

Windows

PWA installed with Chrome
When installed with Chrome on Windows, the behavior is the same as on macOS, so in-scope links are captured when clicked in Chrome and handle_links has been added to manifest.json with the value “preferred” and it can be overridden in app settings in that case.

In-scope links clicked in other apps are not captured.

PWA installed with Edge
A PWA installed with Edge captures in-scope links when clicked in another tab in Edge, but there is no setting to override this.

In-scope links clicked in other apps are not captured.

On Windows, PWAs can’t be installed with Firefox.

Conclusion for Windows: PWAs installed through Chrome and Edge can only capture links clicked inside browser tabs.

Push notifications

Another important feature for PWAs is to open the PWA when a push notification is clicked.

On iOS and Android, the installed PWA is consistently opened when a push notification is tapped, even when the PWA is not running at that moment. The notificationclick event is fired when the notification is tapped, so it can open a URL that is defined in the notification payload.

When no nofiticationclick event handler is defined and the notification is tapped, the URL defined in the start_url property of manifest.json is opened on iOS. On Android, nothing happens in this case.

In the following example, the URL to open is specified in the data property of the notification:

self.addEventListener(’notificationclick’, async (e) => {
  //read the notification object from the event
  const {notification} = e;

  // read the data property of the notification
  const {data} = notification;

  // close the notification
  notification.close();
  
  // open the url specified in the “url” member of the data property
  // this needs to be wrapped in the “waitUntil” method of the event 
  // to make sure the service worker stays active long enough
  e.waitUntil(clients.openWindow(data.url))
});

Check https://whatpwacando.today/notifications for an example of the notification payload.

pwa-check v0.0.9 released

Version 0.0.9 of pwa-check now lists priority, impact, and a fix when it lists a warning or failure for your PWA. This means you can now get an actionable and prioritized report that you can immediately act on.

pwa-check helps you make sure your PWA looks, feels, and behaves like a real app.

You provide it the URL of the PWA you want to test and pwa-check scans the HTML, manifest, scripts, and service worker, then points straight at the gaps that will hurt installability or offline behavior.

Share

Modern Web Weekly #76

Is your web app actually ready to be installed, work offline, and behave like a real PWA?

Let pwa-check answer that for you.

I created pwa-check to help you make sure your PWA looks, feels, and behaves like a real app.

You provide it the URL of the PWA you want to test and pwa-check scans the HTML, manifest, scripts, and service worker, then points straight at the gaps that will hurt installability or offline behavior.

Install it:

npm i @pwa-today/pwa-check

then run it using npx:

npx pwa-check https://whatpwacando.today

or, if you install it globally, directly:

pwa-check https://whatpwacando.today

It then does a thorough audit of your PWA to make sure it:

• meets the installability criteria

• provides icons in all recommended sizes

• provides screenshots with correct configuration and sizes for the enhanced installation dialog

• provides other recommended members in its manifest, like share_target, file_handlers, orientation, handle_links and others

• has a correct viewport meta tag

• registers a service worker that caches assets and has the required event handlers

• provides iOS and iPadOS startup images

• follows other best practices

You can use pwa-check as a standalone CLI tool or as part of your CI/CD pipeline. It returns a non-zero exit code on any failures, or you can make it fail on any warning by passing the —-fail-on-warn flag:

pwa-check https://whatpwacando.today --fail-on-warn

Use —-json for JSON output and —-timeout <ms> to put a timeout on each network request (like fetching icons and screenshots):

pwa-check https://whatpwacando.today --json --timeout 500

I intend to add more checks in the future so give it a spin and let me know what you think or if it’s still missing something.

Check the pwa-check repo on GitHub.

Safari Tech Preview 247 now ships an MCP server

If you’re using AI in your coding workflow (and who doesn’t these days?), you can now ask your agent to run and debug web apps in Safari using the Safari MCP server.

The server is available in Safari Tech Preview 247 and can be enabled through Develop > Developer Settings > Allow remote automation and external agents.

If you use Codex, you can use the following command to add the Safari MCP server:

codex mcp add safari-mcp-stp -- "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp

For Claude, use:

claude mcp add safari-mcp-stp -- "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver" --mcp

For other agents, add the following to mcp.json or config.json:

"safari-mcp-stp": {
  "command": "/Applications/Safari Technology Preview.app/Contents/MacOS/safaridriver",
  "args": ["--mcp"] 
}

After this, you can prompt your agent to run your web app in Safari. For a list of currently available commands, check the WebKit Blog article.

New PWA installation dialog in Chrome 152

Chrome 152 ships with some interesting changes to the web app installation dialog.

The first dialog now shows a “Learn More” button that links to a Google support page that explains PWAs and a “Next” button:

When you click the “Next” button, a second dialog is shown that illustrates where the web app will be installed (Chrome Canary Apps in this case), which is more aligned with the dialog that is shown when a native app is installed on macOS:

After the app is installed, a success dialog is displayed that contains an “Open tab in app” button to directly open the currently open browser tab in the installed PWA:

Oh, and there’s more good stuff in Chrome 152…

PWA notification attribution on macOS

If you have tested push notifications in an installed PWA on macOS, you probably noticed that the notifications contained a Chrome logo instead of the logo of the PWA:

Starting in Chrome 152 on macOS, push notifications will be attributed to the PWA itself instead of Chrome. This means that if you include an icon in the push notification options, this will be shown instead of the Chrome logo:

To set an icon, pass it in the icon key in the options for showNotification() in the push event handler:

self.addEventListener('push', e => {
  e.waitUntil((async () => {
    const options = {
      body: 'Hi, this is a notification',
      icon: '/src/img/icons/icon-512x512.png',
      
      // other options
    };

    await self.registration.showNotification(title, options);

  })());
});

This does introduce two behavioral changes on macOS for installed PWAs:

• the requireInteraction option for showNotification will no longer be supported, as on macOS, this is a per-app setting controlled by the user rather than a per-notification setting controlled by the app

• the Badging API will now require separate permission

For Chrome 152, you will need to use Chrome Canary at the time of writing, and you need to enable the Mac PWA notification attribution flag at chrome://flags/#enable-mac-pwas-notification-attribution

When Chrome 152 is released, this will be enabled by default.

Do you need help with your web app?

Book a 1-on-1 call with me and I will do my absolute best to answer all your questions and solve your problems.

€100 for one hour, money-back guarantee if you’re not satisfied.

Book a call now

Share

Modern Web Weekly #75

I updated my push notifications demo, which now shows a badge on the app icon with the number of unread push notifications using the Badging API.

This API is supported in Chrome, Edge, and Safari and is typically used in conjunction with the “push” event handler in a service worker. It consists of two methods on the navigator object, setAppBadge and clearAppBadge:

// sets a badge with the number 3
navigator.setAppBadge(3)

// clears the badge
navigator.clearAppBadge()

// also clears the badge
navigator.setAppBadge(0)

// sets a badge with a dot
navigator.setAppBadge()

Badges are typically shown when notifications are unread, and in the demo of What PWA Can Do Today, I chose to show badges when the PWA is not running:

When the PWA is opened and then moved to the background, the badge will be cleared on iOS. On Android, the badge can only be cleared when the notifications are clicked or cleared.

In the “push” event handler, I show the notification and then check if the service worker has active clients, which means apps that are not in the background or not running. If this is not the case, the badge is either set or, when it’s already shown, the number of unread notifications is incremented:

e.waitUntil(
    self.registration.showNotification(title, options)
    .then(hasActiveClients)
    .then((activeClients) => {
      if(!activeClients) {
        updateBadges();
      }
    })

Here’s the implementation of hasActiveClients:

const hasActiveClients = async () => {
  const clients = await self.clients.matchAll({
    includeUncontrolled: true,
  });

  return clients.some(({visibilityState}) => 
    visibilityState === ‘visible’);
};

The number of unread notifications is stored in IndexedDB and is updated in the updateBadges function:

const updateBadges = async (inc = 1) => {

  // open the IndexedDB store
  const store = await openStore('badgeStore', ‘readwrite’);

  // get the number of unread notifications or 0 if not stored
  const result = await store.get(’num’) || {num: ‘num’, count: 0};
  
  // get the current number of unread notifications and increment it 
  // by the "inc" argument (1 if not given)
  const numBadges = result.count;
  const count = Math.max(0, numBadges + inc);

  // store the updated number
  await store.put({num: ‘num’, count});

  // set the badge number
  navigator.setAppBadge(count);
}

For brevity, I omitted the implementation of openStore, but you can find it here.

Using the native close mechanism with CloseWatcher

Many UI components have some sort of “modal” or “popup” behavior, like <dialog>, a drawer or a context menu. Usually, these components are easy to close with the device’s native closing mechanism. On desktop, this is usually the ESC key, on Android, this is usually the Back button or swiping to the right from Android 10 on, on iOS with VoiceOver enabled, it’s the “z” key, and game consoles also provide specific buttons as their closing mechanism.

If you’ve ever tried to provide a uniform way for all these devices to close a UI component, you know this is tedious and complex to implement. You would first have to assert the type of device you’re dealing with and then select the appropriate action that would close the element. When new devices emerge, you’d have to add support for these as well, which makes this into a moving technical target that’s hard to hit.

Enter CloseWatcher.

This object abstracts the device-specific closing mechanisms away and provides a uniform API for web apps to respond to these closing actions. Whenever such an action is invoked (ESC key, Back button, etc.), CloseWatcher delivers a cancel event followed by a close event that web apps can listen for to close the UI component.

You can simply create a CloseWatcher and then listen for the cancel and close events:

const watcher = new CloseWatcher();

watcher.addEventListener('cancel', e => {
  // respond to the cancel event    
});

watcher.addEventListener('close', (e) => {
  // respond to the close event
});

The cancel event gives a web app an opportunity to prevent the closing of the UI component based on some condition, for example, when the user has unsaved changes. By calling e.preventDefault(), the close event will not fire:

watcher.addEventListener('cancel', e => {
  if(hasUnsavedChanges) {
    // prevent the close event from firing
    e.preventDefault();    
  }
});

watcher.addEventListener('close', (e) => {
  component.close();
});

It’s important to understand that the CloseWatcher instance is a one-off component; after the close event is fired, the watcher is destroyed. It also provides two methods to fire the events:

• close(): fires the close event

• requestClose(): fires the cancel event and then the close event, unless e.preventDefault() was called in the cancel event

For this reason, a new CloseWatcher needs to be created every time its close event was fired.

In the following example, we create a sidebar that is opened with a button. Inside its click handler, we instantiate a new CloseWatcher and listen for the close event to close the sidebar.

We also provide a button to close the sidebar. Inside the click handler for the close button, we call requestClose() so closing the sidebar always happens through the event handler for the close event:

const sidebar = document.querySelector('.sidebar');
const openButton = document.querySelector('.open-button');
const closeButton = document.querySelector('.close-button');

openButton.addEventListener('click', () => {
  // open the sidebar
  sidebar.classList.add('open');

  // create a new watcher
  const watcher = new CloseWatcher();
  
  // closes the sidebar when the close action is invoked
  watcher.addEventListener('close', (e) => {
    // close the sidebar
    sidebar.classList.remove('open');
  });

  // calls requestClose() so the cancel and close events are fired
  // this makes sure closing the sidebar only happens in one place: the event handler for
  // the close event
  closeButton.onclick = () => watcher.requestClose();
});

We can now also add a handler for the cancel event to warn the user that there are unsaved changes and prevent the sidebar from closing. We can also add a save button that saves the changes and closes the sidebar. Inside its click handler, we call close() instead of requestClose() because we don’t need to fire the cancel event:

const sidebar = document.querySelector('.sidebar');
const openButton = document.querySelector('.open-button');
const closeButton = document.querySelector('.close-button');
const saveButton = document.querySelector('.save-button');

openButton.addEventListener('click', () => {
  // open the sidebar
  sidebar.classList.add('open');

  // create a new watcher
  const watcher = new CloseWatcher();
  
  
  watcher.addEventListener('cancel', e => {
    if(hasUnsavedChanges) {
      // prevents the close event from firing when there are unsaved changes
      e.preventDefault();
    }
  });

  // closes the sidebar when the close action is invoked
  watcher.addEventListener('close', (e) => {
    // close the sidebar
    sidebar.classList.remove('open');
  });

  // calls requestClose() so the cancel and close events are fired
  // this makes sure closing the sidebar only happens in one place: the event handler for
  // the close event
  closeButton.onclick = () => watcher.requestClose();

  // calls close() so only the close event is fired, cancel event is not needed
  // this makes sure closing the sidebar only happens in one place: the event handler for
  // the close event
  saveButton.onclick = () => {
    saveChanges();
    watcher.close();
  }
});

Another important thing to know is that the cancel event can only be canceled once. This is to prevent abuse by trapping the user in not being able to close the sidebar. This means you can only alert the user once when there are unsaved changes. If you want to alert the user as long as there are unsaved changes, you’ll need to use another mechanism.

In one way, this is a bit unfortunate, but the restriction is understandable to prevent abuse.

Check out the CloseWatcher demo.

Do you need help with your web app?

Book a 1-on-1 call with me and I will do my absolute best to answer all your questions and solve your problems.

€100 for one hour, money-back guarantee if you’re not satisfied.

Book a call now

Share

Modern Web Weekly #74

Did you ever wish you could serve some parts of your HTML earlier or later than others?

Imagine your web app has a large dropdown menu at the top of the page. Since HTML is delivered in a top-to-bottom fashion, the HTML after this menu won’t be available until the HTML for the menu is downloaded and parsed, but the user won’t be able to use the menu until the page becomes interactive. The menu HTML might as well be delivered later so the rest of the page is available sooner.

Or how about a single-page app with a page shell. This shell is delivered in the first request, and then JavaScript is needed to plug in all other HTML.

Wouldn’t it be nice if you could do this in one request and choose the order in which the HTML parts are delivered, regardless of their order in the source document?

Well, now you can! 💪

Out-of-order streaming HTML

There have already been some experiments with out-of-order streaming HTML that use Declarative Shadow DOM and <slot> elements to stream HTML out of order:

<div>
  <template shadowrootmode="open">
    <header>Header</header>
    <main>
      <slot name="content"></slot>
    </main>
    <footer>Footer</footer>
  </template>

  <div slot="content">
    This div will be rendered inside the slot above without JavaScript.
  </div>
</div>

In the above example, <slot name=”content”></slot> will be replaced with <div slot=”content”> as soon as it’s available in the browser, without any JavaScript.

This is a very neat feature, but it only works with Shadow DOM.

In Chrome 148, with experimental web features enabled (visit chrome://flags/#enable-experimental-web-platform-features), you can now use Declarative Partial Updates that enable web apps to stream HTML into parts of the document, regardless of the order in which it’s delivered by the server.

For example, web apps can now download the most important HTML first, even when this is not at the top of the HTML document.

How it works

Streaming out-of-order HTML is called “patching”. It means you can interleave content for multiple locations in an HTML document in one HTML stream, and the content doesn’t have to be streamed in the order in which it’s located in the document, hence “out-of-order streaming”.

It works by putting processing instructions in an HTML document that function as the insertion points where the content will be streamed into:

<div>
  <?marker name="content">
</div>

<template for="content">
  <p>Here is the content that will be inserted.</p>
</template>

In the above example, the processing instruction <?marker name=”content”> will be replaced with the contents of the <template>.

The template will look up the processing instruction with a name attribute that corresponds to its for attribute and replace it with its contents.

The above example will end up like this:

<div>
  <p>Here is the content that will be inserted.</p>
</div>

In addition to <?marker>, you can also use the <?start> and <?end> markers that enable you to add temporary content that will be displayed until it’s replaced with the contents of the corresponding <template> element:

<div>
  <?start name="list">
  Loading…
  <?end>
</div>

...

<template for="list">
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
  </ul>
</template>

In this example, “Loading…” is displayed inside the <div> until it’s replaced with the list inside the <template> element.

This would enable you to first stream a skeleton HTML page with a loading screen, and after that you could append the list HTML, which is maybe fetched from an external API that takes longer to load.

Normally, you would first serve the app shell, then fetch the list with the API data in a separate request, and then use JavaScript to insert the list HTML. With patching, you can do everything in a single HTML response without having to use JavaScript to insert the list.

You can even add processing instructions in the templates to enable updates in multiple steps. Imagine that the list in the previous example is loaded in chunks instead of fully in one request. By including processing instructions in the templates, you can now continuously update the list:

<div>
  <?start name="list">
  Loading…
  <?end>
</div>

...

<template for="list">
  <ul>
    <li>Item 1</li>
    <?marker name="items">
  </ul>
</template>

<template for="items">
  <li>Item 2</li>
  <li>Item 3</li>
  <?marker name="items">
</template>

<template for="items">
  <li>Item 4</li>
  <?marker name="items">
</template>

This results in the following HTML:

<div>
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
    <li>Item 3</li>
    <li>Item 4</li>
    <?marker name="items">
  </ul>
</div>

This is huuuuge…

…and there’s even more…

Streaming HTML in single-page apps

Single-page apps (SPA) have long been the solution to make web apps feel like real apps, because they only update the changed content when the user navigates to another page, without a full page reload.

The downside of this is that SPAs can’t use the browser’s streaming parser. When a browser loads a web page, it can do so in a streaming fashion. This means that it can already start rendering the page while it’s still downloading; it doesn’t have to wait for the page to be fully loaded before it can start rendering content.

SPAs typically load a skeleton HTML page and then update the content with DOM manipulation using JavaScript. Any content that is inserted into the DOM after the page has been served by the server cannot use the browser’s streaming parser. It has to wait for all content to be ready before it can start to render it when it’s inserted using JavaScript (for example, with innerHTML).

Until now…

New streaming methods

In addition to existing methods like setHTML, setHTMLUnsafe and the innerHTML and outerHTML setters, this proposal adds streaming methods like streamHTML, streamHTMLUnsafe, streamAppendHTML etc.

This enables SPAs to stream HTML into the insertion points marked by processing instructions using JavaScript. This means that instead of using innerHTML to update content, your SPA can now do this:

const response = await fetch('/path/to/content.html');
const html = await response.text();

const writer = document.body.streamAppendHTMLUnsafe().getWriter();

await writer.write(html);
await writer.close();

Note that in this example, the content is added to the <body> element.

When you use <template> elements and markers, you don’t even need to get a reference to the insertion point with JavaScript anymore. You can just define the insertion point of the SPA content with a marker:

<main id="app">
  <section class="page">
    <?marker name="content">
  </section>
</main>

And then you can simply append the <template> to the bottom of the page:

<template for="content">
<?start name="content">
  <p>Homepage content</p>
<?end>
</template>

Since you defined a marker and added this template to the bottom of the page, the browser will now take care of inserting the content in the right place. Also note that this template contains <?start> and <?end> markers, and the resulting HTML will be this:

<main id="app">
  <section class="page">
    <?start name="content">
      <p>Homepage content</p>
    <?end>
  </section>
</main>

This ensures that the processing instructions are ready for when the user navigates to another page. If each partial contains these processing instructions, you can always just add the page HTML to the bottom of the page, and the browser will then insert it in the right location while replacing the contents of the previous page.

And there’s even more good news…

Cross-browser support is coming soon

Not only can you already use this in Chromium-based browsers from version 148 with experimental web features enabled, but the WebKit team (Safari) has announced they will support this and the Firefox team has a positive position on this feature.

This means this feature could be supported in all major browsers soon! 💪

Demo

I created a demo SPA that uses the technique described above to update the page content. It defines markers in the HTML where the page content is to be inserted, and each page partial HTML template contains new markers where the content of the next page is to be inserted. All page templates are simply added to the bottom of the page, and the browser takes care of the rest.

Check out the demo and the source code.

Notice that the demo uses the streamAppendHTMLUnsafe() method to stream the content. The Unsafe variant is required to preserve the <template> element in the HTML that is inserted. Using streamAppendHTML()results in empty HTML and doesn’t work.

Also notice that the streaming methods are required to use templates and markers. When you use non-streaming methods, like appendHTMLUnsafe() for example, the parent of the template when it is parsed is an intermediate document fragment, and the patching happens "in place" inside the fragment instead of in the insertion point indicated by the markers.

The /list route of the demo demonstrates a list that is updated in chunks. The demo just uses setTimeout() to simulate a response that delivers the chunks, but you can probably imagine how this would work in a production scenario where the content is delivered in real chunks.

Also make sure to check out the Chrome developers article and the accompanying demo, which demonstrates the out-of-order streaming very well.

This is a very promising feature that will truly revolutionize how HTML is delivered. When more browsers support this, you will hear it here first!

Do you need help with your web app?

Book a 1-on-1 call with me and I will do my absolute best to answer all your questions and solve your problems.

€100 for one hour, money-back guarantee if you’re not satisfied.

Book a call now

Share

Modern Web Weekly #73

The File System Access API brings access to the native file system to web apps. The API is currently only supported in Chromium-based browsers on desktop, but the Origin Private File System is now supported across all browsers on desktop, Android, and iOS.

The Origin Private File System (OPFS) is a high-perfor…

Read more

Share

Modern Web Weekly #72

Firefox 151 now supports the Document Picture-in-Picture API after support already landed in Chromium-based browsers last year.

The Document Picture-in-Picture API enables web apps to populate a picture-in-picture window with arbitrary HTML content. This means that you can place custom controls to control a video in a picture-in-pict…

Read more

Share

Modern Web Weekly #71

If you want to use encryption in your web app to encrypt and decrypt sensitive data, you can use the Web Crypto API to generate an public and private key:

const { publicKey, privateKey } = await window.crypto.subtle.generateKey(
  {
    name: "RSA-OAEP",
    modulusLength: 4096,
    publicExponent…

Read more

Safari Tech Preview now supports the improved attr() function

After Chrome, Safari Tech Preview 241 now also supports the improved attr() function. This function can read any attribute from the element it’s applied to. Using its output however, was limited to the CSS content attribute, but now you can use it in conjuncti…

Read more

How to install a PWA with Samsung Internet Browser

I found a report on Reddit this week that pointed to issues with installing PWAs through Samsung Internet Browser on Android.

Some PWAs were flagged as “unsafe” by Google Play Protect, and others, including my What PWA Can Do Today, simply failed silently when trying to install. In that case, a message wo…

Read more

Customisable <select> now in Safari Tech Preview 238

After Chrome, Safari has now also implemented the fully customisable <select> element in Tech Preview 238. This means we can now fully style this element, which was barely possible before.

To opt-in to the new customizable <select> add this to your CSS:

select,
::picker(select) {
  appearance: base-selec…

Read more

A declarative install element

In Modern Web Weekly #65 and #59, I wrote about the Web Install API (now stable in Chrome 144!) that adds the install method to navigator and that enables web apps to be installed as PWAs, also from other domains.

Chrome 147 now also introduces an origin trial for the declarative <install> ele…

Read more

Can I compress it? Yes, you can!

If your web app needs to compress and decompress data, you no longer need an external library. The Compression Streams API is now available in all browsers and enables your app to (de)compress data using GZIP a…

Read more

Web Install API now in Chrome 143

Chrome 143 now supports the Web Install API as an origin trial.

This API provides a declarative way of installing web apps through navigator.install().

When it’s called without arguments, it installs the current web app (the one on the domain where this method is called from:

// installs the current web app
navigator.instal…

Read more

Better drag-and-drop with Observer

If you’ve ever built drag-and-drop functionality, you know that this can be tricky to implement and can result in brittle code that’s hard to follow.

You need to implement a handler for the mousemove event, but this handler should only be called when it’s preceded by a mousedown event on the element that needs to be drag…

Read more

CMA designates Apple as having Strategic Market Status

The Open Web Advocacy (OWA) reports that the UK’s Competition and Markets Authority (CMA) has officially designated Apple as having Strategic Market Status (SMS).

SMS means that Apple “has substantial and entrenched market power and a position of strategic significance”. It means that Apple’s iOS plat…

Read more

What We Need To Make Web Apps A Success

We don’t need to wait for Apple to jump on board

Here’s a fun experiment: put your phone in flight mode so there’s no internet connection, and make sure it’s not connected to wifi either.

Read more

Taming the on-screen keyboard with interactive-widget

In Chromium-based browsers, you can now control how the layout of the page behaves when the on-screen keyboard is shown on mobile devices.

Different browsers behave differently when the on-screen keyboard is shown. They can resize the Layout Viewport, the Visual Viewport,…

Read more

iOS 26 for PWAs: The Good, the Bad, and the Ugly

iOS 26 has arrived, and of course, I combed through the release notes and did a lot of testing to see what has changed for PWA support.

In short, there is unfortunately not too much to be excited about, but let’s start with the good news.

Read more

Install your PWA from anywhere

The dev trial for Microsoft’s proposal for the Web Install UI is now live.

This API adds the install method to navigator to install a web app on the user’s device. When navigator.install() is called without any arguments, the browser will prompt to install the current web app, meaning the web app ho…

Read more