npm - favicon-env - Versions diffs - 0.3.1 → 0.3.2 - Mend

favicon-env 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -545,6 +545,37 @@ For a zero-byte prod page, have the HTML build/template omit these scripts when
 </details>
+<details>
+<summary><b>Non-JS backends</b> — Rails, Django, Laravel, Phoenix, Go, Rust</summary>
+Runtime mode asks nothing of the server: it reads the page's `<link rel="icon">` (or falls back to `/favicon.ico`), redraws it on a canvas, and swaps the `href`. No bundler and no JavaScript framework are involved, so serve the global build from your static assets and let the template supply the environment:
+```html
+<link rel="icon" href="/favicon.svg" />
+<!-- render these two tags only when the app environment is not `prod` -->
+<script src="/static/favicon-env.global.js"></script>
+<script>
+  void faviconEnv.envFavicon({
+    environments: {
+      dev: { tint: '#22c55e' },
+      staging: { badge: { text: 'S', color: '#f59e0b', shape: 'cover' } },
+    },
+    detect: () => 'staging', // interpolate the server's env value here
+  });
+</script>
+```
+Pass whatever the stack already knows — `Rails.env`, `settings.DEBUG`, `config('app.env')`, `Application.get_env(:my_app, :env)`, `os.Getenv("APP_ENV")` — through your template's normal escaping. Without it the hostname heuristic still applies, which is enough when your hosts follow the usual conventions.
+Having the template omit those two tags in `prod` is the whole [zero-bytes-in-prod](#zero-bytes-in-prod) story here: nothing is served, so there is no bundler dead-code elimination to arrange. The `Plain HTML (global)` entry in the framework matrix exercises this exact shape — a server that renders the script conditionally and injects `detect` — so only the template language differs.
+Add the head-observer pattern from the examples above only if something re-renders `<head>` after load: Turbo Drive, Inertia's head manager, `leptos_meta`. Plain server templates, htmx body swaps, and LiveView leave `<head>` alone, so a single call is enough. For a Rust/Wasm SPA (Leptos, Dioxus, Yew), the script tag in the `index.html` shell is all you need — no `wasm-bindgen` interop.
+[Build-time mode](#build-time--ssr-mode) is the one piece that needs a JavaScript runtime; see the note there.
+</details>
 By default the environment is guessed from the hostname (`localhost` / `*.local` / raw IPs → `dev`; a `staging`/`preview`/`qa`/… segment → `staging`; everything else → `prod`). Override it:
 ```js
@@ -679,6 +710,8 @@ const pr = process.env.VERCEL_GIT_PULL_REQUEST_ID;
 faviconDataUri(favicon, pr ? { badge: { text: `#${pr}` } } : { hue: 45 });
 ```
+`favicon-env/ssr` is JavaScript, so a non-JS server can't call it in-process. Run it as a Node build step that writes one SVG per environment (`favicon.dev.svg`, `favicon.staging.svg`) and have the template pick one, or stay on runtime mode and accept its brief flash. `tintSvg` itself is plain string manipulation — a wrapping filtered `<g>` plus an optional badge `<g>` — if you would rather port it to the host language.
 ### Vite
 This Vite plugin rewrites an SVG favicon using the current mode:

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "favicon-env",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Tint your favicon per environment (dev/staging/prod) so you can tell instances apart at a glance. Runtime canvas mode + build-time SVG mode. Zero dependencies.",
   "keywords": [
     "canvas",
@@ -52,13 +52,13 @@
     "@changesets/cli": "^3.0.1",
     "@playwright/test": "^1.62.1",
     "@swc/core": "^1.16.1",
-    "@tanstack/intent": "^0.3.7",
+    "@tanstack/intent": "^0.3.8",
     "dependency-cruiser": "^18.2.0",
-    "knip": "^6.32.3",
+    "knip": "^6.33.0",
     "oxfmt": "^0.65.0",
     "oxlint": "^1.80.0",
     "publint": "^0.3.24",
-    "simple-git-hooks": "^2.13.1",
+    "simple-git-hooks": "^2.14.0",
     "tsup": "^8.5.1",
     "typescript": "^7.0.2"
   },
@@ -74,7 +74,7 @@
     "format": "oxfmt src",
     "knip": "knip",
     "depcruise": "depcruise src",
-    "check": "oxfmt --check src && oxlint src && knip && depcruise src",
+    "check": "oxfmt --check src && oxlint src && knip && depcruise src && pnpm run skill:stale && pnpm run skill:check",
     "publint": "publint --strict",
     "intent:validate": "intent validate skills",
     "intent:stale": "intent stale skills",

package/skills/core/SKILL.md CHANGED Viewed

@@ -5,12 +5,13 @@ description: >
   identical tabs are distinguishable. Load when calling envFavicon, choosing
   runtime (canvas) vs build-time (SSR) mode, adding hue/invert/filter tints or
   badges/PR numbers, wiring it into Next.js/TanStack/Astro/SvelteKit/SolidStart/
-  Angular/Nuxt/Vite/plain HTML, or configuring detect, environments, rules, or
-  auto mode.
+  Angular/Nuxt/Vite/plain HTML or a server-rendered non-JS backend
+  (Rails/Django/Laravel/Phoenix/Go/Rust), or configuring detect, environments,
+  rules, or auto mode.
 metadata:
   type: core
   library: favicon-env
-  library_version: '0.3.1'
+  library_version: '0.3.2'
 sources:
   - 'Amir-Abushanab/favicon-env:README.md'
   - 'Amir-Abushanab/favicon-env:src/tint.ts'
@@ -66,6 +67,7 @@ The environment name defaults to a `location.hostname` heuristic (`defaultDetect
 | Nuxt           | `app/plugins/favicon-env.client.ts`, using an explicit Vite build constant     |
 | Vite SPA       | Client entry module (`src/main.ts`, etc.)                                      |
 | Plain HTML     | Native module or the global build (`window.faviconEnv`)                        |
+| Non-JS backend | Global build `<script>` in the server template; `detect` from the injected env |
 For any SSR router/head manager that declares the favicon itself, wrap the call in
 the head-observer pattern below. Hydration or navigation can otherwise restore its
@@ -81,6 +83,9 @@ are folded to literals. SvelteKit and Nuxt may preserve their normal public runt
 configuration, so define a dedicated constant through Vite's `define` option and use
 that in the guard.
+In a server-rendered template there is no bundler step to arrange: render the
+`<script>` tags only when the environment is not `prod` and prod ships nothing.
 Angular's application builder can emit a lazy chunk even behind a false `define`
 guard. Put the dynamic import in a local loader module and replace that module with a
 typed no-op in the prod build using Angular `fileReplacements`. For plain HTML, omit
@@ -130,6 +135,32 @@ void envFavicon({ auto: true });
 Derives a deterministic hue from `location.host`, so every origin and port gets its
 own colour — handy for telling several dev servers apart.
+### Server-rendered templates — the global build, no bundler
+```html
+<link rel="icon" href="/favicon.svg" />
+<!-- render these two tags only when the app environment is not prod -->
+<script src="/static/favicon-env.global.js"></script>
+<script>
+  void faviconEnv.envFavicon({
+    environments: { dev: { tint: '#22c55e' }, staging: { badge: '#f59e0b' } },
+    detect: () => 'staging', // interpolate Rails.env / config('app.env') / os.Getenv("APP_ENV")
+  });
+</script>
+```
+Runtime mode needs only a browser — it reads `link[rel~="icon"]` (falling back to
+`/favicon.ico`), redraws on canvas, and swaps the `href` — so Rails, Django, Laravel,
+Phoenix, Go, and Rust/Wasm apps serve `dist/favicon-env.global.js` from their static
+assets and let the template inject `detect`. Omitting the two tags in prod is the
+whole zero-bytes story there. Add the head observer only where something re-renders
+`<head>` (Turbo Drive, Inertia, `leptos_meta`); plain templates, htmx body swaps, and
+LiveView leave it alone. For a Rust/Wasm SPA the tag in the `index.html` shell is
+enough — no `wasm-bindgen` interop. `favicon-env/ssr` is the one JS-only entry point:
+run it as a Node build step emitting one SVG per environment if the no-flash path
+matters.
 ### Build-time SSR — no first-paint flash
 ```js
@@ -355,3 +386,32 @@ const href = document.querySelector('link[rel~="icon"]').href;
 redrawing; the `<link>` is not replaced until it resolves.
 Source: src/tint.ts (returns `Promise`, `img` load listener)
+### MEDIUM — Expecting the global build's `data-*` attributes to carry the environment
+Wrong:
+```html
+<!-- beta.acme.internal — no `staging`/`qa`/… segment, so the heuristic says `prod` -->
+<script src="/static/favicon-env.global.js" data-staging="45"></script>
+```
+Correct:
+```html
+<script src="/static/favicon-env.global.js"></script>
+<script>
+  void faviconEnv.envFavicon({
+    environments: { staging: { hue: 45 } },
+    detect: () => 'staging', // filled in by the server template
+  });
+</script>
+```
+`data-<env>="<degrees>"` only declares hues (non-numeric values are dropped, and any
+other numeric `data-*` becomes an environment); the current env is still resolved by
+`defaultDetect`. When the host doesn't match that heuristic, call `envFavicon`
+explicitly with a `detect` the server fills in. `data-auto` is the exception: it
+ignores `environments` and hashes `location.host`.
+Source: src/global.ts (boot), src/detect.ts