From f308efc7ddece0490eb063d2840b4d57c5461fee Mon Sep 17 00:00:00 2001 From: Ryan Carniato Date: Wed, 5 Aug 2026 12:19:01 -0700 Subject: [PATCH 1/3] docs: add Solid Meta v1 documentation for the 1.0 release Solid Meta 1.0 (for Solid 2.0) is provider-less and built on the core useHead registry, so its docs get a versioned section following the same pattern as SolidStart v2: content under src/routes/solid-meta/v1 with a v1 entry on the version axis, its own sidebar, and a Latest/v1 switcher on Meta pages. Covers getting started, a 0.x migration guide, and reference pages for all components including the new groups, + ); +} +``` + +## Related + +- [`Style`](/solid-meta/v1/reference/meta/style) +- [`useHead`](/solid-meta/v1/reference/meta/use-head) diff --git a/src/routes/solid-meta/v1/reference/meta/style.mdx b/src/routes/solid-meta/v1/reference/meta/style.mdx new file mode 100644 index 0000000000..48b05c39a7 --- /dev/null +++ b/src/routes/solid-meta/v1/reference/meta/style.mdx @@ -0,0 +1,80 @@ +--- +title: Style +order: 5 +use_cases: >- + inline styles, critical css, css-in-js output +tags: + - style + - css + - head + - component +version: "1.0" +description: >- + Style adds an inline style element to the document head through Solid Meta. +--- + +`Style` adds a [`; +} +``` + +### Replaceable themed style + +```tsx +import { Style } from "@solidjs/meta"; + +export default function Theme(props: { accent: () => string }) { + return ; +} +``` + +## Related + +- [`Stylesheet`](/solid-meta/v1/reference/meta/stylesheet) +- [`Script`](/solid-meta/v1/reference/meta/script) diff --git a/src/routes/solid-meta/v1/reference/meta/stylesheet.mdx b/src/routes/solid-meta/v1/reference/meta/stylesheet.mdx new file mode 100644 index 0000000000..da35e3ff23 --- /dev/null +++ b/src/routes/solid-meta/v1/reference/meta/stylesheet.mdx @@ -0,0 +1,66 @@ +--- +title: Stylesheet +order: 4 +use_cases: >- + stylesheets, css loading, route-scoped styles +tags: + - stylesheet + - css + - link + - head + - component +version: "1.0" +description: >- + Stylesheet adds a stylesheet link element to the document head through + Solid Meta. +--- + +`Stylesheet` is sugar for [``](/solid-meta/v1/reference/meta/link). + +## Import + +```tsx +import { Stylesheet } from "@solidjs/meta"; +``` + +## Type + +```tsx +const Stylesheet: Component< + Omit, "rel"> & { key?: string } +>; +``` + +## Props + +Accepts attributes for [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) except `rel`, which is fixed to `stylesheet`. + +### `key` + +- **Type:** `string` +- **Optional:** Yes + +Overrides the default identity used for deduplication. + +## Behavior + +- Emitted eagerly: during SSR the stylesheet streams as soon as it registers, so styles load as early as possible. +- Removed when its owner disposes — navigating away from a route removes its route-scoped stylesheet. +- Dedupes by URL: registering the same `href` twice yields one element. + +## Examples + +### Route-scoped stylesheet + +```tsx +import { Stylesheet } from "@solidjs/meta"; + +export default function Dashboard() { + return ; +} +``` + +## Related + +- [`Link`](/solid-meta/v1/reference/meta/link) +- [`Style`](/solid-meta/v1/reference/meta/style) diff --git a/src/routes/solid-meta/v1/reference/meta/title.mdx b/src/routes/solid-meta/v1/reference/meta/title.mdx new file mode 100644 index 0000000000..22396fcb47 --- /dev/null +++ b/src/routes/solid-meta/v1/reference/meta/title.mdx @@ -0,0 +1,78 @@ +--- +title: Title +order: 1 +use_cases: >- + page titles, document titles, browser tab text, head metadata +tags: + - title + - head + - meta + - component +version: "1.0" +description: >- + Title sets the document title through Solid Meta. +--- + +`Title` adds a [``](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) element that sets the document title. + +## Import + +```tsx +import { Title } from "@solidjs/meta"; +``` + +## Type + +```tsx +const Title: Component<JSX.HTMLAttributes<HTMLTitleElement> & { key?: string }>; +``` + +## Props + +### `children` + +- **Type:** `JSX.Element` +- **Optional:** Yes + +Text content of the `title` element. +Applied via `textContent`, so it is always escaped. +Can be a reactive expression. + +### `key` + +- **Type:** `string` +- **Optional:** Yes + +Overrides the default identity used for deduplication. + +## Behavior + +- `title` is a hard singleton: the last-registered `<Title>` wins regardless of attributes. +- Unmounting the winning `<Title>` restores the previous one; a static `<title>` in your server shell is the final fallback. + +## Examples + +### Basic usage + +```tsx +import { Title } from "@solidjs/meta"; + +export default function Page() { + return <Title>Solid Docs; +} +``` + +### Reactive title + +```tsx +import { Title } from "@solidjs/meta"; + +export default function Product(props: { name: () => string }) { + return {props.name()} | My Store; +} +``` + +## Related + +- [`Meta`](/solid-meta/v1/reference/meta/meta) +- [`useHead`](/solid-meta/v1/reference/meta/use-head) diff --git a/src/routes/solid-meta/v1/reference/meta/use-head.mdx b/src/routes/solid-meta/v1/reference/meta/use-head.mdx new file mode 100644 index 0000000000..691e508fa5 --- /dev/null +++ b/src/routes/solid-meta/v1/reference/meta/use-head.mdx @@ -0,0 +1,84 @@ +--- +title: useHead +order: 9 +use_cases: >- + custom head tags, library authors, programmatic head management, head tag + descriptors +tags: + - use-head + - head + - primitive + - advanced +version: "1.0" +description: >- + useHead registers head tag descriptors with Solid 2.0's built-in head + registry. +--- + +`useHead` is the core primitive underneath every Solid Meta component: it registers head tag descriptors with Solid 2.0's built-in head registry. +It is re-exported from `@solidjs/web` as an escape hatch for library authors — routers, CSS-in-JS collectors, SEO policy layers. + +For application code, prefer the [components](/solid-meta/v1/reference/meta/title). + +## Import + +```tsx +import { useHead } from "@solidjs/meta"; // same as from "@solidjs/web" +``` + +## Type + +```tsx +function useHead(tag: HeadTag | HeadTag[] | (() => HeadTag | HeadTag[])): void; + +type HeadTag = { + tag: "title" | "meta" | "link" | "style" | "script" | "base"; + props: Record; + key?: string | (() => string | undefined); +}; +``` + +## Parameters + +### `tag` + +- A **single descriptor** registers one tag under the current reactive owner. +- An **array** is a group: one replacement set, with the same semantics as [``](/solid-meta/v1/reference/meta/head). +- A **function** is a reactive group: membership is re-read in a tracking scope on the client, and resolved at the owning boundary's flush on the server. + +Prop values can be functions for reactive attributes, and `props.children` provides the text body (applied via `textContent`, always escaped). + +## Behavior + +- Registrations follow the same identity, last-wins, and restore-on-disposal rules as the components — they *are* the same registry. +- Must be called under a reactive owner (component setup or a root). + +## Examples + +### Single reactive tag + +```tsx +import { useHead } from "@solidjs/meta"; + +function useDescription(desc: () => string) { + useHead({ + tag: "meta", + props: { name: "description", content: () => desc() }, + }); +} +``` + +### Reactive group + +```tsx +import { useHead, type HeadTag } from "@solidjs/meta"; + +function useSocialTags(tags: () => HeadTag[]) { + useHead(() => tags()); +} +``` + +## Related + +- [`Head`](/solid-meta/v1/reference/meta/head) +- [`Meta`](/solid-meta/v1/reference/meta/meta) diff --git a/vite.config.ts b/vite.config.ts index 21b2ae08d3..dc03bf5f6c 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -61,6 +61,7 @@ export default defineConfig({ default: "latest", values: { latest: { path: "", label: "Latest" }, + v1: { path: "v1", label: "v1" }, v2: { path: "v2", label: "v2" }, }, }, @@ -74,9 +75,13 @@ export default defineConfig({ version: ["latest", "v2"], }, { - project: ["router", "meta"], + project: "router", version: "latest", }, + { + project: "meta", + version: ["latest", "v1"], + }, ], }, overrides: [ @@ -122,7 +127,24 @@ export default defineConfig({ title: "Solid Meta", themeConfig: { sidebar: { - "/solid-meta": createFilesystemSidebar("./src/routes/solid-meta"), + "/solid-meta": createFilesystemSidebar( + "./src/routes/solid-meta", + { + filter: (item) => !item.filePath.includes("/solid-meta/v1"), + } + ), + }, + }, + }, + { + project: "meta", + version: "v1", + title: "Solid Meta", + themeConfig: { + sidebar: { + "/solid-meta/v1": createFilesystemSidebar( + "./src/routes/solid-meta/v1" + ), }, }, }, From d01de199837025b3dbc6954f4cf776e8eba48895 Mon Sep 17 00:00:00 2001 From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com> Date: Wed, 5 Aug 2026 19:20:10 +0000 Subject: [PATCH 2/3] ci: apply automated fixes --- src/routes/solid-meta/v1/(1)getting-started.mdx | 2 +- src/routes/solid-meta/v1/reference/meta/head.mdx | 8 +++++--- src/routes/solid-meta/v1/reference/meta/link.mdx | 6 ++++-- src/routes/solid-meta/v1/reference/meta/meta.mdx | 4 +++- src/routes/solid-meta/v1/reference/meta/script.mdx | 8 ++++++-- src/routes/solid-meta/v1/reference/meta/style.mdx | 4 +++- src/routes/solid-meta/v1/reference/meta/use-head.mdx | 2 +- 7 files changed, 23 insertions(+), 11 deletions(-) diff --git a/src/routes/solid-meta/v1/(1)getting-started.mdx b/src/routes/solid-meta/v1/(1)getting-started.mdx index 291b7b26bb..0df1eb0334 100644 --- a/src/routes/solid-meta/v1/(1)getting-started.mdx +++ b/src/routes/solid-meta/v1/(1)getting-started.mdx @@ -58,7 +58,7 @@ Every component accepts a `key` prop that overrides the default identity — use ``` -To manage a *set* of tags as one unit — several `og:image`s, a block of social tags that should override together — wrap them in [``](/solid-meta/v1/reference/meta/head). +To manage a _set_ of tags as one unit — several `og:image`s, a block of social tags that should override together — wrap them in [``](/solid-meta/v1/reference/meta/head). ## Server rendering diff --git a/src/routes/solid-meta/v1/reference/meta/head.mdx b/src/routes/solid-meta/v1/reference/meta/head.mdx index 73ef289a93..f50fc595c5 100644 --- a/src/routes/solid-meta/v1/reference/meta/head.mdx +++ b/src/routes/solid-meta/v1/reference/meta/head.mdx @@ -15,7 +15,7 @@ description: >- --- `Head` groups its child head tags into one replacement set. -Some head state is a *set*, not a single tag — multiple `og:image`s, or a block of social tags that should override together. +Some head state is a _set_, not a single tag — multiple `og:image`s, or a block of social tags that should override together. :::note[New in 1.0] `Head` did not exist in `@solidjs/meta` 0.x. @@ -52,7 +52,7 @@ Head tag components (and any components that render them). Tags rendered conditionally (or by child components) inside a `` join and leave the set as they mount and unmount. Group scope propagates via context through component calls. - **Nesting starts a new group.** - A `` inside another ``'s children forms its own independent group; to contribute tags *into* the surrounding group, render bare tag components instead. + A `` inside another ``'s children forms its own independent group; to contribute tags _into_ the surrounding group, render bare tag components instead. ## Examples @@ -76,7 +76,9 @@ Head tag components (and any components that render them). ```tsx import { Head, Meta, Title } from "@solidjs/meta"; -export default function Article(props: { article: () => { title: string; image: string } }) { +export default function Article(props: { + article: () => { title: string; image: string }; +}) { return ( {props.article().title} diff --git a/src/routes/solid-meta/v1/reference/meta/link.mdx b/src/routes/solid-meta/v1/reference/meta/link.mdx index e00b4e09ad..58a1c58177 100644 --- a/src/routes/solid-meta/v1/reference/meta/link.mdx +++ b/src/routes/solid-meta/v1/reference/meta/link.mdx @@ -25,7 +25,9 @@ import { Link } from "@solidjs/meta"; ## Type ```tsx -const Link: Component & { key?: string }>; +const Link: Component< + JSX.LinkHTMLAttributes & { key?: string } +>; ``` ## Props @@ -44,7 +46,7 @@ Overrides the default identity used for deduplication. - Dedupes by `rel` + `href`: the last-registered tag wins and unmounting restores the previous one. - **Icons** (`rel="icon"`, `rel="apple-touch-icon"`) dedupe by `rel` + `sizes` + `type` instead — deliberately excluding `href`. - Swapping the `href` *replaces* the favicon rather than accumulating, while size and type variants coexist. + Swapping the `href` _replaces_ the favicon rather than accumulating, while size and type variants coexist. - **Resource rels** (`preload`, `modulepreload`, `prefetch`, `preconnect`, `dns-prefetch`) render immediately and are never retracted — a fetch hint cannot be meaningfully undone. - **Stylesheets** (`rel="stylesheet"`) are emitted eagerly (SSR streams them as soon as they register) and removed when their owner disposes. diff --git a/src/routes/solid-meta/v1/reference/meta/meta.mdx b/src/routes/solid-meta/v1/reference/meta/meta.mdx index 9773da9148..2b23fd5706 100644 --- a/src/routes/solid-meta/v1/reference/meta/meta.mdx +++ b/src/routes/solid-meta/v1/reference/meta/meta.mdx @@ -26,7 +26,9 @@ import { Meta } from "@solidjs/meta"; ## Type ```tsx -const Meta: Component & { key?: string }>; +const Meta: Component< + JSX.MetaHTMLAttributes & { key?: string } +>; ``` ## Props diff --git a/src/routes/solid-meta/v1/reference/meta/script.mdx b/src/routes/solid-meta/v1/reference/meta/script.mdx index a689667fe3..37a0f656b5 100644 --- a/src/routes/solid-meta/v1/reference/meta/script.mdx +++ b/src/routes/solid-meta/v1/reference/meta/script.mdx @@ -30,7 +30,9 @@ import { Script } from "@solidjs/meta"; ## Type ```tsx -const Script: Component & { key?: string }>; +const Script: Component< + JSX.ScriptHTMLAttributes & { key?: string } +>; ``` ## Props @@ -66,7 +68,9 @@ Overrides the default identity used for deduplication. ```tsx import { Script } from "@solidjs/meta"; -export default function Product(props: { product: () => { name: string; price: number } }) { +export default function Product(props: { + product: () => { name: string; price: number }; +}) { return (