astro-helmet 1.0.5 → 1.2.0

package/README.md

@@ -10,6 +10,7 @@
 - Include default charset and viewport meta tags.
 - Order head items with default or specified priority.
 - Meta tag deduplication.
+- JSON-LD structured data helper with automatic `@context`, serialization, and escaping.
 - Flexible API for adding head items and tag attributes.
 
 ## Installation
@@ -113,12 +114,65 @@ const headItems: HeadItems = {
 </Layout>
 ```
 
+### JSON-LD / Structured Data
+
+Use the `jsonLd` property to add [JSON-LD structured data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data) to your pages. `@context` is set to `https://schema.org` automatically, `JSON.stringify()` is handled internally, and `</script>` sequences in values are escaped.
+
+```ts
+const headItems: HeadItems = {
+  title: 'My Article',
+  jsonLd: {
+    '@type': 'Article',
+    headline: 'My Article',
+    author: { '@type': 'Person', name: 'Ryan' },
+    datePublished: '2025-12-01'
+  }
+}
+```
+
+Multiple JSON-LD blocks are supported — pass an array:
+
+```ts
+const headItems: HeadItems = {
+  title: 'My Article',
+  jsonLd: [
+    { '@type': 'Article', headline: 'My Article' },
+    {
+      '@type': 'BreadcrumbList',
+      itemListElement: [
+        { '@type': 'ListItem', position: 1, name: 'Home', item: 'https://example.com/' },
+        { '@type': 'ListItem', position: 2, name: 'My Article' }
+      ]
+    }
+  ]
+}
+```
+
+JSON-LD composes naturally with layout + page merging. Each source contributes blocks that render as separate `<script type="application/ld+json">` tags:
+
+```ts
+// Layout
+const layoutHead: HeadItems = {
+  jsonLd: { '@type': 'WebSite', name: 'My Blog', url: 'https://example.com' }
+}
+
+// Page
+const pageHead: HeadItems = {
+  title: 'My Article',
+  jsonLd: { '@type': 'Article', headline: 'My Article' }
+}
+
+// <Helmet headItems={[layoutHead, pageHead]} />
+```
+
+JSON-LD script tags are rendered with priority `105`, placing them after regular meta tags and before noscript elements.
+
 ### Deduplication
 
 When provided with an array of `headItems`, `astro-helmet` will merge the items together.
 
-`headItems.meta` are deduplicated by `name`, `property` and `http-equiv`.
-Meta items later in the array replace earlier items.
+`headItems.meta` are deduplicated by `name`, `property`, `http-equiv` and `charset`.
+Meta items later in the array replace earlier items. Meta tags without any of these keys (e.g. `itemprop`-only tags) are never deduplicated.
 
 `title` and `base` items are also deduplicated, with the last item in the array taking precedence.
 
@@ -182,6 +236,7 @@ By default, items are ordered as follows:
 | 80       | `<link rel="prefetch" />`                     |
 | 90       | remaining `<link>`                            |
 | 100      | remaining `<meta>`                            |
+| 105      | `<script type="application/ld+json">`         |
 | 110      | anything else                                 |
 
 This is the default implementation of `applyPriority()`:
@@ -215,11 +270,12 @@ function applyPriority(tag: Tag): Required<Tag> {
       break
 
     case 'style':
-      priority = tag.innerHTML.includes('@import') ? 30 : 51
+      priority = tag.innerHTML?.includes('@import') ? 30 : 51
       break
 
     case 'script':
-      if (tag.async) priority = 20
+      if (tag.type === 'application/ld+json') priority = 105
+      else if (tag.async) priority = 20
       else if (tag.defer) priority = 70
       else priority = 40
       break

package/index.ts

@@ -2,4 +2,4 @@ import Helmet from './src/Helmet.astro'
 
 export default Helmet
 
-export type { HeadItems, Tag } from './src/main'
+export type { HeadItems, JsonLdItem, Tag } from './src/main'

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "astro-helmet",
-	"version": "1.0.5",
+	"version": "1.2.0",
 	"type": "module",
 	"description": "A document head manager for astro.",
 	"author": "Ryan Voitiskis <ryanvoitiskis@pm.me> (https://ryanvoitiskis.com/)",
@@ -25,23 +25,29 @@
 	"scripts": {
 		"test": "vitest",
 		"coverage": "vitest run --coverage",
+		"typecheck": "astro check",
+		"lint": "eslint .",
 		"release": "semantic-release"
 	},
 	"devDependencies": {
+		"@astrojs/check": "^0.9.8",
+		"@eslint/js": "^9.39.2",
 		"@semantic-release/changelog": "^6.0.3",
 		"@semantic-release/git": "^10.0.1",
 		"@semantic-release/github": "^11.0.1",
 		"@semantic-release/npm": "^12.0.1",
-		"@vitest/coverage-v8": "^2.1.8",
-		"astro": "^5.0.3",
+		"@vitest/coverage-v8": "^4.1.2",
+		"astro": "^6.1.3",
+		"eslint": "^9.39.2",
 		"prettier": "^3.4.2",
 		"prettier-plugin-astro": "^0.14.1",
 		"semantic-release": "^24.2.0",
 		"typescript": "^5.7.2",
-		"vitest": "^2.1.8"
+		"typescript-eslint": "^8.55.0",
+		"vitest": "^4.1.2"
 	},
 	"peerDependencies": {
-		"astro": "^4.0.0 || ^5.0.0"
+		"astro": "^4.0.0 || ^5.0.0 || ^6.0.0"
 	},
 	"repository": {
 		"type": "git",

package/src/Helmet.astro

@@ -1,5 +1,5 @@
 ---
-import { type HeadItems, type Tag, renderHead } from './main'
+import { type HeadItems, type Tag, renderHead, getInlineContent, getExternalResources } from './main'
 
 interface Props {
 	headItems: HeadItems | HeadItems[]
@@ -12,6 +12,34 @@ interface Props {
 const { headItems, options = {} } = Astro.props
 const { applyPriority, omitHeadTags = false } = options
 const head = renderHead(headItems, applyPriority)
+
+// Register CSP hashes and resources when running on Astro 6+ with CSP enabled.
+// Cast avoids typecheck failures for downstream consumers on Astro 4/5 where
+// `csp` isn't declared on `AstroGlobal`.
+const csp = (Astro as unknown as {
+	csp?: {
+		insertScriptHash(hash: string): void
+		insertStyleHash(hash: string): void
+		insertScriptResource(url: string): void
+		insertStyleResource(url: string): void
+	}
+}).csp
+if (csp) {
+	for (const { type, content } of getInlineContent(headItems)) {
+		const hashBuffer = await crypto.subtle.digest(
+			'SHA-256',
+			new TextEncoder().encode(content)
+		)
+		const hash = btoa(String.fromCharCode(...new Uint8Array(hashBuffer)))
+		if (type === 'script') csp.insertScriptHash(`sha256-${hash}`)
+		else csp.insertStyleHash(`sha256-${hash}`)
+	}
+
+	for (const { type, url } of getExternalResources(headItems)) {
+		if (type === 'script') csp.insertScriptResource(url)
+		else csp.insertStyleResource(url)
+	}
+}
 ---
 
 {

package/src/main.ts

@@ -14,6 +14,7 @@ type TagName =
 	| 'noscript'
 
 type BaseItem = {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
 	[key: string]: any
 	priority?: number
 }
@@ -27,6 +28,14 @@ export type Tag = (BaseItem | ContentItem) & {
 	priority?: number
 }
 
+export type JsonLdItem = {
+	'@type': string
+	/** Automatically injected — do not provide. */
+	'@context'?: never
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	[key: string]: any
+}
+
 export type HeadItems = {
 	title?: string
 	base?: BaseItem[]
@@ -35,6 +44,18 @@ export type HeadItems = {
 	style?: ContentItem[]
 	script?: ContentItem[]
 	noscript?: ContentItem[]
+	jsonLd?: JsonLdItem | JsonLdItem[]
+}
+
+type NormalisedHeadItems = {
+	title: string
+	base: BaseItem[]
+	meta: BaseItem[]
+	link: BaseItem[]
+	style: ContentItem[]
+	script: ContentItem[]
+	noscript: ContentItem[]
+	jsonLd: JsonLdItem[]
 }
 
 export function renderHead(
@@ -50,13 +71,23 @@ export function renderHead(
 	items.meta = deduplicateMetaItems(items.meta)
 	items.base = items.base.slice(-1)
 
-	const { title, ...rest } = items
+	const { title: _title, jsonLd: _jsonLd, ...rest } = items
 	const tags: Tag[] = Object.entries(rest).flatMap(([tagName, tagItems]) =>
 		tagItems.map((item) => ({ ...item, tagName }) as Tag)
 	)
 	tags.push({ tagName: 'title', innerHTML: items.title })
 	tags.push(...getDefaultTags(tags))
 
+	for (const item of items.jsonLd) {
+		tags.push({
+			tagName: 'script',
+			type: 'application/ld+json',
+			innerHTML: escapeJsonLd(
+				JSON.stringify({ ...item, '@context': 'https://schema.org' })
+			)
+		})
+	}
+
 	const prioritisedTags = tags.map((tag) =>
 		applyPriority ? applyPriority(tag) : applyPriorityDefault(tag)
 	)
@@ -66,7 +97,7 @@ export function renderHead(
 	return orderedTags.map((i) => renderHeadTag(i)).join('\n')
 }
 
-function normaliseHeadItems(items: HeadItems): Required<HeadItems> {
+function normaliseHeadItems(items: HeadItems): NormalisedHeadItems {
 	return {
 		title: items.title || '',
 		base: items.base || [],
@@ -74,11 +105,16 @@ function normaliseHeadItems(items: HeadItems): Required<HeadItems> {
 		link: items.link || [],
 		style: items.style || [],
 		script: items.script || [],
-		noscript: items.noscript || []
+		noscript: items.noscript || [],
+		jsonLd: Array.isArray(items.jsonLd)
+			? items.jsonLd
+			: items.jsonLd
+				? [items.jsonLd]
+				: []
 	}
 }
 
-function mergeHeadItems(items: Required<HeadItems>[]): Required<HeadItems> {
+function mergeHeadItems(items: NormalisedHeadItems[]): NormalisedHeadItems {
 	return items.reduce((merged, item) => {
 		merged.title = item.title || merged.title
 		merged.base.push(...item.base)
@@ -87,8 +123,9 @@ function mergeHeadItems(items: Required<HeadItems>[]): Required<HeadItems> {
 		merged.style.push(...item.style)
 		merged.script.push(...item.script)
 		merged.noscript.push(...item.noscript)
+		merged.jsonLd.push(...item.jsonLd)
 		return merged
-	})
+	}, normaliseHeadItems({}))
 }
 
 function getDefaultTags(tags: Tag[]): Tag[] {
@@ -130,11 +167,12 @@ function applyPriorityDefault(tag: Tag): Required<Tag> {
 			break
 
 		case 'style':
-			priority = tag.innerHTML.includes('@import') ? 30 : 51
+			priority = tag.innerHTML?.includes('@import') ? 30 : 51
 			break
 
 		case 'script':
-			if (tag.async) priority = 20
+			if (tag.type === 'application/ld+json') priority = 105
+			else if (tag.async) priority = 20
 			else if (tag.defer) priority = 70
 			else priority = 40
 			break
@@ -145,20 +183,80 @@ function applyPriorityDefault(tag: Tag): Required<Tag> {
 	return { ...tag, priority }
 }
 
-function deduplicateMetaItems(metaItems: BaseItem[]): BaseItem[] {
-	const metaMap = groupMetaItemsByKey(metaItems)
-	return Array.from(metaMap.values()).flatMap(deduplicateByMedia)
+export function getInlineContent(
+	headItems: HeadItems | HeadItems[]
+): { type: 'script' | 'style'; content: string }[] {
+	const items = Array.isArray(headItems)
+		? mergeHeadItems(headItems.map((i) => normaliseHeadItems(i)))
+		: normaliseHeadItems(headItems)
+
+	const result: { type: 'script' | 'style'; content: string }[] = []
+
+	for (const style of items.style) {
+		if (style.innerHTML) result.push({ type: 'style', content: style.innerHTML })
+	}
+
+	for (const script of items.script) {
+		if (script.innerHTML)
+			result.push({ type: 'script', content: script.innerHTML })
+	}
+
+	for (const item of items.jsonLd) {
+		result.push({
+			type: 'script',
+			content: escapeJsonLd(
+				JSON.stringify({ ...item, '@context': 'https://schema.org' })
+			)
+		})
+	}
+
+	return result
 }
 
-function groupMetaItemsByKey(metaItems: BaseItem[]): Map<string, BaseItem[]> {
+export function getExternalResources(
+	headItems: HeadItems | HeadItems[]
+): { type: 'script' | 'style'; url: string }[] {
+	const items = Array.isArray(headItems)
+		? mergeHeadItems(headItems.map((i) => normaliseHeadItems(i)))
+		: normaliseHeadItems(headItems)
+
+	const result: { type: 'script' | 'style'; url: string }[] = []
+
+	for (const script of items.script) {
+		if (script.src) result.push({ type: 'script', url: script.src })
+	}
+
+	for (const link of items.link) {
+		if (link.rel === 'stylesheet' && link.href)
+			result.push({ type: 'style', url: link.href })
+		else if (link.rel === 'preload' && link.href) {
+			if (link.as === 'script') result.push({ type: 'script', url: link.href })
+			else if (link.as === 'style')
+				result.push({ type: 'style', url: link.href })
+		}
+	}
+
+	return result
+}
+
+function escapeJsonLd(json: string): string {
+	return json.replace(/<\//g, '<\\/')
+}
+
+function deduplicateMetaItems(metaItems: BaseItem[]): BaseItem[] {
+	const keyless: BaseItem[] = []
 	const metaMap = new Map<string, BaseItem[]>()
 
-	metaItems.forEach((meta) => {
-		const key = meta.property || meta.name || meta['http-equiv']
+	for (const meta of metaItems) {
+		const key = meta.property || meta.name || meta['http-equiv'] || (meta.charset ? 'charset' : null)
 		if (key) metaMap.set(key, (metaMap.get(key) || []).concat(meta))
-	})
+		else keyless.push(meta)
+	}
 
-	return metaMap
+	return [
+		...keyless,
+		...Array.from(metaMap.values()).flatMap(deduplicateByMedia)
+	]
 }
 
 function deduplicateByMedia(items: BaseItem[]): BaseItem[] {
@@ -176,7 +274,7 @@ function deduplicateByMedia(items: BaseItem[]): BaseItem[] {
 function renderHeadTag(item: BaseItem | ContentItem): string {
 	const attrs = renderAttrs(item)
 	return ['meta', 'link', 'base'].includes(item.tagName)
-		? `<${item.tagName} ${attrs}>`
+		? `<${item.tagName}${attrs ? ' ' + attrs : ''}>`
 		: `<${item.tagName}${attrs && ' '}${attrs}>${item.innerHTML || ''}</${
 				item.tagName
 			}>`