The Service Worker for Land - asset caching, offline support, and dynamic CSS loading 🏞️

Web applications that lose authentication state on network drops force users to re-authenticate. Tokens stored in plaintext are accessible to any script running on the page.

"Offline-capable. Auth tokens encrypted. Auto-refreshed."

Worker is 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. It intercepts fetch events within the Tauri WebView through policy-based routing, serving cached assets and generating CSS-loader JavaScript shims on the fly.

Web applications that lose connectivity force users to stare at blank screens and re-authenticate. Worker solves this by implementing multiple caching strategies (network-first for navigation, cache-first for static assets) and encrypting authentication tokens at rest in cache storage - no script on the page can read them.

Worker is engineered to:

1. Implement Multi-Strategy Asset Caching - network-first for navigation requests (always fresh app shell), cache-first for static assets under /Static/Application/*, and automatic pre-caching of essential resources on service worker install.
2. Enable Full Offline Support - Serve the entire application shell and all cached assets without network connectivity, with transparent fallback through the Cache Storage API.
3. Handle Dynamic CSS Loading - Intercept JavaScript import of CSS modules and respond with generated JavaScript that triggers standard <link> tag injection, bypassing the browser's restrictions on dynamic CSS imports.
4. Support Automatic Updates - Detect new Service Worker versions, validate Trusted Types policy, and prompt clients to reload for seamless version transitions without data loss.

Core Cache (CACHE_CORE) - Network-first strategy for navigation requests under the /Application scope. Pre-caches essential assets on install and falls back to cache when the network is unavailable, ensuring the application shell always loads.

Asset Cache (CACHE_ASSET) - Cache-first strategy for static resources under /Static/Application/*. Stores JavaScript, CSS, images, fonts, and dynamically generated JS modules (the CSS-loader shims) with version-aware cache keys tied to build increments.

Dynamic CSS Loading Pipeline - Two-pass interception system that transforms import './styles.css' into a <link rel="stylesheet"> tag without infinite loops. Pass 1 intercepts the CSS import and returns a JavaScript shim calling window._LOAD_CSS_WORKER. Pass 2 detects the ?Skip=Intercept query parameter and serves the real CSS from cache.

Trusted Types Integration - Full CSP-compatible Trusted Types enforcement through a dedicated WorkerApplication policy. Service worker script URLs are validated against a regex allowlist before being passed to navigator.serviceWorker.register, preventing DOM XSS via injected SW paths.

PostHog Telemetry Bridge - Dual-pipe telemetry (PostHog capture + OTLP traces) from inside the service worker context. Uses the fetch API directly (no Node.js HTTP, no CDN-loaded SDKs - service workers cannot load scripts post-install) with build-baked endpoint and key from import.meta.env.

Increment-Aware Cache Keys - All cache names are tagged with the build increment (Core-{INCREMENT}, Asset-{INCREMENT}), enabling clean cache cut-over on new deployments without stale data from previous versions.

This worker implements a specific two-pass strategy to handle dynamic CSS imports from JavaScript modules (e.g., import './some-styles.css';) located under /Static/Application/.

1. Initial JS Import - A JS module attempts to import a CSS file under /Static/Application/.
2. Service Worker Intercept #1 - The fetch listener intercepts the request. Because the URL matches /Static/Application/*.css and lacks ?Skip=Intercept, it proceeds with the CSS handling logic.
3. Service Worker Responds with JS - The worker responds with a dynamically generated JavaScript module:

   window._LOAD_CSS_WORKER("/Static/Application/CodeEditorLand/component.css");
   export default {};

   This JS response is cached in CACHE_ASSET using the original CSS URL as the key.
4. Browser Executes JS - The browser executes this module. export default {} satisfies the import statement.
5. Client Function Call - window._LOAD_CSS_WORKER is called (defined in Load.ts).
6. Client Modifies URL & Creates <link> - The function appends ?Skip=Intercept to the CSS URL and creates a standard <link rel="stylesheet"> tag in <head>.
7. Browser Fetches CSS - The browser initiates a second fetch with ?Skip=Intercept.
8. Service Worker Intercept #2 - The worker detects ?Skip=Intercept, bypasses JS generation, and serves the actual CSS via cache-first strategy.
9. Browser Applies Styles - The browser receives and applies the real CSS (Content-Type: text/css).

This two-step fetch process, distinguished by the ?Skip=Intercept parameter, allows the initial JavaScript import to resolve quickly while triggering the standard browser mechanism for loading actual CSS without infinite interception loops.

<!DOCTYPE html>
<html lang="en">
	<head>
		<!-- Load the CSS Loader script EARLY -->
		<script src="/Worker/CSS/Load.js" type="module"></script>

		<!-- Set the path to the Service Worker file -->
		<script>
			window._WORKER = "/Worker.js";
		</script>

		<!-- Register the Service Worker -->
		<script src="/Worker/Register.js" type="module"></script>
	</head>

	<body>
		<!-- Load main application script LAST -->
		<script src="/scripts/main-app.js" type="module"></script>
	</body>
</html>

Cache names include the build increment for clean cut-over: Core-{INCREMENT} and Asset-{INCREMENT}.

graph LR
    classDef worker fill:#f0d0ff,stroke:#9b59b6,stroke-width:2px,color:#2c0050;
    classDef client fill:#cce8ff,stroke:#2980b9,stroke-width:2px,color:#003050;
    classDef cache  fill:#d4f5d4,stroke:#27ae60,stroke-width:1px,color:#0a3a0a;
    classDef sky    fill:#9cf,stroke:#2471a3,stroke-width:1px,stroke-dasharray:5 5,color:#001040;

    subgraph SKY["Sky ☀️ - Astro Page (Tauri WebView)"]
        HTMLPage["index.astro loads Load.js + Register.js"]:::sky
        MainApp["workbench JS (dynamic CSS imports)"]:::sky
    end

    subgraph SW["Worker ⚙️ - Service Worker (Worker.ts / Policy.ts)"]
        direction TB
        Register["Register.ts 📋 registration + update detection scope /Application"]:::worker
        Policy["Policy.ts 🛡️ fetch event handler routes by URL pattern"]:::worker
        subgraph CACHES["Cache Storage"]
            CoreCache["CACHE_CORE 🌐 network-first /Application/ navigation"]:::cache
            AssetCache["CACHE_ASSET 📦 cache-first /Static/Application/* CSS + JS"]:::cache
        end
        CSSLoad["Worker/CSS/Load.ts 🎨 window._LOAD_CSS_WORKER client-side link tag injector"]:::worker
        Telemetry["Telemetry/Bridge.ts 📊 PostHog + OTLP SW-level dual-pipe"]:::worker

        Register --> Policy
        Policy --> CoreCache
        Policy --> AssetCache
        CSSLoad --> AssetCache
        Policy --> Telemetry
    end

    HTMLPage -- registers --> Register
    HTMLPage -- defines _LOAD_CSS_WORKER --> CSSLoad
    MainApp -- import .css --> Policy
    Policy -- JS module response export default + _LOAD_CSS_WORKER call --> MainApp
    MainApp -- link rel=stylesheet URL?Skip=Intercept --> Policy
    Policy -- cache-first real CSS --> MainApp

Connection paths:

Element/Worker/
├── Source/
│   ├── Worker.ts                       # Service worker entry: caching strategies, interception logic
│   ├── Worker/
│   │   ├── Policy.ts                   # Trusted Types policy for secure script URL creation
│   │   ├── Register.ts                 # Service worker registration, update detection, activation
│   │   └── CSS/
│   │       └── Load.ts                 # Client-side CSS loader (window._LOAD_CSS_WORKER)
│   ├── Configuration/
│   │   └── ESBuild/
│   │       ├── Worker.ts               # ESBuild build-time configuration
│   │       └── Target.ts               # Target definitions and output path config
│   ├── Telemetry/
│   │   └── Bridge.ts                   # PostHog + OTLP dual-pipe telemetry bridge
│   ├── prepublishOnly.sh               # Build orchestration script
│   └── Run.sh                          # Development watch mode
├── Target/                             # Build output (JS + source maps + declarations)
│   ├── Worker.js
│   ├── Worker/
│   │   ├── Policy.js
│   │   ├── Register.js
│   │   └── CSS/Load.js
│   ├── Configuration/ESBuild/
│   │   ├── Target.js
│   │   └── Worker.js
│   └── Telemetry/Bridge.js
├── Documentation/
│   └── GitHub/
│       ├── Architecture.md             # Internal module architecture
│       └── DeepDive.md                 # Technical deep-dive into caching strategies
├── Configuration/
│   └── ESBuild/
│       ├── Target.js                   # Target definitions (compiled)
│       └── Worker.js                   # ESBuild config (compiled)
├── .github/                            # CI workflows (GitHub, Auto, Dependabot)
├── package.json                        # NPM package metadata + scripts
├── tsconfig.json                       # TypeScript configuration
├── CHANGELOG.md                        # Version history
└── README.md                           # This file

Worker is registered from the Sky Astro page and intercepts fetch events within the Tauri WebView to cache static assets and handle dynamic CSS imports. It operates as an independent service worker script that runs in a separate thread from the main application, providing offline resilience without blocking the UI.

Worker's caching strategies are scoped to /Application and /Static/Application/*, ensuring that only Land's own assets pass through the policy routing - third-party requests are passed through untouched.

• Node.js 18 or later
• NPM registry access for @codeeditorland/worker

cd Element/Worker
npm install
npm run prepublishOnly

cd Element/Worker
npm run Run

ESBuild injects these constants at build time - no runtime config parsing:

Worker enforces security at multiple layers:

Worker is designed to be compatible with:

• Worker.ts
  • Main service worker with caching strategies and CSS import interception
• Policy.ts
  • Trusted Types policy for secure script URL validation
• Register.ts
  • Service worker registration, update detection, and activation
• Load.ts
  • Client-side CSS loader function (window._LOAD_CSS_WORKER)
• Bridge.ts
  • PostHog + OTLP telemetry bridge from service worker context

• Architecture Overview - Land system architecture
• Land Documentation - Complete documentation index
• Sky ☀️ - UI component layer that registers Worker
• Wind 🌬️ - Service layer (correlated frontend element)
• Cocoon 🦋 - Node.js/Effect-TS extension host (correlated frontend element)
• CHANGELOG.md
  • Release history for Worker ⚙️

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.

See CHANGELOG.md for a history of changes specific to Worker ⚙️.

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, under grant agreement No 101135429.

The project is operated by PlayForm, based in Sofia, Bulgaria. PlayForm acts as the open-source steward for Code Editor Land under the NGI0 Commons Fund grant.