diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..d01ef4c
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.2.1 - 2026-10-29
+
+### Documentation
+
+- Add a complete typed JSON-LD quick start, an API selection guide, and direct
+ links to documentation, examples, and support.
+- Clarify safe serialization, CSP nonces, entity selection, and the limits of
+ structured data without promising search ranking or rich-result eligibility.
+- Improve npm discovery metadata and attribution.
+
+### Maintenance
+
+- Update the documentation site to Next.js 16.4.2 and document Vercel's automatic
+ output-directory configuration.
+- Compile and render the actual README example against the built package.
+- Verify documentation links, static HTTP responses, canonical metadata, JSON-LD,
+ crawler and LLM files, Markdown endpoints, and missing-page behavior.
+
+### Compatibility
+
+- No public API or peer dependency changes. Package publishing remains isolated
+ from documentation-site dependencies.
+
+## Earlier releases
+
+See [GitHub Releases](https://github.com/ryanhefner/react-structured/releases) for
+the history through 0.2.0.
diff --git a/README.md b/README.md
index be6b0a6..5f739c8 100644
--- a/README.md
+++ b/README.md
@@ -5,441 +5,90 @@
[](https://codecov.io/gh/ryanhefner/react-structured)
[](LICENSE)
-Type-safe React components for Schema.org JSON-LD structured data, Google rich results, and linked `@graph` documents.
+Type-safe React components for Schema.org JSON-LD, rich-result helpers, and linked `@graph` documents. Use them in any React application, including Next.js, without a Next.js dependency.
-`react-structured` is a small React JSON-LD library powered by [`schema-dts`](https://github.com/google/schema-dts). It gives you typed Schema.org data for SEO, structured data, rich results, and Next.js apps without requiring Next.js.
+[Documentation](https://react-structured.dev) · [Getting started](https://react-structured.dev/docs/getting-started) · [API reference](https://react-structured.dev/docs/reference) · [Examples](https://react-structured.dev/docs/schema) · [Issues](https://github.com/ryanhefner/react-structured/issues)
-## Why react-structured?
+Created by [Ryan Hefner](https://www.ryanhefner.com) and [Commune Software](https://commune.software).
-- Full `schema-dts` coverage for Schema.org `Thing` types and JSON-LD `@graph` documents
-- Framework-agnostic React components that also work in Next.js App Router and Pages Router
-- Type-safe `SchemaData<'Product'>`, `SchemaData<'Movie'>`, `GraphData`, and `JsonLdData`
-- Small JSON-LD focused API: `Schema`, `Graph`, `JsonLd`, and common rich-result helpers
-- Safe script serialization with `` escaping and CSP `nonce` support
-- Development-time warnings for common Google rich-result required fields
-
-## Installation
+## Install
```sh
npm install react-structured
```
-## Usage
-
-`Schema` renders a single Schema.org node as a JSON-LD script tag.
-
-```tsx
-import { Schema, type SchemaData } from 'react-structured'
-
-// Article schema
-
-
-// Product schema
-
-
-// Other Schema.org types are typed too
-
-
-// Use SchemaData when defining data separately
-const courseData = {
- name: 'Introduction to TypeScript',
- provider: { '@type': 'Organization', name: 'Example University' }
-} satisfies SchemaData<'Course'>
-
-
-```
-
-`Graph` renders a JSON-LD `@graph` document.
-
-```tsx
-import { Graph, type GraphData } from 'react-structured'
-
-const graphData = {
- '@graph': [
- {
- '@type': 'Person',
- '@id': 'https://example.com/#person',
- name: 'Jane Doe'
- },
- {
- '@type': 'WebSite',
- '@id': 'https://example.com/#website',
- name: 'Example',
- publisher: { '@id': 'https://example.com/#person' }
- }
- ]
-} satisfies GraphData
-
-
-```
-
-`JsonLd` renders a complete JSON-LD document when you want to provide `@context` yourself.
-
-```tsx
-import { JsonLd, type JsonLdData } from 'react-structured'
-
-const personData = {
- '@context': 'https://schema.org',
- '@type': 'Person',
- name: 'Jane Doe'
-} satisfies JsonLdData
-
-
-```
-
-Rich-result helpers are available for common Google Search targets. They use the same `schema-dts` data model and add development-time warnings for Google-required fields where Google defines them.
-
-```tsx
-import { BreadcrumbJsonLd, ProductJsonLd } from 'react-structured'
-
-
-
-
-```
-
-## Supported Schema Types
-
-### Full schema-dts Support
-
-This package uses [`schema-dts`](https://github.com/google/schema-dts) to derive TypeScript definitions for Schema.org types and JSON-LD graph documents.
-
-- `Schema` supports every Schema.org `Thing` type represented by `schema-dts`.
-- `Graph` supports `schema-dts` JSON-LD `Graph` documents.
-- `JsonLd` supports complete `WithContext` and `Graph` JSON-LD documents.
-- The generated JSON-LD always includes `@context: "https://schema.org"`.
-
-That means TypeScript will:
-
-- Autocomplete Schema.org type names such as `Article`, `Product`, `Movie`, and `Course`
-- Check that `data` is valid for the provided `type`
-- Allow top-level `@type` to be omitted because the component sets it
-- Require top-level `@type` to match the `type` prop if you include it
-- Check that graph nodes are valid Schema.org `Thing` objects
-
-Common structured data types include:
-
-- `Article`
-- `BlogPosting`
-- `BreadcrumbList`
-- `Event`
-- `FAQPage`
-- `LocalBusiness`
-- `Organization`
-- `Person`
-- `Product`
-- `Recipe`
-- `Review`
-- `VideoObject`
-- `WebPage`
-- `WebSite`
-
-The same typing works for other Schema.org types:
-
-```tsx
-import { Schema, type SchemaData } from 'react-structured'
-
-
-
-const bookData = {
- name: 'Example Book',
- author: { '@type': 'Person', name: 'Jane Doe' }
-} satisfies SchemaData<'Book'>
-
-
-```
-
-This keeps the components flexible while preserving type safety for Schema.org types represented by `schema-dts`.
+Use an existing React 16.14 or newer application. TypeScript declarations are included, with Schema.org types powered by [`schema-dts`](https://github.com/google/schema-dts). Both ESM and CommonJS entry points are available.
-## How It Fits with next-meta and next-seo
+## Quick start
-`react-structured` is not a full SEO/meta-tag framework. It focuses on type-safe JSON-LD structured data.
+Render structured data alongside the visible page content. This example returns a complete React component; replace its example values with facts about your site.
-Use [`next-meta`](https://github.com/ryanhefner/next-meta) for titles, canonical
-URLs, Open Graph metadata, and social cards. Use `react-structured` alongside it
-for Schema.org JSON-LD. The packages remain independent, and their combined peer
-dependency range requires React 16.14 or newer.
-
-Use `react-structured` when you want:
-
-- React JSON-LD components without a Next.js peer dependency
-- Broad Schema.org coverage through `schema-dts`
-- Direct control over JSON-LD data and `@graph` relationships
-- Structured data in React, Vite, Remix, Astro islands, Next.js, or another React environment
-
-Current `next-seo` releases also focus on JSON-LD and direct users to Next.js's
-native Metadata API for standard metadata. Choose `react-structured` when you
-prefer exhaustive `schema-dts` coverage and framework-independent components;
-choose `next-seo` when its curated JSON-LD component API better matches the
-project. Avoid rendering the same entity through both JSON-LD libraries on one
-page.
-
-## Component API
-
-All rendering components accept these script options:
-
-- `id`: `id` attribute for the rendered script tag. Use a stable,
- document-unique value for inspection and testing.
-- `nonce`: CSP nonce attribute
-- `scriptKey`: React key applied to the rendered script tag
-- `validate`: Enables development-time Google rich-result warnings. Defaults to `true`.
-
-React reserves the `key` prop for the component instance. Use React's `key` normally when rendering lists of components, and use `scriptKey` only when the underlying `` sequences. Escaping prevents script breakout; it does not establish that user-supplied data is accurate or appropriate to publish. Model the visible page honestly, keep private data out of JSON-LD, and read the [security guide](https://react-structured.dev/docs/security).
-See the test files for more examples of how to use each schema type and helper component.
+## Help and contributing
-The documentation site lives in [`docs`](docs/README.md) and is prepared for
-`https://react-structured.dev`. Run `pnpm run docs:dev` to preview it locally.
+[Open an issue](https://github.com/ryanhefner/react-structured/issues), browse the [documentation](https://react-structured.dev), or see the [source and tests](https://github.com/ryanhefner/react-structured/tree/main/src). Report security concerns privately to the [maintainer](mailto:hi@ryanhefner.com) rather than a public issue.
## Development
-Use Node 24.18.0 and pnpm 11.25.0 for repository development. The development
-runtime pin does not change the library's React peer compatibility.
+Repository development uses the pinned Node 24 and pnpm versions. These pins do not change the library's React peer compatibility or require consumers to use pnpm.
```sh
nvm use
@@ -449,5 +98,10 @@ pnpm run verify
pnpm run build
```
-Publishing still uses npm for Trusted Publishing; pnpm manages dependencies and
-development tasks. Consumer installation commands above remain valid with npm.
+The documentation site is published at [react-structured.dev](https://react-structured.dev). Run `pnpm run docs:dev` locally; see [docs development and deployment](docs/README.md) for the independent site checks and Vercel configuration. Package verification intentionally does not require docs workspace dependencies.
+
+Coverage is generated with `pnpm run test:ci`. Publishing uses npm trusted publishing; package publishing and documentation deployment remain separate operations.
+
+## License
+
+[MIT](LICENSE)
diff --git a/docs/README.md b/docs/README.md
index 3218598..6c22366 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -67,6 +67,13 @@ pnpm run docs:verify
pnpm run docs:release-check
```
+`docs:verify` also serves the generated static artifact on a temporary loopback
+port and checks real HTTP GET/HEAD responses, canonical metadata, JSON-LD,
+crawler and LLM files, Markdown, and missing-page status codes. Run
+`pnpm run docs:smoke` separately after an existing build. This validates the
+artifact and clean-URL hosting contract; it does not inspect Vercel dashboard
+settings or replace a post-deployment smoke check.
+
Deploy `docs/out` to `react-structured.dev`. For Vercel, use `docs` as the project
root; `vercel.json` checks public dependencies, installs the workspace, and builds
the library before the site. Keep the Framework Preset set to **Next.js** and the
diff --git a/docs/components/docs/Navbar.tsx b/docs/components/docs/Navbar.tsx
index 65e3bc6..535a618 100644
--- a/docs/components/docs/Navbar.tsx
+++ b/docs/components/docs/Navbar.tsx
@@ -36,7 +36,7 @@ export function Navbar({ records }: { records: readonly DocsSearchRecord[] }) {
react-structured
- v0.2.0
+ v0.2.1
diff --git a/docs/package.json b/docs/package.json
index 03deab3..594072d 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -23,7 +23,7 @@
"@emotion/react": "11.14.0",
"@postkit/react": "0.2.0",
"fathom-client": "3.7.2",
- "next": "16.3.8",
+ "next": "16.4.2",
"next-meta": "0.5.0",
"next-themes": "0.4.6",
"react": "19.2.8",
diff --git a/package.json b/package.json
index a5892aa..f3fd280 100644
--- a/package.json
+++ b/package.json
@@ -1,12 +1,18 @@
{
"name": "react-structured",
- "version": "0.2.0",
+ "version": "0.2.1",
"description": "Type-safe React components for Schema.org JSON-LD structured data, rich results, and @graph documents.",
"repository": {
"type": "git",
"url": "git+https://github.com/ryanhefner/react-structured.git"
},
"author": "Ryan Hefner (https://www.ryanhefner.com)",
+ "contributors": [
+ {
+ "name": "Commune Software",
+ "url": "https://commune.software"
+ }
+ ],
"license": "MIT",
"type": "module",
"bugs": {
@@ -31,21 +37,14 @@
"react",
"json-ld",
"jsonld",
- "ld-json",
"react-json-ld",
- "schema.org",
"schema-org",
- "schema",
"schema-dts",
"structured-data",
"rich-results",
"google-rich-results",
- "google-search",
"seo",
- "metadata",
- "next",
"nextjs",
- "app-router",
"typescript"
],
"files": [
@@ -74,7 +73,7 @@
"types": "./types/index.d.ts",
"scripts": {
"clean": "rimraf dist types coverage",
- "build": "pnpm run clean && rollup -c --bundleConfigAsCjs && tsc -p tsconfig.json",
+ "build": "pnpm run clean && rollup -c --bundleConfigAsCjs && tsc -p tsconfig.json && node scripts/readme-smoke.mjs",
"dev": "rollup -c --bundleConfigAsCjs --watch",
"lint": "eslint .",
"prepack": "pnpm run build",
@@ -88,7 +87,8 @@
"docs:build": "pnpm run build && pnpm --dir docs build",
"docs:typecheck": "pnpm --dir docs typecheck",
"docs:test": "vitest run --config vite.docs.config.ts",
- "docs:verify": "node --test scripts/docs.test.mjs scripts/site-structured-data.test.mjs",
+ "docs:verify": "node --test scripts/docs.test.mjs scripts/site-structured-data.test.mjs && pnpm run docs:smoke",
+ "docs:smoke": "node scripts/docs-http-smoke.mjs",
"docs:release-check": "node scripts/check-docs-release.mjs",
"verify": "pnpm run test:tooling && pnpm run lint && pnpm run typecheck && pnpm test"
},
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6aafe0e..bdd9c3b 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -124,7 +124,7 @@ importers:
version: 0.3.0(supports-color@7.2.0)
'@chakra-docs/next':
specifier: 0.3.0
- version: 0.3.0(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(supports-color@7.2.0)
+ version: 0.3.0(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(supports-color@7.2.0)
'@chakra-docs/search':
specifier: 0.3.0
version: 0.3.0(supports-color@7.2.0)
@@ -147,11 +147,11 @@ importers:
specifier: 3.7.2
version: 3.7.2
next:
- specifier: 16.3.8
- version: 16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ specifier: 16.4.2
+ version: 16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
next-meta:
specifier: 0.5.0
- version: 0.5.0(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ version: 0.5.0(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
next-themes:
specifier: 0.4.6
version: 0.4.6(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
@@ -163,7 +163,7 @@ importers:
version: 19.2.8(react@19.2.8)
react-fathom:
specifier: 0.3.0
- version: 0.3.0(fathom-client@3.7.2)(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ version: 0.3.0(fathom-client@3.7.2)(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
react-icons:
specifier: 5.7.0
version: 5.7.0(react@19.2.8)
@@ -1751,83 +1751,83 @@ packages:
'@emnapi/core': ^1.7.1 || ^2.0.0-alpha.3
'@emnapi/runtime': ^1.7.1 || ^2.0.0-alpha.3
- '@next/env@16.3.8':
+ '@next/env@16.4.2':
resolution:
{
- integrity: sha512-Al9zqHVV7TJv0eFuOU4U7Lvv74PTih4Ch63sk2xCIpSTkE3udFnaOcnzP2lQVymiL7yS9Cj2iClUXlR3EQ5sEw==,
+ integrity: sha512-nTUTFH7G5/J/fmpkjVLegOkqyKOP0CEsJcMsyO4UCYeN1su+YMW/MfaSErnJskL7XM+UDK6aTvslxsRCyya/sA==,
}
- '@next/swc-darwin-arm64@16.3.8':
+ '@next/swc-darwin-arm64@16.4.2':
resolution:
{
- integrity: sha512-2JPRMh2nmQG5CiL7cXGL9AGwnPWJQ//cTtAUCT+w511QHk79SYz3LGv/pc5X643B/WEO0rvu3Yww0hqwt3kgeA==,
+ integrity: sha512-ONkhFvZNFWlsEHOM/81AtxdyuJP2KRYKYR0JxPwvcu1AuPMMMgcL+wW2luldJvMtZwKtUxoSkCychW5wIeoYSw==,
}
engines: { node: '>= 10' }
cpu: [arm64]
os: [darwin]
- '@next/swc-darwin-x64@16.3.8':
+ '@next/swc-darwin-x64@16.4.2':
resolution:
{
- integrity: sha512-GZtCCOBKJ4leVIT/Th0llWKhD1ca92lzbQiS5R5ON9QkoiFnilFsebDae1JU2a3HWoKMEmEZWGs1AGLavVM72Q==,
+ integrity: sha512-luPCMbOsCoaF+kXJEUjmjmOZg1lC3BflhmUu+ZmW4tBu2vW/4AXak8JBFvePizGkxVmNiAw/r9ra+6UviCWtWQ==,
}
engines: { node: '>= 10' }
cpu: [x64]
os: [darwin]
- '@next/swc-linux-arm64-gnu@16.3.8':
+ '@next/swc-linux-arm64-gnu@16.4.2':
resolution:
{
- integrity: sha512-O659ygeQYqneJ1fBKMpFxIFqYkYswu8IAS1OCKK/4f3ZgJJm1dRz4fVJZRi/kLLWjnBKnebOePA4WNv+sV1pVA==,
+ integrity: sha512-xhwFTAncJyaCNy5KqKKuKaIIdCy1/1ZV1s5S1G0hhT7wGMkDTlfJ6aQbfRFnIG/s3/kDrxQ8aycVe+c5QnP8ow==,
}
engines: { node: '>= 10' }
cpu: [arm64]
os: [linux]
libc: [glibc]
- '@next/swc-linux-arm64-musl@16.3.8':
+ '@next/swc-linux-arm64-musl@16.4.2':
resolution:
{
- integrity: sha512-dSjKSyWpzxoO1d3DIZZcP4XJcNaKeLmxQMFOiYl5vuBRMmweIqnAhty8tAmRsvTss779cK1FtYnDMj40e4TQlg==,
+ integrity: sha512-T1PNmfbPcxr5ndtWUL/3wQtLXsz808lq6sc2GrNT5k2oquF7UyqZddHSuAewHVsWsGXe6nsl9HoN1YNriVjuSg==,
}
engines: { node: '>= 10' }
cpu: [arm64]
os: [linux]
libc: [musl]
- '@next/swc-linux-x64-gnu@16.3.8':
+ '@next/swc-linux-x64-gnu@16.4.2':
resolution:
{
- integrity: sha512-lbqOuz3RPRcv+o9msNsJw5x4+Y1ZwPTs6vmL6DCf7i0fZfvng/F59wyeDwqHIvV0mK//RBy/jJkZ+nCKsSMXjQ==,
+ integrity: sha512-N9cDUOCGtkJG5PNKDFZUF3xXndrJJcpLp121uAGjIGvO/U2p9tfdNOM9htj7+5f72l0m8rMw/cvYacUJBQoudg==,
}
engines: { node: '>= 10' }
cpu: [x64]
os: [linux]
libc: [glibc]
- '@next/swc-linux-x64-musl@16.3.8':
+ '@next/swc-linux-x64-musl@16.4.2':
resolution:
{
- integrity: sha512-+316WswI8ScVgZeUd+1KGaXkHhaYQzCjvH/05TZSpJ8zBizb1a4G7DtO7F12jcBIqMOtsz9ji1t48fmKtzqsGA==,
+ integrity: sha512-yY2uh1YhX6ufuYy2FCbw1dqblbhI57GLYAJfCkqD9auTv6pLrH67Uccjc3QMKBeCYAG6lkgu08ExmX1bbjejjQ==,
}
engines: { node: '>= 10' }
cpu: [x64]
os: [linux]
libc: [musl]
- '@next/swc-win32-arm64-msvc@16.3.8':
+ '@next/swc-win32-arm64-msvc@16.4.2':
resolution:
{
- integrity: sha512-ji0gd4kMYUxO+1fJBIbiBVRCjzG/lloiyCccnlebvb1ZJ5qXCPZqYg4Jl1DrrixnWNMKylzgpmMWx0yNDYXlzw==,
+ integrity: sha512-j/ArWRIHpMMB6wYLMhr2puTguBt70lNU/Cmjl9p6dTDE8DGknYJMP9PdwPk2dqpCNL/KIX9yfngDvIesxJPmsg==,
}
engines: { node: '>= 10' }
cpu: [arm64]
os: [win32]
- '@next/swc-win32-x64-msvc@16.3.8':
+ '@next/swc-win32-x64-msvc@16.4.2':
resolution:
{
- integrity: sha512-WcTlaKt/TWkh5kUjdJcUmB1XgZ+1c6fz4Y9fDHL73YNSdGaUWjceeWrrlwF0nv19iABYWC4iAq1oX1w4Bn0vfg==,
+ integrity: sha512-AA4edyWHDko3NCSo0x6GomsdgFb0oR1J3MXU1b5xt6FRFg4AucrMPW3S0hCe/9onU0O1BbpGQBsqo1r0Gneu1g==,
}
engines: { node: '>= 10' }
cpu: [x64]
@@ -5413,10 +5413,10 @@ packages:
react: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
react-dom: ^16.8 || ^17 || ^18 || ^19 || ^19.0.0-rc
- next@16.3.8:
+ next@16.4.2:
resolution:
{
- integrity: sha512-U7QEZaTini6wKrb8A8hqLLqYQyCetegKjCpJOyxk642vWoMoU1x5PyZCJFvgYgiptA8xc5j/9xYlZFO7w9Sjmw==,
+ integrity: sha512-r+oBJojfefUjOiWkBhXgLS+igxX/7BWyK59uHnyOyplMSLtBZ+QLP3okrdYTbrfrbrmNTVWLBPaHDX9KRaIt3w==,
}
engines: { node: '>=20.9.0' }
hasBin: true
@@ -7749,11 +7749,11 @@ snapshots:
transitivePeerDependencies:
- supports-color
- '@chakra-docs/next@0.3.0(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(supports-color@7.2.0)':
+ '@chakra-docs/next@0.3.0(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(supports-color@7.2.0)':
dependencies:
'@chakra-docs/core': 0.3.0(supports-color@7.2.0)
'@chakra-docs/search': 0.3.0(supports-color@7.2.0)
- next: 16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ next: 16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
react: 19.2.8
react-dom: 19.2.8(react@19.2.8)
tslib: 2.8.1
@@ -8124,30 +8124,30 @@ snapshots:
'@tybys/wasm-util': 0.10.3
optional: true
- '@next/env@16.3.8': {}
+ '@next/env@16.4.2': {}
- '@next/swc-darwin-arm64@16.3.8':
+ '@next/swc-darwin-arm64@16.4.2':
optional: true
- '@next/swc-darwin-x64@16.3.8':
+ '@next/swc-darwin-x64@16.4.2':
optional: true
- '@next/swc-linux-arm64-gnu@16.3.8':
+ '@next/swc-linux-arm64-gnu@16.4.2':
optional: true
- '@next/swc-linux-arm64-musl@16.3.8':
+ '@next/swc-linux-arm64-musl@16.4.2':
optional: true
- '@next/swc-linux-x64-gnu@16.3.8':
+ '@next/swc-linux-x64-gnu@16.4.2':
optional: true
- '@next/swc-linux-x64-musl@16.3.8':
+ '@next/swc-linux-x64-musl@16.4.2':
optional: true
- '@next/swc-win32-arm64-msvc@16.3.8':
+ '@next/swc-win32-arm64-msvc@16.4.2':
optional: true
- '@next/swc-win32-x64-msvc@16.3.8':
+ '@next/swc-win32-x64-msvc@16.4.2':
optional: true
'@nicolo-ribaudo/eslint-scope-5-internals@5.1.1-v1':
@@ -10946,21 +10946,21 @@ snapshots:
natural-compare@1.4.0: {}
- next-meta@0.5.0(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+ next-meta@0.5.0(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
dependencies:
react: 19.2.8
react-dom: 19.2.8(react@19.2.8)
optionalDependencies:
- next: 16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ next: 16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
next-themes@0.4.6(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
dependencies:
react: 19.2.8
react-dom: 19.2.8(react@19.2.8)
- next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+ next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
dependencies:
- '@next/env': 16.3.8
+ '@next/env': 16.4.2
'@swc/helpers': 0.5.23
baseline-browser-mapping: 2.11.8
caniuse-lite: 1.0.30001806
@@ -10969,14 +10969,14 @@ snapshots:
react-dom: 19.2.8(react@19.2.8)
styled-jsx: 5.1.6(@babel/core@7.29.7(supports-color@7.2.0))(babel-plugin-macros@3.1.0)(react@19.2.8)
optionalDependencies:
- '@next/swc-darwin-arm64': 16.3.8
- '@next/swc-darwin-x64': 16.3.8
- '@next/swc-linux-arm64-gnu': 16.3.8
- '@next/swc-linux-arm64-musl': 16.3.8
- '@next/swc-linux-x64-gnu': 16.3.8
- '@next/swc-linux-x64-musl': 16.3.8
- '@next/swc-win32-arm64-msvc': 16.3.8
- '@next/swc-win32-x64-msvc': 16.3.8
+ '@next/swc-darwin-arm64': 16.4.2
+ '@next/swc-darwin-x64': 16.4.2
+ '@next/swc-linux-arm64-gnu': 16.4.2
+ '@next/swc-linux-arm64-musl': 16.4.2
+ '@next/swc-linux-x64-gnu': 16.4.2
+ '@next/swc-linux-x64-musl': 16.4.2
+ '@next/swc-win32-arm64-msvc': 16.4.2
+ '@next/swc-win32-x64-msvc': 16.4.2
sharp: 0.35.5(@types/node@24.13.6)
transitivePeerDependencies:
- '@babel/core'
@@ -11188,14 +11188,14 @@ snapshots:
react: 19.2.8
scheduler: 0.27.0
- react-fathom@0.3.0(fathom-client@3.7.2)(next@16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+ react-fathom@0.3.0(fathom-client@3.7.2)(next@16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8))(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
dependencies:
'@babel/runtime': 7.29.7
fathom-client: 3.7.2
react: 19.2.8
react-dom: 19.2.8(react@19.2.8)
optionalDependencies:
- next: 16.3.8(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+ next: 16.4.2(@babel/core@7.29.7(supports-color@7.2.0))(@types/node@24.13.6)(babel-plugin-macros@3.1.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
react-icons@5.7.0(react@19.2.8):
dependencies:
diff --git a/scripts/docs-dependencies.test.mjs b/scripts/docs-dependencies.test.mjs
index 37fd367..ec98a58 100644
--- a/scripts/docs-dependencies.test.mjs
+++ b/scripts/docs-dependencies.test.mjs
@@ -33,10 +33,13 @@ test('every locked nanoid 3 release includes the zero-size generator fix', () =>
test('the docs pin the patched Next.js release without older lockfile copies', () => {
assert.equal(
JSON.parse(read('docs/package.json')).dependencies.next,
- '16.3.8',
+ '16.4.2',
+ )
+ assert.match(read('pnpm-lock.yaml'), /^ {2}next@16\.4\.2:/m)
+ assert.doesNotMatch(
+ read('pnpm-lock.yaml'),
+ /^ {2}next@16\.(?:[0-3]\.\d+|4\.[01]):/m,
)
- assert.match(read('pnpm-lock.yaml'), /^ {2}next@16\.3\.8:/m)
- assert.doesNotMatch(read('pnpm-lock.yaml'), /^ {2}next@16\.3\.[0-7]:/m)
})
test('site analytics uses the pinned public React Fathom release', () => {
diff --git a/scripts/docs-deployment.test.mjs b/scripts/docs-deployment.test.mjs
index 02b80f9..d2495ef 100644
--- a/scripts/docs-deployment.test.mjs
+++ b/scripts/docs-deployment.test.mjs
@@ -15,3 +15,13 @@ test('Vercel looks for Next.js build manifests, not static-export assets', () =>
assert.equal(nextConfig.output, 'export')
assert.equal(vercel.buildCommand, 'cd .. && pnpm run docs:build')
})
+
+test('documentation verification checks the exported site over HTTP independently of publishing', () => {
+ const pkg = JSON.parse(
+ readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+ )
+ assert.match(pkg.scripts['docs:verify'], /pnpm run docs:smoke/)
+ assert.equal(pkg.scripts['docs:smoke'], 'node scripts/docs-http-smoke.mjs')
+ assert.doesNotMatch(pkg.scripts.verify, /docs:/)
+ assert.equal(pkg.scripts.prepublishOnly, 'pnpm run verify')
+})
diff --git a/scripts/docs-http-smoke.mjs b/scripts/docs-http-smoke.mjs
new file mode 100644
index 0000000..f5a1ba3
--- /dev/null
+++ b/scripts/docs-http-smoke.mjs
@@ -0,0 +1,135 @@
+import assert from 'node:assert/strict'
+import { readFile } from 'node:fs/promises'
+import { createServer } from 'node:http'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { JSDOM } from 'jsdom'
+
+const output = fileURLToPath(new URL('../docs/out/', import.meta.url))
+const mime = {
+ '.html': 'text/html; charset=utf-8',
+ '.txt': 'text/plain; charset=utf-8',
+ '.xml': 'application/xml; charset=utf-8',
+ '.png': 'image/png',
+ '.md': 'text/markdown; charset=utf-8',
+}
+
+// This checks the built static artifact through HTTP, not Next's development
+// server. Production hosts must provide equivalent clean-URL and real-404 rules.
+const server = createServer(async (request, response) => {
+ try {
+ if (request.method !== 'GET' && request.method !== 'HEAD') {
+ response.writeHead(405, { Allow: 'GET, HEAD' }).end()
+ return
+ }
+ const pathname = decodeURIComponent(
+ new URL(request.url, 'http://localhost').pathname,
+ )
+ const requested = path.resolve(output, '.' + pathname)
+ const relative = path.relative(output, requested)
+ if (relative.startsWith('..') || path.isAbsolute(relative)) {
+ response.writeHead(400).end()
+ return
+ }
+ const candidates =
+ pathname === '/'
+ ? [path.join(output, 'index.html')]
+ : [requested, requested + '.html', path.join(requested, 'index.html')]
+ let content
+ let filename
+ for (const candidate of candidates) {
+ try {
+ content = await readFile(candidate)
+ filename = candidate
+ break
+ } catch (error) {
+ if (!['ENOENT', 'EISDIR', 'ENOTDIR'].includes(error.code)) throw error
+ }
+ }
+ const status = content ? 200 : 404
+ if (!content) {
+ content = await readFile(path.join(output, '404.html'))
+ filename = '404.html'
+ }
+ response.writeHead(status, {
+ 'Content-Type':
+ mime[path.extname(filename)] ?? 'application/octet-stream',
+ 'Content-Length': content.length,
+ 'X-Content-Type-Options': 'nosniff',
+ })
+ response.end(request.method === 'HEAD' ? undefined : content)
+ } catch {
+ response.writeHead(500).end()
+ }
+})
+
+try {
+ await new Promise((resolve, reject) => {
+ server.once('error', reject)
+ server.listen(0, '127.0.0.1', resolve)
+ })
+ const origin = `http://127.0.0.1:${server.address().port}`
+ const request = (route, method = 'GET') =>
+ fetch(origin + route, { method, signal: AbortSignal.timeout(10_000) })
+
+ for (const route of ['/', '/docs', '/docs/getting-started', '/withoss']) {
+ const response = await request(route)
+ assert.equal(response.status, 200, route)
+ const dom = new JSDOM(await response.text())
+ try {
+ const document = dom.window.document
+ assert.equal(document.querySelectorAll('main').length, 1, route)
+ assert.equal(document.querySelectorAll('h1').length, 1, route)
+ assert.equal(
+ document.querySelector('link[rel="canonical"]')?.href,
+ new URL(route, 'https://react-structured.dev').href,
+ route,
+ )
+ assert.ok(
+ document.querySelector('script[type="application/ld+json"]'),
+ route,
+ )
+ } finally {
+ dom.window.close()
+ }
+ const head = await request(route, 'HEAD')
+ assert.equal(head.status, 200, route)
+ assert.equal(await head.text(), '', route)
+ }
+ for (const file of [
+ 'robots.txt',
+ 'sitemap.xml',
+ 'llms.txt',
+ 'llms-full.txt',
+ ]) {
+ const response = await request('/' + file)
+ assert.equal(response.status, 200, file)
+ assert.match(
+ response.headers.get('content-type'),
+ file.endsWith('.xml') ? /application\/xml/ : /text\/plain/,
+ )
+ assert.match(await response.text(), /https:\/\/react-structured\.dev/, file)
+ const head = await request('/' + file, 'HEAD')
+ assert.equal(head.status, 200, file)
+ assert.equal(await head.text(), '', file)
+ }
+ const markdown = await request('/markdown/getting-started.md')
+ assert.equal(markdown.status, 200)
+ assert.match(markdown.headers.get('content-type'), /text\/markdown/)
+ assert.match(await markdown.text(), /react-structured/)
+ for (const route of ['/not-a-real-page', '/docs/not-a-real-page']) {
+ assert.equal((await request(route)).status, 404, route)
+ assert.equal((await request(route, 'HEAD')).status, 404, route)
+ }
+ assert.equal((await request('/docs', 'POST')).status, 405)
+ console.log(
+ 'Static docs HTTP smoke passed: content, metadata, JSON-LD, discovery files, Markdown, HEAD, and real 404s.',
+ )
+} finally {
+ if (server.listening) {
+ server.closeAllConnections()
+ await new Promise((resolve, reject) =>
+ server.close((error) => (error ? reject(error) : resolve())),
+ )
+ }
+}
diff --git a/scripts/docs-tooling.test.mjs b/scripts/docs-tooling.test.mjs
index 6f904a6..c44a470 100644
--- a/scripts/docs-tooling.test.mjs
+++ b/scripts/docs-tooling.test.mjs
@@ -5,3 +5,4 @@ import './mobile-layout.test.mjs'
import './search-recommendations.test.mjs'
import './llms.test.mjs'
import './publish-isolation.test.mjs'
+import './readme-links.test.mjs'
diff --git a/scripts/package-metadata.test.mjs b/scripts/package-metadata.test.mjs
new file mode 100644
index 0000000..218ae68
--- /dev/null
+++ b/scripts/package-metadata.test.mjs
@@ -0,0 +1,60 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+
+const pkg = JSON.parse(
+ readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+)
+const readme = readFileSync(new URL('../README.md', import.meta.url), 'utf8')
+
+test('release version matches the documentation header and changelog', () => {
+ const header = readFileSync(
+ new URL('../docs/components/docs/Navbar.tsx', import.meta.url),
+ 'utf8',
+ )
+ const changelog = readFileSync(
+ new URL('../CHANGELOG.md', import.meta.url),
+ 'utf8',
+ )
+ assert.ok(header.includes(`v${pkg.version}`))
+ assert.ok(changelog.includes(`## ${pkg.version} - `))
+})
+
+test('package metadata and README provide focused discovery and support paths', () => {
+ assert.match(pkg.description, /JSON-LD/)
+ assert.equal(pkg.homepage, 'https://react-structured.dev')
+ assert.equal(
+ pkg.bugs.url,
+ 'https://github.com/ryanhefner/react-structured/issues',
+ )
+ assert.equal(new Set(pkg.keywords).size, pkg.keywords.length)
+ for (const keyword of [
+ 'react',
+ 'json-ld',
+ 'schema-dts',
+ 'structured-data',
+ 'typescript',
+ ]) {
+ assert.ok(pkg.keywords.includes(keyword), keyword)
+ }
+ assert.match(pkg.author, /Ryan Hefner/)
+ assert.ok(
+ pkg.contributors.some(
+ ({ name, url }) =>
+ name === 'Commune Software' && url === 'https://commune.software',
+ ),
+ )
+ for (const filename of ['README.md', 'LICENSE'])
+ assert.ok(pkg.files.includes(filename))
+ for (const url of [
+ pkg.homepage,
+ `${pkg.homepage}/docs/getting-started`,
+ `${pkg.homepage}/docs/reference`,
+ pkg.bugs.url,
+ ]) {
+ assert.ok(readme.includes(`](${url})`), url)
+ }
+ assert.match(readme, /[\s\S]*```tsx/)
+ assert.match(readme, //)
+ assert.match(pkg.scripts.build, /node scripts\/readme-smoke\.mjs/)
+})
diff --git a/scripts/readme-links.test.mjs b/scripts/readme-links.test.mjs
new file mode 100644
index 0000000..0a2c3b8
--- /dev/null
+++ b/scripts/readme-links.test.mjs
@@ -0,0 +1,49 @@
+import assert from 'node:assert/strict'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import test from 'node:test'
+import { fileURLToPath } from 'node:url'
+
+const root = new URL('../', import.meta.url)
+const requireDocs = createRequire(new URL('docs/package.json', root))
+const { buildFilesystemManifest, defineDocsDiscoveryConfig } = await import(
+ requireDocs.resolve('@chakra-docs/source-filesystem')
+)
+
+test('README documentation links and fragments resolve against real published pages', async () => {
+ const manifest = await buildFilesystemManifest({
+ config: defineDocsDiscoveryConfig({
+ rootDir: fileURLToPath(new URL('docs/', root)),
+ collections: [
+ {
+ id: 'docs',
+ name: 'Documentation',
+ contentPath: 'content',
+ basePath: '/docs',
+ include: ['**/*.md'],
+ },
+ ],
+ }),
+ })
+ const readme = readFileSync(new URL('README.md', root), 'utf8')
+ let docsLinks = 0
+ for (const [, href] of readme.matchAll(/\]\(([^)\s]+)\)/g)) {
+ if (href.startsWith('#')) continue
+ if (!/^[a-z][a-z\d+.-]*:/i.test(href)) {
+ assert.ok(existsSync(new URL(href.split('#')[0], root)), href)
+ continue
+ }
+ const url = new URL(href)
+ if (url.origin !== 'https://react-structured.dev') continue
+ if (url.pathname === '/') continue
+ docsLinks++
+ const page = manifest.byRoute[url.pathname]
+ assert.ok(page, href)
+ if (url.hash)
+ assert.ok(
+ page.headings.some(({ id }) => `#${id}` === url.hash),
+ href,
+ )
+ }
+ assert.ok(docsLinks >= 8, 'README links to the focused guides and reference')
+})
diff --git a/scripts/readme-smoke.mjs b/scripts/readme-smoke.mjs
new file mode 100644
index 0000000..090ab86
--- /dev/null
+++ b/scripts/readme-smoke.mjs
@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict'
+import {
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import ts from 'typescript'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+const markdown = readFileSync(path.join(root, 'README.md'), 'utf8')
+const start = ''
+const end = ''
+assert.equal(markdown.split(start).length, 2, 'one quick-start start marker')
+assert.equal(markdown.split(end).length, 2, 'one quick-start end marker')
+assert.ok(markdown.indexOf(start) < markdown.indexOf(end))
+const section = markdown.split(start)[1].split(end)[0]
+const examples = [...section.matchAll(/^```tsx\r?\n([\s\S]*?)^```\s*$/gm)]
+assert.equal(examples.length, 1, 'one complete TSX quick start')
+
+const cache = path.join(root, '.npm-cache')
+mkdirSync(cache, { recursive: true })
+const temporary = mkdtempSync(path.join(cache, 'readme-'))
+try {
+ const source = path.join(temporary, 'quickstart.tsx')
+ const options = {
+ target: ts.ScriptTarget.ES2020,
+ module: ts.ModuleKind.ESNext,
+ moduleResolution: ts.ModuleResolutionKind.Bundler,
+ jsx: ts.JsxEmit.ReactJSX,
+ strict: true,
+ skipLibCheck: true,
+ noUnusedLocals: true,
+ noEmitOnError: true,
+ types: ['react'],
+ }
+ const host = ts.createCompilerHost(options)
+ const original = host.getSourceFile.bind(host)
+ host.getSourceFile = (filename, languageVersion, onError, fresh) =>
+ filename === source
+ ? ts.createSourceFile(
+ filename,
+ examples[0][1],
+ languageVersion,
+ true,
+ ts.ScriptKind.TSX,
+ )
+ : original(filename, languageVersion, onError, fresh)
+ host.writeFile = (filename, content) => {
+ assert.equal(filename, path.join(temporary, 'quickstart.js'))
+ writeFileSync(path.join(temporary, 'quickstart.mjs'), content)
+ }
+ const program = ts.createProgram([source], options, host)
+ const diagnostics = ts.getPreEmitDiagnostics(program)
+ assert.equal(
+ diagnostics.length,
+ 0,
+ ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+ getCurrentDirectory: () => root,
+ getCanonicalFileName: (filename) => filename,
+ getNewLine: () => '\n',
+ }),
+ )
+ assert.equal(program.emit().emitSkipped, false)
+ const example = await import(
+ pathToFileURL(path.join(temporary, 'quickstart.mjs')).href
+ )
+ assert.equal(typeof example.default, 'function')
+ const html = renderToStaticMarkup(createElement(example.default))
+ const scripts = [
+ ...html.matchAll(
+ /