Add lists, tables, and highlighter to cdn-edge-caching-cache-keys-vary-headers articles

Author: webstackdev

src/components/Code/CodeTabs/client/selectors.ts

@@ -71,11 +71,3 @@ export function queryCodeTabsIconMarkup(params: {
   const markup = iconHostCandidate.innerHTML.trim()
   return markup ? markup : null
 }
-
-export function hasHighlighterElement(scope: ParentNode = document): boolean {
-  return scope.querySelector('highlighter-element') !== null
-}
-
-export function hasMastodonModalElement(scope: ParentNode = document): boolean {
-  return scope.querySelector('mastodon-modal-element') !== null
-}

src/components/Code/CodeTabs/index.astro

@@ -16,35 +16,6 @@ const iconBankId = 'code-tabs-icon-bank'
 
 <script>
   import { registerCodeTabsWebComponent } from './client'
-  import { hasHighlighterElement, hasMastodonModalElement } from './client/selectors'
-  registerCodeTabsWebComponent()
-
-  const registerOptionalMarkdownWebComponents = async () => {
-    if (hasHighlighterElement()) {
-      try {
-        const { registerHighlighterWebComponent } = await import(
-          '@components/Social/Highlighter/client'
-        )
-        registerHighlighterWebComponent()
-      } catch {
-        // Best effort only.
-      }
-    }
 
-    if (hasMastodonModalElement()) {
-      try {
-        const { registerMastodonModalWebComponent } = await import(
-          '@components/Social/Mastodon/client'
-        )
-        registerMastodonModalWebComponent()
-      } catch {
-        // Best effort only.
-      }
-    }
-  }
-
-  registerOptionalMarkdownWebComponents()
-  document.addEventListener('astro:page-load', () => {
-    registerOptionalMarkdownWebComponents()
-  })
+  registerCodeTabsWebComponent()
 </script>

src/components/Inset/layouts/DefaultInset.astro

@@ -9,7 +9,7 @@ export type Props = {
 const { classes, color }: Props = Astro.props
 
 const backgroundClass = color ? `bg-${color}` : 'bg-content-inverse-active'
-const layoutClass = `font-mono ${backgroundClass} border-2 border-trim rounded-md px-6 pt-6`
+const layoutClass = `font-mono whitespace-pre-wrap ${backgroundClass} border-2 border-trim rounded-md px-6 pt-6`
 ---
 
 <div class:list={[layoutClass, classes?.layout]}>

src/components/List/__tests__/index.spec.ts

@@ -100,8 +100,36 @@ describe('List (Astro)', () => {
       expect(leads).toHaveLength(2)
       expect(badges[0]?.textContent?.trim()).toBe('4')
       expect(badges[1]?.textContent?.trim()).toBe('5')
-      expect(badges[0]?.className).toContain('bg-info')
-      expect(leads[0]?.className).toContain('text-info')
+      expect(badges[0]?.getAttribute('style')).toContain('background-color: var(--color-info);')
+      expect(leads[0]?.getAttribute('style')).toContain('color: var(--color-info);')
+    })
+  })
+
+  test('uses the default marker color for numbered-with-background-list when no color is provided', async () => {
+    const List = (await import('@components/List/index.astro')).default
+
+    const renderedHtml = await container.renderToString(List, {
+      props: {
+        variant: 'numbered-with-background-list',
+        items: [
+          {
+            lead: 'Default step',
+            text: 'Uses the default marker color.',
+          },
+        ],
+      },
+    })
+
+    await withJsdomEnvironment(async ({ window }) => {
+      window.document.body.innerHTML = renderedHtml
+
+      const badge = window.document.querySelector('li > span:first-child')
+      const lead = window.document.querySelector('li em')
+
+      expect(badge?.className).toContain('bg-primary-offset')
+      expect(lead?.className).toContain('text-primary-offset')
+      expect(badge?.getAttribute('style')).toBeNull()
+      expect(lead?.getAttribute('style')).toBeNull()
     })
   })
 })

src/components/List/layouts/NumberedWithBackgroundList.astro

@@ -14,21 +14,31 @@ export type Props = {
 }
 
 const { items, classes, color, startNumber = 1 }: Props = Astro.props
-const resolvedColor = typeof color === 'string' && color.trim().length > 0 ? color.trim() : 'primary-offset'
-const pillColorClass = `bg-${resolvedColor}`
+const resolvedColor = typeof color === 'string' && color.trim().length > 0 ? color.trim() : undefined
+const safeColorToken = resolvedColor && /^[-a-z0-9]+$/i.test(resolvedColor) ? resolvedColor : undefined
+const pillStyle = safeColorToken ? `background-color: var(--color-${safeColorToken});` : undefined
+const leadStyle = safeColorToken ? `color: var(--color-${safeColorToken});` : undefined
 
 const olClass = ["space-y-3", classes?.ol]
 const liClass = ["flex items-start gap-4 bg-page-offset/50 rounded-lg p-4", classes?.li]
-const emClass = [`text-${resolvedColor}`, "font-semibold not-italic", classes?.em]
+const emClass = ["font-semibold not-italic", !safeColorToken && 'text-primary-offset', classes?.em]
 ---
 
 <ol class:list={olClass}>
   {
     items.map((item, index) => (
       <li class:list={liClass}>
-        <span class:list={["mt-2 shrink-0 w-8 h-8 text-content-inverse rounded-full flex items-center justify-center text-sm font-bold", pillColorClass]}>{startNumber + index}</span>
+        <span
+          class:list={[
+            "mt-2 shrink-0 w-8 h-8 text-content-inverse rounded-full flex items-center justify-center text-sm font-bold",
+            !safeColorToken && 'bg-primary-offset',
+          ]}
+          style={pillStyle}
+        >
+          {startNumber + index}
+        </span>
         <div class="pt-1">
-          {item.lead && <em class:list={emClass} set:html={item.lead}></em>}
+          {item.lead && <em class:list={emClass} style={leadStyle} set:html={item.lead}></em>}
           <div set:html={item.text}></div>
         </div>
       </li>

src/components/Social/Highlighter/index.astro

@@ -18,7 +18,6 @@
  * ```
  */
 import Icon from '@components/Icon/index.astro'
-import './index.css'
 
 export interface Props {
   /**
@@ -49,13 +48,3 @@ const { ariaLabel, class: className } = Astro.props
     <slot />
   </span>
 </highlighter-element>
-
-<script>
-  import { registerHighlighterWebComponent } from '@components/Social/Highlighter/client'
-
-  registerHighlighterWebComponent()
-
-  document.addEventListener('astro:page-load', () => {
-    registerHighlighterWebComponent()
-  })
-</script>

src/content/articles/cdn-edge-caching-cache-keys-vary-headers/index.mdx

@@ -18,15 +18,15 @@ The cache hit ratio looked fantastic. 94% of requests served from edge. Response
 
 This is the fundamental tension in edge caching. Aggressive caching dramatically improves performance and reduces origin load, but incorrect configuration serves wrong content to users — sometimes catastrophically. Edge caching is a __data integrity__ problem first, performance problem second.
 
-The good news: two concepts cause the vast majority of CDN cache bugs, and once you understand them, you can cache aggressively without fear. Those concepts are cache keys and Vary headers.
+The good news: <Highlighter>two concepts cause the vast majority of CDN cache bugs, and once you understand them, you can cache aggressively without fear.</Highlighter> Those concepts are cache keys and Vary headers.
 
 ## Cache Keys Determine Correctness
 
 A cache key is the identifier the CDN uses to store and retrieve cached responses. When a request arrives, the edge generates a cache key from the request attributes and looks for a matching entry. If found, it returns the cached response. If not, it fetches from origin and stores the response under that key.
 
 By default, most CDNs use a simplified version of the URL:
 
-```text
+<Inset color="warning-inverse">
 Default cache key:
   SCHEME + HOST + PATH + QUERY_STRING
 
@@ -35,7 +35,7 @@ Example request:
 
 Cache key:
   "https://example.com/api/products?category=shoes"
-```
+</Inset>
 
 This seems straightforward, but the details matter enormously. Two requests that __should__ return identical content but generate different cache keys create duplicate cache entries — wasting storage and reducing hit ratios. Two requests that __should__ return different content but generate the same cache key serve wrong content to users — exactly the bug we opened with.
 
@@ -45,15 +45,15 @@ The rule is simple: every attribute that affects your response must be in the ca
 
 Query parameters are the most common source of cache key problems. Consider these two URLs:
 
-```text
+<Inset color="danger-inverse">
 Problem: Query parameter order
 
 These are the same request but different cache keys:
-  /products?color=red&size=large
-  /products?size=large&color=red
+&nbsp;&nbsp;&nbsp;/products?color=red&size=large
+&nbsp;&nbsp;&nbsp;/products?size=large&color=red
 
 Result: Two cache entries for identical content
-```
+</Inset>
 
 Different parameter order, different cache keys, same content — you're now storing two copies and reducing your hit ratio. Marketing teams compound this by adding tracking parameters to URLs. Every `utm_source`, `fbclid`, and `gclid` creates a unique cache key for content that's identical regardless of how the user arrived.
 
@@ -89,6 +89,8 @@ Query parameter pollution is one of the most common causes of poor cache hit rat
 
 The `Vary` header tells caches "this response differs based on these request headers." It's the origin's way of saying "I returned different content to different clients based on header X, so you need to store separate cached versions."
 
+<Newsletter />
+
 When a CDN sees `Vary: Accept-Language`, it doesn't just store one cached response per URL — it stores one per URL __per unique Accept-Language value__. The cache key effectively becomes URL + the values of all headers listed in Vary.
 
 ```http title="vary-example.http"
@@ -105,7 +107,8 @@ With two headers in Vary, you get a combinatorial explosion of cache variants. E
 The guideline: only vary on headers with a small, known set of values.
 
 <Table
-  variant="vertical-column-delineation-table"
+  variant="grid-and-accent-header-table"
+  fullWidth={false}
   content={{
     figure: "Vary header guidance for common headers.",
     thead: { th: ["Vary On", "Good Idea?", "Reason"] },
@@ -138,8 +141,6 @@ The guideline: only vary on headers with a small, known set of values.
 
 `Accept-Encoding` is safe because there are only a few compression algorithms. `Accept-Language` is risky because browsers send values like `en-US, en;q=0.9, de;q=0.8`—technically unique per user's language preferences. If you vary on it, normalize the header first to extract just the primary language.
 
-<Newsletter />
-
 ### The Cookie Vary Trap
 
 The most common Vary mistake is `Vary: Cookie`. It seems logical — if your response depends on cookies, tell the cache to vary on them. But cookies include session IDs, authentication tokens, and tracking identifiers that are unique per user. Even when the actual content-affecting cookie (`preferences=dark`) is the same, the unique session IDs create separate cache entries.
@@ -188,14 +189,31 @@ Understanding cache keys and Vary headers lets you avoid the two most dangerous
 
 This is the bug from our opening story — serving one user's content to another. It happens when:
 
-- Your origin returns `Cache-Control: public` for personalized responses
-- You vary on session cookie but session IDs still contaminate the cache key
-- You cache without checking for authentication headers
+<List
+  variant="colored-marker-list"
+  classes={{
+    wrapper: "sm:ml-12 sm:mr-12 mb-6",
+  }}
+  items={[
+    {
+      color: "bg-danger-offset",
+      text: 'Your origin returns <span class="font-mono">Cache-Control: public</span> for personalized responses',
+    },
+    {
+      color: "bg-danger-offset",
+      text: "You vary on session cookie but session IDs still contaminate the cache key",
+    },
+    {
+      color: "bg-danger-offset",
+      text: "You cache without checking for authentication headers",
+    },
+  ]}
+/>
 
 The patterns that keep you safe:
 
 <Table
-  variant="vertical-column-delineation-table"
+  variant="criteria-highlight-table"
   content={{
     figure: "Personalized content caching patterns.",
     thead: { th: ["Pattern", "Risk Level", "Why"] },
@@ -261,6 +279,10 @@ function handler(event: any): any {
 
 With these headers normalized or stripped, your origin never sees the attack vectors that could poison your cache.
 
+## Getting It Right
+
+Both of these bugs — and most CDN issues you'll encounter — stem from the same root cause: a mismatch between what's in the cache key and what actually affects the response.
+
 <Download
   resource="cdn-edge-caching-cache-keys-vary-headers"
   title="Download the Edge Caching Guide"
@@ -281,10 +303,6 @@ With these headers normalized or stripped, your origin never sees the attack vec
   ]}
 />
 
-## Getting It Right
-
-Both of these bugs — and most CDN issues you'll encounter — stem from the same root cause: a mismatch between what's in the cache key and what actually affects the response.
-
 A properly-configured cache with 70% hit ratio beats a misconfigured cache with 95% hit ratio. The latter is serving wrong content to 95% of users — or worse, leaking private data between users.
 
 Start with serving correct content: audit your cache keys, normalize your Vary headers, and verify that personalized content can never be cached. Once you've established that foundation, you can optimize for performance with confidence.