Welcome to Worker, the Service Worker for the Land Code Editor that enhances web application performance and reliability through advanced caching, offline support, and a unique strategy for handling dynamic CSS imports from JavaScript modules.

Worker is engineered to:

1. Implement Asset Caching: Provide multiple caching strategies including network-first for navigation and cache-first for static assets.
2. Enable Offline Support: Allow the application shell and cached assets to function without network connectivity.
3. Handle Dynamic CSS Loading: Intercept JavaScript CSS imports and respond with JavaScript modules that trigger standard tag loading.
4. Support Automatic Updates: Detect new Service Worker versions and prompt clients to reload for seamless updates.

This repository contains a Service Worker designed to enhance web application performance and reliability through advanced caching, offline support, and a unique strategy for handling dynamic CSS imports originating from JavaScript modules.

• Asset Caching: Implements multiple caching strategies:

  • Core Cache (CACHE_CORE): Stores essential application shell files and critical scripts (like /Application/, Register.js, Load.js). Uses a network-first strategy for navigation requests to ensure users get the latest page structure if online, falling back to the cache when offline. Pre-caches essential assets on install.
  • Asset Cache (CACHE_ASSET): Stores static application assets (/Static/Application/*), including JavaScript, images, and the actual CSS files. Uses a cache-first strategy for fast loading. Also stores the dynamically generated JavaScript modules used for CSS loading (see below).

• Offline Support: Leverages the caches to allow the application shell and cached assets to function offline.

• Dynamic CSS Loading: Intercepts JavaScript import statements for specific CSS files and responds with a JavaScript module that triggers the loading of the actual CSS via a standard tag.

• Automatic Updates: Detects when a new version of the Service Worker is activated and prompts the client (via Register.js) to reload the page, ensuring the user gets the latest application version seamlessly.

• Client Control Management: The Register.js script ensures the Service Worker gains control of the page, potentially reloading the page once after the initial registration if necessary.

  ---

  System Architecture Diagram

  This diagram illustrates Worker's service worker caching and CSS loading strategy.

  sequenceDiagram
  classDef sw fill:#f9f,stroke:#333,stroke-width:2px;
  classDef client fill:#9cf,stroke:#333,stroke-width:2px;
  classDef cache fill:#cfc,stroke:#333,stroke-width:1px;
  
  participant Client as Client (Browser):::client
  participant SW as Service Worker:::sw
  participant CoreCache as CACHE_CORE:::cache
  participant AssetCache as CACHE_ASSET:::cache
  
  Client->>SW: Fetch /Application/ (navigation)
  SW->>CoreCache: Network-first strategy
  CoreCache-->>SW: Return cached shell or network
  
  Client->>SW: Import /Static/Application/*.css
  SW-->>Client: Respond with JS module (load CSS via link)
  Client->>Client: Execute JS, call window._LOAD_CSS_WORKER
  Client->>Client: Create with ?Skip=Intercept
  Client->>SW: Fetch CSS with ?Skip=Intercept
  SW->>AssetCache: Cache-first for CSS
  AssetCache-->>SW: Return CSS content
  SW-->>Client: CSS applied
  

  Loading

  ---

  Usage: Dynamic CSS Loading via JS Module Response

This worker implements a specific strategy to handle dynamic CSS imports from JavaScript modules (e.g., import './some-styles.css';) located under the /Static/Application/ path. Instead of relying on postMessage coordination, it directly responds to the initial import request with JavaScript code that initiates the standard browser CSS loading mechanism.

The Workflow:

1. Initial JS Import: A JavaScript module in your application attempts to import a CSS file located under /Static/Application/ (e.g., /Static/Application/CodeEditorLand/component.css).
2. Service Worker Intercept #1: The worker's fetch listener intercepts this request. Because the URL matches the pattern /Static/Application/*.css and doesn't contain the special ?Skip=Intercept parameter, it proceeds with the CSS handling logic.
3. Service Worker Responds with JS: The worker immediately responds to the fetch request with a dynamically generated JavaScript module (Content-Type: application/javascript; charset=utf-8). The content of this module is similar to:
   window._LOAD_CSS_WORKER("/Static/Application/CodeEditorLand/component.css");
   export default {};
   This JavaScript response is then cached in CACHE_ASSET using the original CSS request URL as the key.
4. Browser Executes JS: The browser receives and executes this JavaScript module. The export default {}; satisfies the expectation of the original import statement.
5. Client Function Call: The executed JavaScript calls the globally available window._LOAD_CSS_WORKER function (which must be defined beforehand by including Load.js).
6. Client Modifies URL & Creates : The _LOAD_CSS_WORKER function appends the ?Skip=Intercept query parameter to the received CSS URL (e.g., /Static/Application/CodeEditorLand/component.css?Skip=Intercept). It then creates a standard tag, setting its href to this modified URL, and appends it to the document's .
7. Browser Fetches CSS: The browser sees the new tag and initiates a second fetch request for the CSS file, this time using the URL with the ?Skip=Intercept parameter.
8. Service Worker Intercept #2: The worker intercepts this second request.
9. Service Worker Serves CSS: The worker detects the ?Skip=Intercept parameter. It bypasses the JS generation logic and proceeds to fetch the actual CSS content using a cache-first strategy against CACHE_ASSET (looking for the URL including the parameter in the cache, or fetching from the network). It responds with the real CSS content (Content-Type: text/css).
10. Browser Applies Styles: The browser receives the actual CSS and applies the styles as expected.

This two-step fetch process, initiated by the SW's JavaScript response and distinguished by the Skip=Intercept parameter, allows the initial JavaScript import to resolve quickly while triggering the standard browser mechanism for loading the actual CSS styles without causing infinite interception loops.

To understand how Worker's service worker implements the dynamic CSS loading strategy, see the following source files:

• Worker.js - Main service worker with caching strategies
• Register.js - Service worker registration and update handling
• CSS/Load.js - Client-side CSS loader function (window._LOAD_CSS_WORKER)

The source files explain the two-step fetch process, cache-first strategies for assets, and the ?Skip=Intercept parameter pattern for avoiding infinite loops.

This example shows how to integrate the necessary client-side scripts and the Service Worker registration within an HTML page (.html file).

index.html (or your main layout/page):

See CHANGELOG.md for a history of changes to this component.

This project is released into the public domain under the Creative Commons CC0 Universal license. You are free to use, modify, distribute, and build upon this work for any purpose, without any restrictions. For the full legal text, see the LICENSE file.

Stay updated with our progress! See CHANGELOG.md for a history of changes specific to Worker.

Worker is a core element of the Land ecosystem. This project is funded through NGI0 Commons Fund, a fund established by NLnet with financial support from the European Commission's Next Generation Internet program. Learn more at the NLnet project page.

Project Maintainers: Source Open (Source/Open@Editor.Land) | GitHub Repository | Report an Issue | Security Policy