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 @@ [![codecov](https://codecov.io/gh/ryanhefner/react-structured/branch/main/graph/badge.svg)](https://codecov.io/gh/ryanhefner/react-structured) [![license](https://img.shields.io/npm/l/react-structured.svg)](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( + /]*type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g, + ), + ] + assert.equal(scripts.length, 1) + const data = JSON.parse(scripts[0][1]) + assert.equal(data['@context'], 'https://schema.org') + assert.equal(data['@type'], 'Organization') + assert.ok(data.name) + assert.ok(html.includes('

')) + console.log( + 'Actual README quick start typechecked against public exports and rendered valid JSON-LD.', + ) +} finally { + rmSync(temporary, { recursive: true, force: true }) +} diff --git a/scripts/tooling.test.mjs b/scripts/tooling.test.mjs index eab7116..42ea16e 100644 --- a/scripts/tooling.test.mjs +++ b/scripts/tooling.test.mjs @@ -1,4 +1,5 @@ import './test-suites.test.mjs' +import './package-metadata.test.mjs' import assert from 'node:assert/strict' import { readFileSync, existsSync } from 'node:fs' import test from 'node:test'