Skip to content
Astro Eclipse
Esc
↑↓navigate↵open⌘Jpreview
On this page

Head script

What the inline script injected into every page does, how big it is and how it handles storage failure.

The integration injects one inline <script> into the <head> of every page. It is written by hand, runs before first paint and has no dependencies. With the default config it is about 480 B gzipped.

The size is checked on every library build by size-limit, against a budget of 700 B for the default config and 1 kB for a config with colorScheme and themeColor. Other configs differ by the length of their theme names and storage key.

What it does

  1. Reads the stored choice from localStorage. A value that is not one of your themes (or system, when allowed) is ignored and default is used.

  2. Resolves system to light or dark with matchMedia('(prefers-color-scheme: dark)').

  3. Applies the theme to <html>: sets the attribute, or toggles one class per theme when attribute is class. This happens before the body is parsed, so the first paint is right.

  4. Listens for changes of prefers-color-scheme and, while the choice is system, re-applies the theme and dispatches eclipse:change.

  5. Listens for the storage event on the configured key and does the same when another tab changes the choice.

  6. Listens for astro:before-swap and applies the theme to event.newDocument.documentElement, which is how ClientRouter navigation keeps the theme.

  7. When colorScheme or themeColor is set, sets color-scheme on <html> and <meta name="theme-color"> at the same moments as the theme, including on the incoming document of a swap. See browser chrome. Without those options none of that code is in the script.

  8. When forcedTheme is set, a page whose <html> (or incoming document, on a swap) has data-eclipse-forced="<theme>" gets that theme instead of the stored choice, and the storage and system handlers keep it. See forced theme. A config with forcedTheme is held to a 600 B budget.

  9. When values is set, the script writes values[theme] instead of the theme name, and in class mode removes the classes of every theme before adding the new ones. It also reads the current theme back from a mapped value when storage cannot be read, preferring the theme with the most classes in common. A config with values is held to a 650 B budget.

The eclipse:change event is dispatched on document with detail: { theme, preference } (with forced added when forcedTheme is on). It is the same event onThemeChange listens to.

The script never runs an animation. The View Transition belongs to setTheme, which is part of the client API.

When storage fails

Reading localStorage is wrapped in a try. In a private window or with storage blocked, the read throws, nothing is stored, and the script falls back to default. If default is system, the page follows the system preference and keeps following it.

When storage cannot be read, the theme already on the page is treated as the choice, so it survives ClientRouter swaps. The client API keeps a choice it could not save in memory until a write works again. Other-tab sync does not work without storage, because no storage event is fired. A storage event with no key (another tab called localStorage.clear()) re-applies the theme too.

Configured values are inlined

The theme names, default, attribute, key and whether system is allowed are written into the script as JSON from your config, with < escaped. It does not read the config at runtime.

Content security policy

Because the script is inline, a strict script-src without 'unsafe-inline' blocks it unless you allow it with a hash. Astro’s own CSP support includes it. See the content security policy guide for what was tested and how to get the hash.

Related: config, ClientRouter, getting started.

Was this page helpful?