Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion api-surface.json
Original file line number Diff line number Diff line change
Expand Up @@ -347,7 +347,8 @@
"./expo-router",
"./node",
"./react",
"./schema"
"./schema",
"./web"
],
"exports": {
".": [
Expand Down Expand Up @@ -420,6 +421,10 @@
"PageHead",
"PageHeadProps"
],
"./web": [
"PageHead",
"PageHeadProps"
],
"./node": [
"AuditExportOptions",
"AuditProblem",
Expand Down
4 changes: 4 additions & 0 deletions docs/docs/seo/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,10 @@ Each returns a `JsonLd` with `@context: 'https://schema.org'` and `@type` set. E

- `<PageHead {...meta} site? active?>` — the same `PageMeta` props as the Expo Router `PageHead`, for an app with no Expo Router: React Navigation on react-native-web, a Vite build, an Electron renderer. Writes the `toHeadTags` records to `document.head` in an effect and takes them out on unmount, so the two adapters write the same head. A tag of the same name, property or `rel` that was there before, from the template or from a screen below, is taken out while this head is on and put back when it goes, and the `hreflang` links go as one set, so no language of the head below stays: a screen mounted over another wins, and the one below gets its head back. `active={false}` takes the head out for a screen that stays mounted behind another; a React Navigation screen passes `useIsFocused()`. Native renders `null`. An effect never runs on a server, so a static file gets its head from `headTagsHtml` at build time.

## `@rootnative/seo/web` — peers: react, react-native; no router

- `<PageHead {...meta} site? active?>` — the same props as the `/dom` `PageHead`, for an app with no Expo Router that renders on a server or prerenders at build time. Renders the `toHeadTags` records as `<title>`, `<meta>` and `<link>` elements. React 19 moves them into `<head>`, on the server and in the browser, so the HTML file has the head and no `headTagsHtml` step is necessary. The JSON-LD is a `<script type="application/ld+json">` in the page body. After the first render it takes out the `<title>` and each head tag in a page slot that it did not render (the tags of the HTML template), and puts them back when it goes. React does not merge two heads: a screen that stays mounted behind another passes `active={false}` (with React Navigation, `useIsFocused()`), or the head holds the tags of both. Native renders `null`. Use `/dom` for an app that only renders in the browser and stacks screens: there, a screen mounted over another wins with no `active` prop.

## `@rootnative/seo/expo-image` — optional peer: expo-image `>=57.0.0`

- `<Picture source alt width height srcSet? sizes? contentFit? loading? fetchPriority? site? style? testID?>` — an image a crawler sees. On the web a plain `<img>` with `src`, `alt`, `width`, `height`, `loading` (default `lazy`), `decoding="async"` and `object-fit` from `contentFit` (default `cover`); on native `expo-image` with `alt` and `accessibilityLabel`. `srcSet` lists more files of the image as `{ source, width }`, with the width in pixels: the web writes `srcset` and `sizes`, so the browser picks a file by the shown width and the pixel density before any script runs, and native gives the files to `expo-image` in place of `source`, which picks one by the view size and the screen scale. Pass `sizes` with `srcSet`, for example `'160px'`; without it the browser takes `100vw`. `fetchPriority="high"` on the hero image, the one the page is built around: the web writes `fetchpriority`, so the browser starts that download before layout, and native gives `expo-image` the value as `priority`. `source` is absolute, or a path under the site URL like `PageMeta.image`: the web gets the path under the host, native the absolute URL, and a relative one needs the site from `SeoProvider` or the `site` prop. `style` is a React Native image style that comes after the `width` and `height` box, so a size in `style` wins; set a side to `undefined` to let `flex` or `aspectRatio` size it. The web lays out the `<img>` as a react-native-web view, and flattens the style to CSS. `alt=""` marks a decorative image.
Expand Down
21 changes: 21 additions & 0 deletions docs/docs/seo/checklist.md
Original file line number Diff line number Diff line change
Expand Up @@ -349,6 +349,27 @@ const head = headTagsHtml(toHeadTags(site, { title: 'Trek', url: '/' }))
const html = template.replace('</head>', `${head}</head>`)
```

### An app that renders on a server

An app with no Expo Router that renders its pages on a server, or prerenders
them at build time, takes `PageHead` from `@rootnative/seo/web`. It has the
same props. It renders the tags as elements, and React 19 moves them into
`<head>` on the server and in the browser. So the HTML file has the head of
the page, and you need no `headTagsHtml` step.

```tsx
import { PageHead } from '@rootnative/seo/web'

export function MovieScreen() {
return <PageHead title={data.title} url={`/movies/${data.id}`} />
}
```

React does not merge two heads. A screen that stays mounted behind another
must pass `active={false}`, or the head holds the tags of both screens. The
tags of your HTML template in the same slots are taken out while the page
is on, and put back when it goes.

### Per-route `noindex`

An overlay route, a filter sheet, or a per-device screen is a page the
Expand Down
4 changes: 4 additions & 0 deletions docs/static/llms-full.txt
Original file line number Diff line number Diff line change
Expand Up @@ -3154,6 +3154,10 @@ Each returns a `JsonLd` with `@context: 'https://schema.org'` and `@type` set. E

- `<PageHead {...meta} site? active?>` — the same `PageMeta` props as the Expo Router `PageHead`, for an app with no Expo Router: React Navigation on react-native-web, a Vite build, an Electron renderer. Writes the `toHeadTags` records to `document.head` in an effect and takes them out on unmount, so the two adapters write the same head. A tag of the same name, property or `rel` that was there before, from the template or from a screen below, is taken out while this head is on and put back when it goes, and the `hreflang` links go as one set, so no language of the head below stays: a screen mounted over another wins, and the one below gets its head back. `active={false}` takes the head out for a screen that stays mounted behind another; a React Navigation screen passes `useIsFocused()`. Native renders `null`. An effect never runs on a server, so a static file gets its head from `headTagsHtml` at build time.

## `@rootnative/seo/web` — peers: react, react-native; no router

- `<PageHead {...meta} site? active?>` — the same props as the `/dom` `PageHead`, for an app with no Expo Router that renders on a server or prerenders at build time. Renders the `toHeadTags` records as `<title>`, `<meta>` and `<link>` elements. React 19 moves them into `<head>`, on the server and in the browser, so the HTML file has the head and no `headTagsHtml` step is necessary. The JSON-LD is a `<script type="application/ld+json">` in the page body. After the first render it takes out the `<title>` and each head tag in a page slot that it did not render (the tags of the HTML template), and puts them back when it goes. React does not merge two heads: a screen that stays mounted behind another passes `active={false}` (with React Navigation, `useIsFocused()`), or the head holds the tags of both. Native renders `null`. Use `/dom` for an app that only renders in the browser and stacks screens: there, a screen mounted over another wins with no `active` prop.

## `@rootnative/seo/expo-image` — optional peer: expo-image `>=57.0.0`

- `<Picture source alt width height srcSet? sizes? contentFit? loading? fetchPriority? site? style? testID?>` — an image a crawler sees. On the web a plain `<img>` with `src`, `alt`, `width`, `height`, `loading` (default `lazy`), `decoding="async"` and `object-fit` from `contentFit` (default `cover`); on native `expo-image` with `alt` and `accessibilityLabel`. `srcSet` lists more files of the image as `{ source, width }`, with the width in pixels: the web writes `srcset` and `sizes`, so the browser picks a file by the shown width and the pixel density before any script runs, and native gives the files to `expo-image` in place of `source`, which picks one by the view size and the screen scale. Pass `sizes` with `srcSet`, for example `'160px'`; without it the browser takes `100vw`. `fetchPriority="high"` on the hero image, the one the page is built around: the web writes `fetchpriority`, so the browser starts that download before layout, and native gives `expo-image` the value as `priority`. `source` is absolute, or a path under the site URL like `PageMeta.image`: the web gets the path under the host, native the absolute URL, and a relative one needs the site from `SeoProvider` or the `site` prop. `style` is a React Native image style that comes after the `width` and `height` box, so a size in `style` wins; set a side to `undefined` to let `flex` or `aspectRatio` size it. The web lays out the `<img>` as a react-native-web view, and flattens the style to CSS. `alt=""` marks a decorative image.
Expand Down
1 change: 1 addition & 0 deletions packages/seo/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ pnpm add @rootnative/seo
| `@rootnative/seo/expo-router` | `expo-router` | `PageHead`, `RouteHead`, `shellTags` |
| `@rootnative/seo/expo-image` | `expo-image` | `Picture`: a plain `<img>` on the web, `expo-image` on native |
| `@rootnative/seo/dom` | `react`, `react-native` | `PageHead` for an app with no Expo Router: writes the same tags to `document.head` |
| `@rootnative/seo/web` | `react`, `react-native` | `PageHead` for an app with no Expo Router that renders on a server or prerenders: the same tags as elements, which React moves into the head |
| `@rootnative/seo/node` | Node | `writeSeoFiles`, `auditExport`, `browseExport`, `serveExport`, the `rootnative-seo` command, `readExport`, `writeSitemap`, `writeRobots`, `writeManifest` |

## Quick start (Expo Router)
Expand Down
4 changes: 4 additions & 0 deletions packages/seo/llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,10 @@ Each returns a `JsonLd` with `@context: 'https://schema.org'` and `@type` set. E

- `<PageHead {...meta} site? active?>` — the same `PageMeta` props as the Expo Router `PageHead`, for an app with no Expo Router: React Navigation on react-native-web, a Vite build, an Electron renderer. Writes the `toHeadTags` records to `document.head` in an effect and takes them out on unmount, so the two adapters write the same head. A tag of the same name, property or `rel` that was there before, from the template or from a screen below, is taken out while this head is on and put back when it goes, and the `hreflang` links go as one set, so no language of the head below stays: a screen mounted over another wins, and the one below gets its head back. `active={false}` takes the head out for a screen that stays mounted behind another; a React Navigation screen passes `useIsFocused()`. Native renders `null`. An effect never runs on a server, so a static file gets its head from `headTagsHtml` at build time.

## `@rootnative/seo/web` — peers: react, react-native; no router

- `<PageHead {...meta} site? active?>` — the same props as the `/dom` `PageHead`, for an app with no Expo Router that renders on a server or prerenders at build time. Renders the `toHeadTags` records as `<title>`, `<meta>` and `<link>` elements. React 19 moves them into `<head>`, on the server and in the browser, so the HTML file has the head and no `headTagsHtml` step is necessary. The JSON-LD is a `<script type="application/ld+json">` in the page body. After the first render it takes out the `<title>` and each head tag in a page slot that it did not render (the tags of the HTML template), and puts them back when it goes. React does not merge two heads: a screen that stays mounted behind another passes `active={false}` (with React Navigation, `useIsFocused()`), or the head holds the tags of both. Native renders `null`. Use `/dom` for an app that only renders in the browser and stacks screens: there, a screen mounted over another wins with no `active` prop.

## `@rootnative/seo/expo-image` — optional peer: expo-image `>=57.0.0`

- `<Picture source alt width height srcSet? sizes? contentFit? loading? fetchPriority? site? style? testID?>` — an image a crawler sees. On the web a plain `<img>` with `src`, `alt`, `width`, `height`, `loading` (default `lazy`), `decoding="async"` and `object-fit` from `contentFit` (default `cover`); on native `expo-image` with `alt` and `accessibilityLabel`. `srcSet` lists more files of the image as `{ source, width }`, with the width in pixels: the web writes `srcset` and `sizes`, so the browser picks a file by the shown width and the pixel density before any script runs, and native gives the files to `expo-image` in place of `source`, which picks one by the view size and the screen scale. Pass `sizes` with `srcSet`, for example `'160px'`; without it the browser takes `100vw`. `fetchPriority="high"` on the hero image, the one the page is built around: the web writes `fetchpriority`, so the browser starts that download before layout, and native gives `expo-image` the value as `priority`. `source` is absolute, or a path under the site URL like `PageMeta.image`: the web gets the path under the host, native the absolute URL, and a relative one needs the site from `SeoProvider` or the `site` prop. `style` is a React Native image style that comes after the `width` and `height` box, so a size in `style` wins; set a side to `undefined` to let `flex` or `aspectRatio` size it. The web lays out the `<img>` as a react-native-web view, and flattens the style to CSS. `alt=""` marks a decorative image.
Expand Down
9 changes: 9 additions & 0 deletions packages/seo/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,12 @@
"import": "./dist/dom/index.mjs",
"default": "./dist/dom/index.mjs"
},
"./web": {
"types": "./dist/web/index.d.mts",
"react-native": "./dist/web/index.mjs",
"import": "./dist/web/index.mjs",
"default": "./dist/web/index.mjs"
},
"./expo-image": {
"types": "./dist/expo-image/index.d.mts",
"react-native": "./dist/expo-image/index.mjs",
Expand All @@ -70,6 +76,9 @@
"dom": [
"dist/dom/index.d.mts"
],
"web": [
"dist/web/index.d.mts"
],
"expo-image": [
"dist/expo-image/index.d.mts"
],
Expand Down
49 changes: 49 additions & 0 deletions packages/seo/src/__tests__/web-head-server.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import { renderToString } from 'react-dom/server'
import { defineSite } from '../index'
import { SeoProvider } from '../react'
import { movie } from '../schema'
import { PageHead } from '../web'

// The component renders nothing on native, and this project runs as native.
// `react-dom/server` needs a `MessageChannel`, which the `web` project does
// not have, so the server render is tested here.
jest.mock('react-native', () => ({ Platform: { OS: 'web' } }))

const site = defineSite({ name: 'Trek', url: 'https://example.com/app' })

describe('PageHead from /web on a server', () => {
it('puts the head in the HTML', () => {
const html = renderToString(
<SeoProvider site={site}>
<PageHead
title="Dune"
description="A duke moves to a desert planet."
url="/movies/1"
alternates={[
{ lang: 'en', url: '/movies/1' },
{ lang: 'de', url: '/de/movies/1' },
]}
jsonLd={[
movie({ name: 'Dune', url: 'https://example.com/app/movies/1' }),
]}
/>
</SeoProvider>,
)
expect(html).toContain('>Dune | Trek</title>')
expect(html).toContain('content="A duke moves to a desert planet."')
expect(html).toContain(
'<link rel="canonical" href="https://example.com/app/movies/1"',
)
expect(html).toContain('hrefLang="de"')
expect(html).toContain('<script type="application/ld+json">')
})

it('renders no tag while active is false', () => {
const html = renderToString(
<SeoProvider site={site}>
<PageHead title="Dune" url="/movies/1" active={false} />
</SeoProvider>,
)
expect(html).toBe('')
})
})
Loading
Loading