https://github.com/jdevalk/seo-graph
Agent-ready SEO for JavaScript — schema.org JSON-LD graph builder with an Astro integration.
https://github.com/jdevalk/seo-graph
Last synced: about 2 months ago
JSON representation
Agent-ready SEO for JavaScript — schema.org JSON-LD graph builder with an Astro integration.
- Host: GitHub
- URL: https://github.com/jdevalk/seo-graph
- Owner: jdevalk
- License: mit
- Created: 2026-04-09T07:41:04.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-09T08:04:33.000Z (2 months ago)
- Last Synced: 2026-04-09T09:29:22.085Z (2 months ago)
- Language: TypeScript
- Homepage: https://joost.blog
- Size: 79.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-geo - SEO Graph - ready Schema.org JSON-LD graph builder for JavaScript with an Astro integration. | (Open-Source Repos & Tools / Structured Data & Schema)
README
# seo-graph
[](https://github.com/jdevalk/seo-graph/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@jdevalk/seo-graph-core)
[](https://www.npmjs.com/package/@jdevalk/astro-seo-graph)
[](./LICENSE)
> Agent-ready SEO for JavaScript. A pure schema.org JSON-LD graph builder plus
> an Astro integration, designed to be shared across frameworks and CMSes.
This monorepo ships two packages (plus a third consumer living elsewhere):
| Package | Purpose |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| [`@jdevalk/seo-graph-core`](./packages/seo-graph-core) | Pure, runtime-agnostic schema.org piece builders and graph assembler. Depends only on [`schema-dts`](https://github.com/google/schema-dts). |
| [`@jdevalk/astro-seo-graph`](./packages/astro-seo-graph) | Astro integration: `` component, route factories for agent-ready endpoints, breadcrumb helper, Zod content helpers. |
| [`@jdevalk/emdash-plugin-seo`](https://github.com/jdevalk/emdash-plugin-seo) | EmDash CMS plugin. Lives in its own repo, depends on `seo-graph-core`. |
## Documentation
See [AGENTS.md](./AGENTS.md) for the full reference: all builder signatures,
site-type recipes (blog, e-commerce, local business, docs, podcast, etc.),
and schema.org best practices. It's written for both humans and AI coding
agents.
## Why
Read more about [why this project exists](https://joost.blog/seo-graph/).
## Develop
```sh
pnpm install
pnpm typecheck
pnpm build
pnpm test
```
## Architecture notes
- **No page-type enum in core.** Core exposes piece builders; dispatch lives in
the caller. This keeps the core's API surface small and avoids baking a
specific content model into a shared lib.
- **[`schema-dts`](https://github.com/google/schema-dts) is the type substrate.**
All builders accept schema.org properties at the top level with full
autocomplete from `schema-dts`. `buildPiece` gives you every
Product property typed; the `@type` value narrows union types to the
matching leaf automatically.
- **Dedicated builders for non-trivial work.** Seven builders handle ID
generation, date conversion, and transforms (`buildWebSite`, `buildWebPage`,
`buildArticle`, `buildBreadcrumbList`, `buildImageObject`, `buildVideoObject`,
`buildSiteNavigationElement`). Everything else — Person, Organization, Blog,
Product, Recipe, Event, etc. — uses `buildPiece`.
- **Breadcrumbs are an input, not a derivation.** Callers pre-compute the
breadcrumb list. The Astro integration ships `breadcrumbsFromUrl` to
derive crumbs from an `Astro.url`, but the core itself has no
URL-parsing logic.
## License
MIT © Joost de Valk