sugikit 0.0.1 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +29 -21
- package/README.md +45 -0
- package/dist/api/browser.d.ts +5 -0
- package/dist/api/browser.js +5 -0
- package/dist/api/rules.d.ts +12 -0
- package/dist/api/rules.js +14 -0
- package/dist/auth.d.ts +156 -0
- package/dist/auth.js +547 -0
- package/dist/browser.d.ts +25 -0
- package/dist/browser.js +120 -0
- package/dist/check.d.ts +21 -0
- package/dist/check.js +89 -0
- package/dist/convert-probe.d.ts +21 -0
- package/dist/convert-probe.js +647 -0
- package/dist/fetch.d.ts +6 -0
- package/dist/fetch.js +22 -0
- package/dist/framework.d.ts +2 -0
- package/dist/framework.js +17 -0
- package/dist/gather.d.ts +48 -0
- package/dist/gather.js +211 -0
- package/dist/html.d.ts +17 -0
- package/dist/html.js +43 -0
- package/dist/http.d.ts +36 -0
- package/dist/http.js +57 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +331 -0
- package/dist/links.d.ts +8 -0
- package/dist/links.js +69 -0
- package/dist/polish-run.d.ts +115 -0
- package/dist/polish-run.js +357 -0
- package/dist/probe.d.ts +14 -0
- package/dist/probe.js +457 -0
- package/dist/psi-scores.d.ts +4 -0
- package/dist/psi-scores.js +7 -0
- package/dist/psi.d.ts +56 -0
- package/dist/psi.js +192 -0
- package/dist/release.d.ts +1 -0
- package/dist/release.js +5 -0
- package/dist/render.d.ts +28 -0
- package/dist/render.js +270 -0
- package/dist/report.d.ts +227 -0
- package/dist/report.js +69 -0
- package/dist/rules/convert-render.d.ts +100 -0
- package/dist/rules/convert-render.js +279 -0
- package/dist/rules/convert.d.ts +15 -0
- package/dist/rules/convert.js +322 -0
- package/dist/rules/fixes.d.ts +16 -0
- package/dist/rules/fixes.js +536 -0
- package/dist/rules/geo.d.ts +15 -0
- package/dist/rules/geo.js +112 -0
- package/dist/rules/polish.d.ts +59 -0
- package/dist/rules/polish.js +223 -0
- package/dist/rules/robots.d.ts +14 -0
- package/dist/rules/robots.js +69 -0
- package/dist/rules/seo.d.ts +31 -0
- package/dist/rules/seo.js +208 -0
- package/dist/rules/types.d.ts +55 -0
- package/dist/rules/types.js +78 -0
- package/dist/score.d.ts +6 -0
- package/dist/score.js +23 -0
- package/dist/skills.d.ts +9 -0
- package/dist/skills.js +22 -0
- package/package.json +64 -4
- package/skills/INSTALL_PROMPT.md +9 -0
- package/skills/sugikit/SKILL.md +147 -0
- package/skills/sugikit/references/convert.md +127 -0
- package/skills/sugikit/references/geo.md +97 -0
- package/skills/sugikit/references/next.md +254 -0
- package/skills/sugikit/references/pagespeed.md +94 -0
- package/skills/sugikit/references/polish.md +123 -0
- package/skills/sugikit/references/seo.md +150 -0
- package/skills/sugikit/references/tanstack-start.md +246 -0
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Polish rules
|
|
2
|
+
|
|
3
|
+
Sugikit loads the page in headless Chromium in four states: `desktop-light` (1440 px wide), `desktop-dark`, `phone-light` and `phone-dark`, plus `phone-light-reduced-motion`. Screenshots of each state are in `<report name>-shots/` next to the report (`.sugikit/report-shots/`, `.sugikit/before-shots/`). Look at them before and after a visible fix.
|
|
4
|
+
|
|
5
|
+
General rule for this category: keep the look. Change the smallest property that makes the rule pass. When a change is visible, list it for the user with the old and new value.
|
|
6
|
+
|
|
7
|
+
## polish/horizontal-scroll (error)
|
|
8
|
+
|
|
9
|
+
Measures: on `phone-light`, the page is wider than the viewport, so it scrolls sideways. `evidence` lists the elements that stick out past the right edge.
|
|
10
|
+
|
|
11
|
+
Fix:
|
|
12
|
+
- Find the listed element and the rule that makes it wide: a fixed `width`, a `min-width`, a wide table or code block, a long unbroken word or URL, an image or video without `max-width`, a negative margin, or a transform.
|
|
13
|
+
- Let it shrink: `max-width: 100%` on media, `min-width: 0` on flex or grid children, `overflow-wrap: anywhere` on long strings, `overflow-x: auto` on the table or code block itself (not on the page).
|
|
14
|
+
- Do not put `overflow-x: hidden` on `html` or `body`. It hides the bug and can break `position: sticky`.
|
|
15
|
+
|
|
16
|
+
## polish/tap-targets (warn)
|
|
17
|
+
|
|
18
|
+
Measures: on `phone-light`, links, buttons, inputs, selects, summaries and ARIA buttons, links, tabs and menu items with a hit area smaller than 24x24 CSS px, with the WCAG 2.5.8 exceptions: links inside a line of text, unstyled native controls the browser sizes, and controls spaced so a 24 px circle centered on each does not touch another control or another small control's circle.
|
|
19
|
+
|
|
20
|
+
Fix:
|
|
21
|
+
- Grow the hit area, not the visible control. Add padding and balance it with a negative margin, or set `min-height` and `min-width` on the link, or use a `::before` overlay with `position: absolute; inset: -8px`.
|
|
22
|
+
- Spacing also passes: a small control is fine when nothing else sits within 12 px of its center.
|
|
23
|
+
- 44x44 px is better on touch, but 24x24 is the rule. Do not resize icons or change font size to pass.
|
|
24
|
+
|
|
25
|
+
## polish/contrast (error)
|
|
26
|
+
|
|
27
|
+
Measures: text with contrast below 4.5:1 (3:1 for large text: 24 px, or 18.66 px bold) in any of the four states. `evidence` gives the element, the ratio and the states where it fails. A failure only in `-dark` states means the dark theme values are wrong.
|
|
28
|
+
|
|
29
|
+
Fix:
|
|
30
|
+
- Change the color token or class that sets the color, not one element inline, so the whole site stays consistent.
|
|
31
|
+
- Keep the hue. Move to the next darker step of the same color (light theme) or the next lighter step (dark theme). In Tailwind, `text-gray-400` becomes `text-gray-500` or `text-gray-600`, not `text-slate-700`. With OKLCH tokens, change only the lightness.
|
|
32
|
+
- Choose the closest step that passes. Check both themes after the change.
|
|
33
|
+
- Text on images or gradients: add a scrim or darken the overlay a little. Do not remove the image.
|
|
34
|
+
- List each changed color for the user.
|
|
35
|
+
|
|
36
|
+
## polish/axe (warn)
|
|
37
|
+
|
|
38
|
+
Measures: serious or critical axe-core violations in `desktop-light`, except color contrast (that is `polish/contrast`). `evidence` lists axe rule ids with impact and count. Each id is explained at `https://dequeuniversity.com/rules/axe/<version>/<id>`.
|
|
39
|
+
|
|
40
|
+
Common ids and fixes:
|
|
41
|
+
- `button-name`, `link-name`: icon-only buttons and links need an accessible name. Add `aria-label` with what the control does, or visually hidden text.
|
|
42
|
+
- `image-alt`: add `alt`. Use `alt=""` for decorative images.
|
|
43
|
+
- `label`: form inputs need a `<label>` or `aria-label`. A placeholder is not a label.
|
|
44
|
+
- `aria-*` ids (`aria-allowed-attr`, `aria-required-children`, `aria-valid-attr-value`): fix the ARIA, or remove ARIA that native HTML already gives.
|
|
45
|
+
- `list`, `listitem`: `<li>` must be inside `<ul>` or `<ol>`.
|
|
46
|
+
- `nested-interactive`: do not put a button inside a link or a link inside a button.
|
|
47
|
+
- `frame-title`: give embedded iframes a `title`.
|
|
48
|
+
|
|
49
|
+
These fixes should not change how the page looks.
|
|
50
|
+
|
|
51
|
+
## polish/type-scale (warn)
|
|
52
|
+
|
|
53
|
+
Measures: more than 12 font size steps on `desktop-light` (visible paragraphs, list items, headings, link and button labels, quotes and table cells; sizes within 1 px count as one step).
|
|
54
|
+
|
|
55
|
+
Fix:
|
|
56
|
+
- List the sizes in `evidence`. Merge sizes that are close (15 px and 16 px, 13 px and 14 px) into the one the design uses most.
|
|
57
|
+
- Define the steps once (CSS variables or the Tailwind theme) and use only those steps.
|
|
58
|
+
- Keep the fonts, weights and the hierarchy between headings.
|
|
59
|
+
|
|
60
|
+
## polish/body-text-size (warn)
|
|
61
|
+
|
|
62
|
+
Measures: on `phone-light`, the share of body paragraph text (paragraphs of 60+ characters outside footer, aside, nav, small and figcaption, counted by characters) under 15 px. Fails above 50%. `evidence` gives the share, the most common small size and the paragraphs. 14 px body text fails; 15 px passes; a few small captions or notes never fail.
|
|
63
|
+
|
|
64
|
+
Fix:
|
|
65
|
+
- Raise the main paragraph text to 16 px on phones with a step that already exists in the type scale. In Tailwind the unprefixed class is the phone size, so `text-sm md:text-base` gives 14 px on phones; use `text-base` as the base (or `text-base md:text-sm` to keep desktop as is).
|
|
66
|
+
- Keep the font and the hierarchy. Captions, notes and dense UI labels can stay small.
|
|
67
|
+
|
|
68
|
+
## polish/line-length (warn)
|
|
69
|
+
|
|
70
|
+
Measures: paragraphs at 1440 px with more than 85 characters per line.
|
|
71
|
+
|
|
72
|
+
Fix:
|
|
73
|
+
- Add `max-width: 65ch` (Tailwind `max-w-prose` or `max-w-[65ch]`) to the paragraph or its text wrapper, not to the whole section, so backgrounds and grids keep their width.
|
|
74
|
+
- Keep the text alignment. If the text is centered, add `margin-inline: auto` so it stays centered.
|
|
75
|
+
|
|
76
|
+
## polish/spacing-scale (warn)
|
|
77
|
+
|
|
78
|
+
Measures: distinct padding, margin and gap values on `desktop-light`. Fails when more than a quarter of them are not multiples of 4 px. `evidence` lists the off-grid values.
|
|
79
|
+
|
|
80
|
+
Fix:
|
|
81
|
+
- Round each listed value to the nearest multiple of 4 px (13 px to 12 px, 18 px to 16 px or 20 px).
|
|
82
|
+
- Replace Tailwind arbitrary values (`p-[13px]`, `mt-[18px]`) with scale steps (`p-3`, `mt-5`).
|
|
83
|
+
- Values from `em` or `rem` units at odd font sizes can be off-grid. Change the value, not the font size.
|
|
84
|
+
- The visual change is a few pixels. Do not change the layout.
|
|
85
|
+
|
|
86
|
+
## polish/img-dimensions (warn)
|
|
87
|
+
|
|
88
|
+
Measures: images with no width and height (they cause layout shift) and images whose file is more than 2x their displayed size (wasted bytes).
|
|
89
|
+
|
|
90
|
+
Fix:
|
|
91
|
+
- Add `width` and `height` attributes with the file's real pixel size, or a CSS `aspect-ratio` on the image or its box. CSS can still make it responsive (`width: 100%; height: auto`).
|
|
92
|
+
- Oversized files: serve a resized file. Use the framework image component, or add `srcset` and `sizes` with resized files. Do not lower the quality of the hero image so it looks worse.
|
|
93
|
+
|
|
94
|
+
## polish/dark-mode (info, or warn when half done)
|
|
95
|
+
|
|
96
|
+
Measures: whether the page background and text color change between `desktop-light` and `desktop-dark` (`prefers-color-scheme: dark`). Info when there is no dark mode. Warn when only the background or only the text changes, because that is broken.
|
|
97
|
+
|
|
98
|
+
Fix:
|
|
99
|
+
- Half done (warn): add the missing value so background and text change together. Check `polish/contrast` in the dark states after.
|
|
100
|
+
- No dark mode (info): optional. Add one only if the user wants it. Build it from the existing palette (the darkest neutral as background, the lightest as text). Add `color-scheme: light dark` on `:root`.
|
|
101
|
+
- If the site has a theme toggle with a class (`.dark`), keep it and make the default follow `prefers-color-scheme`.
|
|
102
|
+
|
|
103
|
+
## polish/reduced-motion (warn)
|
|
104
|
+
|
|
105
|
+
Measures: animations that are endless or long and still run when `prefers-reduced-motion: reduce` is on.
|
|
106
|
+
|
|
107
|
+
Fix:
|
|
108
|
+
- Put the animation inside `@media (prefers-reduced-motion: no-preference) { ... }`, or set `animation: none` and `transition: none` for the listed selectors under `@media (prefers-reduced-motion: reduce)`.
|
|
109
|
+
- Motion (Framer Motion): wrap the app in `<MotionConfig reducedMotion="user">`.
|
|
110
|
+
- Keep the animation for everyone else. Do not remove it.
|
|
111
|
+
- Reduced motion means less motion, not no feedback. Short fades and color changes can stay.
|
|
112
|
+
|
|
113
|
+
## polish/browser (error)
|
|
114
|
+
|
|
115
|
+
Measures: Sugikit could not start headless Chromium, so no polish checks ran.
|
|
116
|
+
|
|
117
|
+
Fix: run `npx sugikit browsers install` and check again. If install is not possible, run with `--no-browser` and tell the user polish was skipped.
|
|
118
|
+
|
|
119
|
+
## polish/slow-page (info)
|
|
120
|
+
|
|
121
|
+
Measures: the check ran past its time budget (`--timeout`, default 120 s), so it skipped the optional browser checks named in `evidence` (dark states, the reduced motion run, CTA click tests). Video and audio are never downloaded during polish checks.
|
|
122
|
+
|
|
123
|
+
Fix: run `sugikit check` again with a longer `--timeout`. If the page is slow for visitors too, make it lighter: smaller hero media, lazy-loaded images and video, fewer third-party scripts.
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# SEO rules
|
|
2
|
+
|
|
3
|
+
Sugikit reads the server HTML of the page (no JavaScript), the response headers, `/robots.txt` and the sitemap. A tag that only appears after client JavaScript runs does not count. Put meta tags in the framework's head API, which renders them on the server.
|
|
4
|
+
|
|
5
|
+
All text you write here (title, description, alt text, JSON-LD) comes from the page's own words. Never invent features, prices, ratings or claims.
|
|
6
|
+
|
|
7
|
+
## seo/http-status (error)
|
|
8
|
+
|
|
9
|
+
Measures: the page URL returns a 2xx status.
|
|
10
|
+
|
|
11
|
+
Fix: a 404 or 500 means the URL is wrong or the dev server is broken. Check the path, the dev server log and the port. Fix this before any other rule; the other results are not useful until the page loads.
|
|
12
|
+
|
|
13
|
+
## seo/fetch-blocked (info)
|
|
14
|
+
|
|
15
|
+
Measures: the plain HTTP request for the page got 403, 429, 503 or a bot challenge page, but the headless browser loaded it. Sugikit then checked the HTML the browser got. Only reported when browser checks run (not with `--no-browser`).
|
|
16
|
+
|
|
17
|
+
Fix: optional, but search and AI crawlers may be blocked the same way. Check the bot protection and WAF rules of the host or CDN (Cloudflare Bot Fight Mode, Vercel Firewall and similar): allow Googlebot, Bingbot, GPTBot, ClaudeBot and PerplexityBot to fetch the page without a challenge. In Next.js, also check that middleware (proxy.ts in Next.js 16) does not block these user agents; in TanStack Start, the global request middleware in src/start.ts.
|
|
18
|
+
|
|
19
|
+
## seo/title (error)
|
|
20
|
+
|
|
21
|
+
Measures: the page has a non-empty `<title>` in `<head>`.
|
|
22
|
+
|
|
23
|
+
Fix: name the product and what it does, from the hero headline. Pattern: `Product: what it does` or `Product - what it does`. Set it through the framework head API, once per page.
|
|
24
|
+
|
|
25
|
+
## seo/title-length (warn)
|
|
26
|
+
|
|
27
|
+
Measures: the title is 30 to 60 characters.
|
|
28
|
+
|
|
29
|
+
Fix: too short, add the main benefit from the hero. Too long, cut extra words or a site-wide suffix. Keep the product name first. Check the result with the length rule before you move on.
|
|
30
|
+
|
|
31
|
+
## seo/meta-description (error)
|
|
32
|
+
|
|
33
|
+
Measures: `<meta name="description">` exists with content.
|
|
34
|
+
|
|
35
|
+
Fix: one or two sentences that say what the product does and for whom. Take them from the hero paragraph and the first section. Do not add claims the page does not make.
|
|
36
|
+
|
|
37
|
+
## seo/meta-description-length (warn)
|
|
38
|
+
|
|
39
|
+
Measures: the description is 70 to 160 characters.
|
|
40
|
+
|
|
41
|
+
Fix: shorten or extend with the page's own words. Count the characters.
|
|
42
|
+
|
|
43
|
+
## seo/html-lang (error)
|
|
44
|
+
|
|
45
|
+
Measures: `<html>` has a `lang` attribute.
|
|
46
|
+
|
|
47
|
+
Fix: set it in the root layout or shell to the page language (`en`, `en-US`, `de`). Use the language the copy is written in.
|
|
48
|
+
|
|
49
|
+
## seo/viewport (error)
|
|
50
|
+
|
|
51
|
+
Measures: `<meta name="viewport">` exists.
|
|
52
|
+
|
|
53
|
+
Fix: `width=device-width, initial-scale=1`. Do not add `maximum-scale=1` or `user-scalable=no`; they block zoom.
|
|
54
|
+
|
|
55
|
+
## seo/canonical (error)
|
|
56
|
+
|
|
57
|
+
Measures: `<link rel="canonical">` exists and its `href` is an absolute http(s) URL.
|
|
58
|
+
|
|
59
|
+
Fix: the absolute production URL of this page, for example `https://example.com/`. This needs the production domain. If the project does not state it (env var, config, existing og:url), ask the user. Do not use the localhost URL. Do not guess a domain.
|
|
60
|
+
|
|
61
|
+
## seo/open-graph (warn)
|
|
62
|
+
|
|
63
|
+
Measures: `og:title`, `og:description`, `og:url` and `og:image` all exist, and `og:image` is an absolute http(s) URL.
|
|
64
|
+
|
|
65
|
+
Fix:
|
|
66
|
+
- Reuse the title and description.
|
|
67
|
+
- `og:url` is the canonical URL.
|
|
68
|
+
- `og:image` must be absolute (needs the production domain). Use an existing share image (1200x630) from the project. If there is none, a framework image route can render one from the page's own title and colors. Ask the user if they have a share image before you make one.
|
|
69
|
+
|
|
70
|
+
## seo/twitter-card (warn)
|
|
71
|
+
|
|
72
|
+
Measures: `<meta name="twitter:card">` exists.
|
|
73
|
+
|
|
74
|
+
Fix: `summary_large_image` when there is an og:image, else `summary`. Add `twitter:title`, `twitter:description` and `twitter:image` with the same values as Open Graph.
|
|
75
|
+
|
|
76
|
+
## seo/json-ld (warn)
|
|
77
|
+
|
|
78
|
+
Measures: the page has at least one `<script type="application/ld+json">` and every block parses as JSON.
|
|
79
|
+
|
|
80
|
+
Fix: render one JSON-LD block on the server. Build it with `JSON.stringify` from an object, not by hand, so it always parses. Escape `<` as `<` when you inject it as HTML.
|
|
81
|
+
|
|
82
|
+
## seo/json-ld-type (warn)
|
|
83
|
+
|
|
84
|
+
Measures: some JSON-LD node has `@type` `Organization`, `WebSite`, `SoftwareApplication`, `MobileApplication` or `Product`. Passes as not applicable (info) when the page has no valid JSON-LD; seo/json-ld reports that.
|
|
85
|
+
|
|
86
|
+
Fix:
|
|
87
|
+
- Pick the type that is true: `SoftwareApplication` for a web or desktop app, `MobileApplication` for a phone app, `Product` for a physical or sold product, `Organization` and `WebSite` for a company or content site.
|
|
88
|
+
- Use `@graph` to hold several nodes.
|
|
89
|
+
- Fill only fields the page supports: `name`, `description`, `url`, `applicationCategory`, `operatingSystem`, `logo`. Add `offers` only with the real price on the page. Never add `aggregateRating` or `review` unless the page shows real ratings.
|
|
90
|
+
- Organization name and logo: take them from the page. Ask the user if the page does not say them.
|
|
91
|
+
|
|
92
|
+
## seo/h1 (error)
|
|
93
|
+
|
|
94
|
+
Measures: exactly one `<h1>` on the page.
|
|
95
|
+
|
|
96
|
+
Fix: keep the hero headline as the `<h1>`. Change other `<h1>` tags to `<h2>` and keep their look with the same classes. If there is no `<h1>`, make the hero headline element an `<h1>` with its current styles. If the logo is wrapped in an `<h1>`, change it to a `<div>` or `<a>`.
|
|
97
|
+
|
|
98
|
+
## seo/heading-order (warn)
|
|
99
|
+
|
|
100
|
+
Measures: heading levels do not skip (no `h2` followed by `h4`). `evidence` lists the skips.
|
|
101
|
+
|
|
102
|
+
Fix: change the tag to the right level and keep its classes, so the look does not change. Style comes from CSS, not from the heading level. Card titles under an `h2` section are `h3`.
|
|
103
|
+
|
|
104
|
+
## seo/img-alt (warn)
|
|
105
|
+
|
|
106
|
+
Measures: every `<img>` has an `alt` attribute (an empty `alt=""` passes).
|
|
107
|
+
|
|
108
|
+
Fix: describe what the image shows when it carries meaning (a product screenshot: "Dashboard showing ..."). Use `alt=""` for decorative images and icons next to text. Describe only what is in the image.
|
|
109
|
+
|
|
110
|
+
## seo/favicon (warn)
|
|
111
|
+
|
|
112
|
+
Measures: a `<link rel="icon">` (or `rel="shortcut icon"`) exists.
|
|
113
|
+
|
|
114
|
+
Fix: use the existing logo mark from the project. Do not design a new icon. If the project has no icon file, ask the user.
|
|
115
|
+
|
|
116
|
+
## seo/noindex (error)
|
|
117
|
+
|
|
118
|
+
Measures: no `noindex` or `none` in `<meta name="robots">`, `<meta name="googlebot">` or the `X-Robots-Tag` header.
|
|
119
|
+
|
|
120
|
+
Fix: remove the noindex on the production page. A preview or staging setup may set it on purpose. If it looks deliberate (tied to an env var), ask the user before you remove it, and keep it for non-production environments.
|
|
121
|
+
|
|
122
|
+
## seo/robots-txt (error)
|
|
123
|
+
|
|
124
|
+
Measures: `/robots.txt` returns 200 with a plain text body. An HTML fallback page (a framework 404 or SPA shell served with 200) fails.
|
|
125
|
+
|
|
126
|
+
Fix: serve a robots.txt that allows crawling (`User-agent: *` and `Allow: /`) and lists the sitemap. Use the framework route or a static file in `public/`.
|
|
127
|
+
|
|
128
|
+
## seo/robots-sitemap (warn)
|
|
129
|
+
|
|
130
|
+
Measures: robots.txt has a `Sitemap:` line. Passes as not applicable (info) when there is no robots.txt; seo/robots-txt reports that.
|
|
131
|
+
|
|
132
|
+
Fix: add `Sitemap: https://<production-domain>/sitemap.xml`. The URL must be absolute, so it needs the production domain.
|
|
133
|
+
|
|
134
|
+
## seo/sitemap (error)
|
|
135
|
+
|
|
136
|
+
Measures: the sitemap (from robots.txt, else `/sitemap.xml`) returns 200 and is a `<urlset>` or `<sitemapindex>`. An HTML fallback page fails. On a local run, when robots.txt lists the sitemap on another host, the same path on the tested origin is checked instead (see `seo/sitemap-host`). A public page must list a reachable production URL: a listed sitemap that does not answer fails, and a listed local host (localhost, 127.0.0.1, `*.localhost`, `[::1]`, 0.0.0.0) fails without a fetch.
|
|
137
|
+
|
|
138
|
+
Fix: serve `/sitemap.xml` with one `<url>` per public page, absolute `<loc>` URLs and `Content-Type: application/xml`. Use the framework sitemap route. If robots.txt lists a local host, build the `Sitemap:` line from the production domain (Next.js: `metadataBase` and app/robots.ts; TanStack Start: the robots.txt server route).
|
|
139
|
+
|
|
140
|
+
## seo/sitemap-lastmod (warn)
|
|
141
|
+
|
|
142
|
+
Measures: every sitemap entry has a `<lastmod>`. Passes as not applicable (info) when there is no valid sitemap; seo/sitemap reports that.
|
|
143
|
+
|
|
144
|
+
Fix: add a W3C date (`2026-01-31` or full ISO time) per entry. Use a real date: the build time or the content's last change. Do not set every page to "now" on each request.
|
|
145
|
+
|
|
146
|
+
## seo/sitemap-host (info)
|
|
147
|
+
|
|
148
|
+
Measures: on a local run (localhost, 127.0.0.1, `*.localhost`, `[::1]` or 0.0.0.0), robots.txt lists the sitemap on another host, so the same path on the tested origin was checked instead. Never reported for a public page.
|
|
149
|
+
|
|
150
|
+
Fix: optional. Nothing to change on a preview or dev server. On the live site, make the robots.txt `Sitemap:` line use the same host as the site (Next.js: build it in app/robots.ts from the same base URL as `metadataBase`; TanStack Start: the robots.txt server route).
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# TanStack Start (1.169) recipes
|
|
2
|
+
|
|
3
|
+
TanStack Start renders on the server by default. Head tags come from the route `head()` option and render through `<HeadContent />` in the root shell. Server routes (files with a `server` property in `createFileRoute`) serve plain files like `sitemap.xml`.
|
|
4
|
+
|
|
5
|
+
Check `package.json` for the version and `vite.config.ts` for the `tanstackStart()` options. Confirm syntax in the docs when unsure: `https://tanstack.com/start/latest/docs/framework/react/guide/seo` and `.../guide/server-routes`.
|
|
6
|
+
|
|
7
|
+
Replace `https://example.com` with the real production domain. If you do not know it, ask the user. Keep it in one constant:
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
// src/lib/site.ts
|
|
11
|
+
export const SITE_URL = import.meta.env.VITE_SITE_URL ?? 'https://example.com'
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Root route: lang, viewport, defaults
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
// src/routes/__root.tsx
|
|
18
|
+
import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router'
|
|
19
|
+
import appCss from '../styles.css?url'
|
|
20
|
+
|
|
21
|
+
export const Route = createRootRoute({
|
|
22
|
+
head: () => ({
|
|
23
|
+
meta: [
|
|
24
|
+
{ charSet: 'utf-8' },
|
|
25
|
+
{ name: 'viewport', content: 'width=device-width, initial-scale=1' },
|
|
26
|
+
{ name: 'twitter:card', content: 'summary_large_image' },
|
|
27
|
+
],
|
|
28
|
+
links: [
|
|
29
|
+
{ rel: 'stylesheet', href: appCss },
|
|
30
|
+
{ rel: 'icon', href: '/favicon.ico' },
|
|
31
|
+
],
|
|
32
|
+
}),
|
|
33
|
+
shellComponent: RootDocument,
|
|
34
|
+
})
|
|
35
|
+
|
|
36
|
+
function RootDocument({ children }: { children: React.ReactNode }) {
|
|
37
|
+
return (
|
|
38
|
+
<html lang="en">
|
|
39
|
+
<head>
|
|
40
|
+
<HeadContent />
|
|
41
|
+
</head>
|
|
42
|
+
<body>
|
|
43
|
+
{children}
|
|
44
|
+
<Scripts />
|
|
45
|
+
</body>
|
|
46
|
+
</html>
|
|
47
|
+
)
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Child route `head()` values merge with the root. A child `title` or `description` replaces the root one, so set page values on the page route.
|
|
52
|
+
|
|
53
|
+
## Index route: title, description, canonical, Open Graph, JSON-LD
|
|
54
|
+
|
|
55
|
+
```tsx
|
|
56
|
+
// src/routes/index.tsx
|
|
57
|
+
import { createFileRoute } from '@tanstack/react-router'
|
|
58
|
+
import { SITE_URL } from '../lib/site'
|
|
59
|
+
|
|
60
|
+
const title = 'Product: what it does'
|
|
61
|
+
const description = 'One or two sentences from the hero that say what the product does.'
|
|
62
|
+
|
|
63
|
+
const jsonLd = {
|
|
64
|
+
'@context': 'https://schema.org',
|
|
65
|
+
'@type': 'SoftwareApplication',
|
|
66
|
+
name: 'Product',
|
|
67
|
+
description,
|
|
68
|
+
url: `${SITE_URL}/`,
|
|
69
|
+
applicationCategory: 'BusinessApplication',
|
|
70
|
+
operatingSystem: 'Web',
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export const Route = createFileRoute('/')({
|
|
74
|
+
head: () => ({
|
|
75
|
+
meta: [
|
|
76
|
+
{ title },
|
|
77
|
+
{ name: 'description', content: description },
|
|
78
|
+
{ property: 'og:title', content: title },
|
|
79
|
+
{ property: 'og:description', content: description },
|
|
80
|
+
{ property: 'og:url', content: `${SITE_URL}/` },
|
|
81
|
+
{ property: 'og:image', content: `${SITE_URL}/og.png` },
|
|
82
|
+
{ property: 'og:type', content: 'website' },
|
|
83
|
+
{ name: 'twitter:title', content: title },
|
|
84
|
+
{ name: 'twitter:description', content: description },
|
|
85
|
+
{ name: 'twitter:image', content: `${SITE_URL}/og.png` },
|
|
86
|
+
],
|
|
87
|
+
links: [{ rel: 'canonical', href: `${SITE_URL}/` }],
|
|
88
|
+
scripts: [{ type: 'application/ld+json', children: JSON.stringify(jsonLd) }],
|
|
89
|
+
}),
|
|
90
|
+
component: Home,
|
|
91
|
+
})
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- All URLs in `head()` must be absolute; there is no `metadataBase`.
|
|
95
|
+
- For FAQ schema, add a second script entry with the `FAQPage` object, built from the same array the FAQ section renders. Only when the page shows a real FAQ.
|
|
96
|
+
- Do not add `{ name: 'robots', content: 'noindex' }` on production pages.
|
|
97
|
+
|
|
98
|
+
## Server routes for text files
|
|
99
|
+
|
|
100
|
+
The `[.]` in the file name escapes the dot. Each file serves one path.
|
|
101
|
+
|
|
102
|
+
```ts
|
|
103
|
+
// src/routes/robots[.]txt.ts
|
|
104
|
+
import { createFileRoute } from '@tanstack/react-router'
|
|
105
|
+
import { SITE_URL } from '../lib/site'
|
|
106
|
+
|
|
107
|
+
export const Route = createFileRoute('/robots.txt')({
|
|
108
|
+
server: {
|
|
109
|
+
handlers: {
|
|
110
|
+
GET: () =>
|
|
111
|
+
new Response(`User-agent: *\nAllow: /\n\nSitemap: ${SITE_URL}/sitemap.xml\n`, {
|
|
112
|
+
headers: { 'Content-Type': 'text/plain' },
|
|
113
|
+
}),
|
|
114
|
+
},
|
|
115
|
+
},
|
|
116
|
+
})
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
// src/routes/sitemap[.]xml.ts
|
|
121
|
+
import { createFileRoute } from '@tanstack/react-router'
|
|
122
|
+
import { SITE_URL } from '../lib/site'
|
|
123
|
+
|
|
124
|
+
const pages = ['/', '/pricing']
|
|
125
|
+
const lastmod = new Date().toISOString() // module load time; use real content dates when you have them
|
|
126
|
+
|
|
127
|
+
export const Route = createFileRoute('/sitemap.xml')({
|
|
128
|
+
server: {
|
|
129
|
+
handlers: {
|
|
130
|
+
GET: () => {
|
|
131
|
+
const urls = pages
|
|
132
|
+
.map((p) => ` <url>\n <loc>${SITE_URL}${p}</loc>\n <lastmod>${lastmod}</lastmod>\n </url>`)
|
|
133
|
+
.join('\n')
|
|
134
|
+
const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`
|
|
135
|
+
return new Response(xml, { headers: { 'Content-Type': 'application/xml' } })
|
|
136
|
+
},
|
|
137
|
+
},
|
|
138
|
+
},
|
|
139
|
+
})
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
// src/routes/llms[.]txt.ts
|
|
144
|
+
import { createFileRoute } from '@tanstack/react-router'
|
|
145
|
+
import { hero } from '../content'
|
|
146
|
+
import { SITE_URL } from '../lib/site'
|
|
147
|
+
|
|
148
|
+
export const Route = createFileRoute('/llms.txt')({
|
|
149
|
+
server: {
|
|
150
|
+
handlers: {
|
|
151
|
+
GET: () => {
|
|
152
|
+
const body = [
|
|
153
|
+
`# ${hero.title}`,
|
|
154
|
+
'',
|
|
155
|
+
`> ${hero.summary}`,
|
|
156
|
+
'',
|
|
157
|
+
'## Pages',
|
|
158
|
+
'',
|
|
159
|
+
`- [Home](${SITE_URL}/): what the landing page covers`,
|
|
160
|
+
'',
|
|
161
|
+
'## Optional',
|
|
162
|
+
'',
|
|
163
|
+
`- [Full text](${SITE_URL}/llms-full.txt): the full page content as markdown`,
|
|
164
|
+
'',
|
|
165
|
+
].join('\n')
|
|
166
|
+
return new Response(body, { headers: { 'Content-Type': 'text/plain; charset=utf-8' } })
|
|
167
|
+
},
|
|
168
|
+
},
|
|
169
|
+
},
|
|
170
|
+
})
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
`src/routes/llms-full[.]txt.ts` uses `createFileRoute('/llms-full.txt')` the same way and writes every section and FAQ item as markdown (H1, `>` summary, `##` per section, `###` per question).
|
|
174
|
+
|
|
175
|
+
Keep the copy in one module (`src/content.ts`) that the index route and the text routes both import, so the text files are built from the same content as the page. If the copy is inline JSX, move only the strings the text files need into it. Keep the JSX and its classes as they are.
|
|
176
|
+
|
|
177
|
+
Static files in `public/` (`public/robots.txt`, `public/sitemap.xml`, `public/llms.txt`) also work. Use them when the content never changes. Do not have both a public file and a server route for the same path.
|
|
178
|
+
|
|
179
|
+
## Built-in sitemap and prerendering
|
|
180
|
+
|
|
181
|
+
`tanstackStart()` can prerender pages to static HTML and write a sitemap at build:
|
|
182
|
+
|
|
183
|
+
```ts
|
|
184
|
+
// vite.config.ts
|
|
185
|
+
tanstackStart({
|
|
186
|
+
prerender: { enabled: true, crawlLinks: true },
|
|
187
|
+
sitemap: { enabled: true, host: 'https://example.com' },
|
|
188
|
+
})
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
- Prerendering makes the HTML static, which is good for a landing page.
|
|
192
|
+
- Server routes have no component, so automatic discovery skips them. To write them as static files, list them in `pages`: `pages: [{ path: '/llms.txt' }, { path: '/llms-full.txt' }, { path: '/robots.txt' }]`. Otherwise they run on the server at request time, which is fine too.
|
|
193
|
+
- Use either the built-in sitemap or a sitemap server route, not both. Check that the built-in one writes `<lastmod>`; if it does not, use the server route.
|
|
194
|
+
|
|
195
|
+
## Server-rendered content
|
|
196
|
+
|
|
197
|
+
- Do not set `ssr: false` on the index route and do not enable SPA mode for the landing page.
|
|
198
|
+
- Load data in the route `loader`, not in `useEffect`.
|
|
199
|
+
- Client-only widgets can render a server fallback with the real text.
|
|
200
|
+
|
|
201
|
+
## Images
|
|
202
|
+
|
|
203
|
+
```tsx
|
|
204
|
+
<img
|
|
205
|
+
src="/hero-1200.webp"
|
|
206
|
+
srcSet="/hero-600.webp 600w, /hero-1200.webp 1200w, /hero-2400.webp 2400w"
|
|
207
|
+
sizes="(max-width: 768px) 100vw, 1200px"
|
|
208
|
+
width={1200}
|
|
209
|
+
height={800}
|
|
210
|
+
alt="Dashboard showing ..."
|
|
211
|
+
fetchPriority="high"
|
|
212
|
+
/>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- Every `<img>` gets `width` and `height` (the file's pixel size) so space is reserved. CSS `width: 100%; height: auto` keeps it responsive.
|
|
216
|
+
- Make resized files for `srcSet` (for example with `sharp` in a small script, or `vite-imagetools`). Ask before you add a dependency.
|
|
217
|
+
- The hero image gets `fetchPriority="high"`. Images below the fold get `loading="lazy"`.
|
|
218
|
+
|
|
219
|
+
## Fonts
|
|
220
|
+
|
|
221
|
+
- Self-hosted fonts: preload the one or two files the hero uses in the root `head().links`:
|
|
222
|
+
`{ rel: 'preload', href: '/fonts/Inter-var.woff2', as: 'font', type: 'font/woff2', crossOrigin: 'anonymous' }`
|
|
223
|
+
- `@font-face` uses `font-display: swap`.
|
|
224
|
+
- Google Fonts links: keep `preconnect` to `fonts.googleapis.com` and `fonts.gstatic.com` (with `crossOrigin: 'anonymous'`), and `&display=swap` in the URL. Keep the same families; drop only weights that are not used.
|
|
225
|
+
|
|
226
|
+
## Dark mode and reduced motion
|
|
227
|
+
|
|
228
|
+
Same CSS as any site, in `src/styles.css`:
|
|
229
|
+
|
|
230
|
+
```css
|
|
231
|
+
:root { color-scheme: light dark; --bg: #fff; --fg: #111; }
|
|
232
|
+
@media (prefers-color-scheme: dark) { :root { --bg: #0b0b0c; --fg: #ededed; } }
|
|
233
|
+
@media (prefers-reduced-motion: reduce) { .marquee { animation: none; } }
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
Tailwind: `dark:` and `motion-safe:` variants. Keep any existing class-based theme toggle.
|
|
237
|
+
|
|
238
|
+
## Production check
|
|
239
|
+
|
|
240
|
+
```sh
|
|
241
|
+
npm run build
|
|
242
|
+
npm run start # if the project has a start script, often: node .output/server/index.mjs
|
|
243
|
+
npm run preview # else: vite preview
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Use the project's package manager and the URL the command prints. Stop the server when done.
|