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,127 @@
|
|
|
1
|
+
# Convert rules
|
|
2
|
+
|
|
3
|
+
Convert checks look at what makes a visitor trust the page and act: working links, a way to reach a human, a short sign-up form, a visible price. Each finding carries `engine` (what measured it), `confidence` (`high`, `medium`, `low`), `source` (the study or guide behind the rule) and, when only the site owner can fix it, `needsOwner: true`.
|
|
4
|
+
|
|
5
|
+
The `convert` score weights checks by confidence: high 3, medium 2, low 1. `info` findings weigh 0.
|
|
6
|
+
|
|
7
|
+
The report also has `pageType`: `product` (a homepage with a nav of 4 or more links), `launch` (an ad or launch page with few links) or `waitlist` (the only form is a single email field). Some checks depend on it. If the detection is wrong, run `sugikit check` with `--page-type product|launch|waitlist`.
|
|
8
|
+
|
|
9
|
+
Hard rules for every convert fix (see SKILL.md, Conversion policy):
|
|
10
|
+
|
|
11
|
+
- Never invent proof, testimonials, user counts, logos, ratings, prices, guarantees, deadlines, urgency or contact details. Read the repo first (README, pricing config, checkout setup, llms.txt). If the fact is not there, ask the owner.
|
|
12
|
+
- A finding with `needsOwner: true` goes to the "your turn" list. Do not retry it.
|
|
13
|
+
- Keep the site's style. Copy edits are suggestions unless the owner allowed copy changes.
|
|
14
|
+
|
|
15
|
+
## convert/link-text (warn, high)
|
|
16
|
+
|
|
17
|
+
Measures: links whose whole text is "click here", "learn more", "read more" or "here" (case and spaces ignored) and that have no `aria-label` or `aria-labelledby`.
|
|
18
|
+
|
|
19
|
+
Fix: rewrite the link text to say where it goes: "See pricing", "Read the setup guide", "Compare plans". Use the target page's own title. If the design needs the short text, keep it and add an `aria-label` that names the target. This is a small copy change: when the owner did not allow copy changes, suggest the new text instead of applying it.
|
|
20
|
+
|
|
21
|
+
## convert/placeholder-text (error, high)
|
|
22
|
+
|
|
23
|
+
Measures: leftovers in the visible text and links:
|
|
24
|
+
|
|
25
|
+
- placeholder text: "Lorem ipsum", "TODO", "Your Name", "Company Inc" (form labels and scripts are ignored),
|
|
26
|
+
- links to example.com, example.org or example.net,
|
|
27
|
+
- visible `href="#"` links (anchors with `role="button"` or an `onclick` handler count as buttons and pass),
|
|
28
|
+
- same-origin links that return 4xx. Sugikit checks up to 20 links from the page (HEAD, then GET when the server answers 405), 4 at a time, 5 seconds each.
|
|
29
|
+
|
|
30
|
+
Fix: remove the leftover or replace it with the real thing. Point `#` and broken links at the real page or route; if the page does not exist, remove the link. When the fix needs real values (a name, a company, a real URL), the finding has `needsOwner: true`: ask the owner and leave it open. Never fill in made-up names, companies or addresses.
|
|
31
|
+
|
|
32
|
+
## convert/contact-visible (warn, high)
|
|
33
|
+
|
|
34
|
+
Measures: the header, footer or nav has a `mailto:` link, or a link whose href or text mentions contact, support or help. A page with no header, footer or nav is searched whole.
|
|
35
|
+
|
|
36
|
+
Fix: add a contact link to the footer (or header): a `mailto:` link, a contact page or a support link. The owner gives the address. If the repo already has one (README, package.json `author` or `bugs`, an existing contact page), use it; else ask the owner. `needsOwner: true` when missing.
|
|
37
|
+
|
|
38
|
+
## convert/form-fields (warn or error, high)
|
|
39
|
+
|
|
40
|
+
Measures: the visible fields (inputs other than hidden and buttons, selects, textareas) of sign-up and lead forms: forms with an email field or a submit label like sign up, join, waitlist, subscribe, get started or request. Warn above 3 fields or when the form asks for a phone number. Error above 6 fields.
|
|
41
|
+
|
|
42
|
+
Fix: cut the form to the email field, plus a name only when the product needs it. Remove the phone field. Move every other question to onboarding, after sign-up. Change the server code that reads the form in the same step, so removed fields are not required there. Ask the owner before you remove a field that a CRM or sales process may depend on.
|
|
43
|
+
|
|
44
|
+
## convert/price-visible (warn, medium)
|
|
45
|
+
|
|
46
|
+
Measures: a currency amount on the page ($, € or £ before a number, or a number with USD, EUR or GBP), or a same-origin link whose text or href says pricing, plans or price. Waitlist pages are skipped (info). A later browser check verifies that the pricing link shows a price in one click.
|
|
47
|
+
|
|
48
|
+
Fix: show the price on the page (a pricing section) or link the pricing page from the nav or the hero. Take the numbers only from the repo (pricing config, checkout or payment provider setup) or from the owner. Never invent a price, a plan or a discount. `needsOwner: true` when no price is known: ask the owner for the price, or whether the product is free.
|
|
49
|
+
|
|
50
|
+
The render part: when the static check passed only through a pricing link, the full check loads that page once and looks for a currency amount in its HTML (a link to a section of this page uses the rendered page). It passes with `engine: "render"` and the price as evidence, or fails when the pricing page answers non-2xx or shows no price (`needsOwner: true`).
|
|
51
|
+
|
|
52
|
+
## Render checks
|
|
53
|
+
|
|
54
|
+
These run in the same headless browser pass as the polish checks (`engine: "render"`), at 1440x900 (desktop-light) and 390x844 (phone-light), measured at the top of the page. They do not run with `--no-browser`.
|
|
55
|
+
|
|
56
|
+
**Primary CTA.** Every render check uses the same primary CTA. Clickables are `a[href]`, `button`, `[role="button"]` and submit or button inputs that are visible and have their center in the first screen; boxes over 40% of the screen (card links) do not count. A clickable is **filled** when it paints its own background (alpha 0.5 or more, or a gradient) that differs from the background behind it (1.2:1 or more); outline and text buttons are not filled. The primary CTA is the largest filled clickable whose label has an action word (get, start, try, buy, sign up, join, download, install, book, request, subscribe, create), else the most salient filled clickable. Salience is box area x contrast: fill contrast for filled elements, a fifth of the text contrast for text links.
|
|
57
|
+
|
|
58
|
+
Policy for every render fix: keep the site's palette, type and layout style. Change spacing, order, size and which existing color a button uses; never add a new hue, a fake popup replacement, or urgency.
|
|
59
|
+
|
|
60
|
+
## convert/hero-in-first-screen (error, high)
|
|
61
|
+
|
|
62
|
+
Source: NN/g scrolling and attention.
|
|
63
|
+
|
|
64
|
+
Measures: the first visible h1 and the primary CTA boxes are fully inside the first screen at 1440x900 and at 390x844. Evidence names each state and the box edges in px.
|
|
65
|
+
|
|
66
|
+
Fix: cut the hero's top padding and decorative space, shrink an oversized visual above the h1, and on phones put the CTA above the hero visual. Keep the fonts and colors.
|
|
67
|
+
|
|
68
|
+
## convert/mobile-fold (error or warn, high)
|
|
69
|
+
|
|
70
|
+
Source: NN/g Fold Manifesto; NN/g scrolling and attention.
|
|
71
|
+
|
|
72
|
+
Measures at 390x844: the h1 and the primary CTA are at least partly visible (error when not). Then the "false floor": when the page is taller than one screen, something must show in the bottom 15% of the first screen: text, an image or control, or the top edge of a section with its own background (fixed and sticky layers do not count). Nothing there is a warn: the page looks finished.
|
|
73
|
+
|
|
74
|
+
Fix: lower the hero's height on phones (no `min-height: 100vh` hero with an empty bottom), so the next section or more content peeks in. Do not add a decorative arrow that does nothing.
|
|
75
|
+
|
|
76
|
+
## convert/primary-cta-one (error or warn)
|
|
77
|
+
|
|
78
|
+
Source: NN/g: keep major CTAs above the fold; Wiebe: remove other calls to action.
|
|
79
|
+
|
|
80
|
+
Measures at 1440x900: no primary CTA (no filled button or link in the first screen) is an error with high confidence. Two or more filled buttons that compete (box at least 60% of the primary's area, similar fill contrast) is a warn with medium confidence; evidence lists them with their sizes.
|
|
81
|
+
|
|
82
|
+
Fix: keep one filled button for the main action. Turn the other ones into outline buttons or text links. With none, fill the main CTA with the darkest or accent color the site already uses.
|
|
83
|
+
|
|
84
|
+
## convert/cta-salient (error or warn)
|
|
85
|
+
|
|
86
|
+
Source: WCAG 1.4.3 and 1.4.11; Kadavy via CXL (secondary): contrast matters, not hue.
|
|
87
|
+
|
|
88
|
+
Measures the primary CTA at 1440x900: label contrast at least 4.5:1 against its fill (error, high), fill contrast at least 3:1 against the background around it (warn, high), and it ranks first by salience among the labeled interactive elements in the first screen (warn, medium). Colors are read through a canvas, so oklch and other color spaces work; a background image behind the button makes the fill contrast unknown, and that part is skipped.
|
|
89
|
+
|
|
90
|
+
Fix: raise contrast inside the existing palette: the darkest or strongest color the site already has for the fill, a light or dark label, more space around the button, or a quieter style for the element that outranks it. Never add a new hue (policy P2).
|
|
91
|
+
|
|
92
|
+
## convert/cta-tap-size (warn, high)
|
|
93
|
+
|
|
94
|
+
Source: WCAG 2.5.5 and 2.5.8 target size.
|
|
95
|
+
|
|
96
|
+
Measures: the primary CTA box at 390x844 is at least 44x44 CSS px. `polish/tap-targets` checks every target at 24x24.
|
|
97
|
+
|
|
98
|
+
Fix: more padding or `min-height: 44px` on the button at phone width. Keep its look.
|
|
99
|
+
|
|
100
|
+
## convert/arrival-popup (error, high)
|
|
101
|
+
|
|
102
|
+
Source: Google Search Central intrusive interstitials; NN/g popups.
|
|
103
|
+
|
|
104
|
+
Measures: about 1 second after the load event on desktop-light and phone-light, and about 4 seconds after it on phone-light (before any scrolling), any overlay that covers more than 30% of the viewport: fixed elements, `dialog[open]`, `[role="dialog"]`, `[aria-modal="true"]`, and absolute elements named like a modal, popup, cookie, consent or newsletter. Decorative layers (`pointer-events: none`, negative z-index) and a fixed layer that holds the h1 (a page that scrolls inside a fixed container) do not count.
|
|
105
|
+
|
|
106
|
+
Fix: remove the popup on arrival. Show a newsletter ask inline after the value, and a cookie notice as a small bar that leaves the page usable. Never trigger it on a timer in the first seconds.
|
|
107
|
+
|
|
108
|
+
## convert/cta-works (error, high)
|
|
109
|
+
|
|
110
|
+
Source: Stanford credibility: "Avoid errors of all types".
|
|
111
|
+
|
|
112
|
+
Measures: the primary CTA plus CTAs inside a pricing section (filled or with an action word), at most 4:
|
|
113
|
+
|
|
114
|
+
- `mailto:`, `tel:` and `sms:` links pass.
|
|
115
|
+
- `#section` links pass when the element exists on the page.
|
|
116
|
+
- http(s) links get a HEAD request (GET when the server answers 405); 2xx and 3xx pass. Same-origin links follow redirects; off-site links (checkout, app stores) get only the first response. 401, 403, 429 and 503 are inconclusive (bot protection or a login), not a failure.
|
|
117
|
+
- Buttons, and links to `#`, empty or `javascript:`, are clicked in a fresh page: they pass when a navigation, a new page, a dialog, a clipboard write, a form submit or a visible DOM change outside the button happens within 2 seconds, with no uncaught error. Submit buttons of a form are never clicked (no form is ever sent); a real popup window is never opened.
|
|
118
|
+
|
|
119
|
+
Evidence lists every target with what happened. Fix: point the link at a real page, give the button a working handler, or fix the error it throws. If the right target (checkout URL, download link) is not in the repo, ask the owner.
|
|
120
|
+
|
|
121
|
+
## convert/hero-lcp (warn or info, high)
|
|
122
|
+
|
|
123
|
+
Source: web.dev Core Web Vitals: LCP within 2.5 s.
|
|
124
|
+
|
|
125
|
+
Measures on phone-light: the largest-contentful-paint element (PerformanceObserver, buffered, read before scrolling) and its time. Fails (warn) when the LCP element is below the first screen. With `--psi`, PageSpeed's mobile LCP (field data at the 75th percentile when the page has it, else lab) is used and must be 2.5 s or less (warn). Without PageSpeed, the local lab time is only a hint: on a local dev or preview server it is `info` and the message says local timing is not representative.
|
|
126
|
+
|
|
127
|
+
Fix: preload the hero image and give it `fetchpriority="high"` (never `loading="lazy"`), serve it at the right size, and render the hero on the server, not only on the client.
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# GEO rules
|
|
2
|
+
|
|
3
|
+
GEO (generative engine optimization) is about AI assistants and AI search: ChatGPT, Claude, Perplexity, Google AI Overviews. They read the raw HTML, `/robots.txt` and `/llms.txt`. Most of their crawlers do not run JavaScript.
|
|
4
|
+
|
|
5
|
+
Everything you add here must be true to the page. Never invent features, prices, integrations, customers or claims. If the page does not say it, it does not go in.
|
|
6
|
+
|
|
7
|
+
## geo/llms-txt (error)
|
|
8
|
+
|
|
9
|
+
Measures: `/llms.txt` returns 200 with a plain text body. An HTML fallback page fails.
|
|
10
|
+
|
|
11
|
+
Fix: serve a markdown file at `/llms.txt`. Generate it at build time from the same content the page uses, so it stays in sync. Use `Content-Type: text/plain; charset=utf-8`. Format:
|
|
12
|
+
|
|
13
|
+
```md
|
|
14
|
+
# Product name
|
|
15
|
+
|
|
16
|
+
> One or two sentences: what the product is and who it is for. Take it from the hero.
|
|
17
|
+
|
|
18
|
+
Short paragraph with key facts from the page: what it does, platforms, pricing model if the page states it.
|
|
19
|
+
|
|
20
|
+
## Pages
|
|
21
|
+
|
|
22
|
+
- [Home](https://example.com/): what the landing page covers
|
|
23
|
+
- [Pricing](https://example.com/pricing): plans and prices
|
|
24
|
+
- [Docs](https://example.com/docs): how to set it up
|
|
25
|
+
|
|
26
|
+
## Optional
|
|
27
|
+
|
|
28
|
+
- [Full text](https://example.com/llms-full.txt): the full page content as markdown
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
Rules for the file:
|
|
32
|
+
- Starts with one `# ` H1: the product or site name.
|
|
33
|
+
- Then a `> ` blockquote summary.
|
|
34
|
+
- Then `## ` sections with markdown link lists: `- [Title](absolute-url): note`.
|
|
35
|
+
- Links use absolute production URLs. This needs the production domain; ask the user if it is unknown.
|
|
36
|
+
- Link only pages that exist.
|
|
37
|
+
|
|
38
|
+
## geo/llms-txt-format (warn)
|
|
39
|
+
|
|
40
|
+
Measures: `/llms.txt` starts with a `# ` heading and contains at least one markdown link `[text](url)`. Passes as not applicable (info) when there is no /llms.txt; geo/llms-txt reports that.
|
|
41
|
+
|
|
42
|
+
Fix: follow the format above. A plain text file or a file that starts with a blank `##` section fails.
|
|
43
|
+
|
|
44
|
+
## geo/llms-full-txt (warn)
|
|
45
|
+
|
|
46
|
+
Measures: `/llms-full.txt` returns 200 with a plain text body. An HTML fallback page fails.
|
|
47
|
+
|
|
48
|
+
Fix: serve the full text of the page (and other key pages) as markdown: the same H1 and summary as `/llms.txt`, then every section of the page with its heading and text, lists as lists, FAQ as question headings with answers. Build it from the same content source the page renders, at build time, so it never drifts from the page. Do not paste a hand-written summary that can go stale.
|
|
49
|
+
|
|
50
|
+
## geo/ai-crawlers (warn)
|
|
51
|
+
|
|
52
|
+
Measures: robots.txt does not block `/` for GPTBot, OAI-SearchBot, ChatGPT-User, ClaudeBot, Claude-SearchBot, Claude-User, PerplexityBot, Google-Extended or Applebot-Extended. A `Disallow: /` under `User-agent: *` blocks them too, unless they have their own group. Only a 4xx robots.txt means no rules and passes. A 5xx or no response counts as blocked.
|
|
53
|
+
|
|
54
|
+
Fix:
|
|
55
|
+
- Remove the `Disallow: /` for these agents, or add an explicit group:
|
|
56
|
+
|
|
57
|
+
```txt
|
|
58
|
+
User-agent: GPTBot
|
|
59
|
+
User-agent: ClaudeBot
|
|
60
|
+
User-agent: PerplexityBot
|
|
61
|
+
Allow: /
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
- A block can be a deliberate choice (some owners do not want AI training). If the block looks deliberate, ask the user before you change it. Search crawlers (OAI-SearchBot, Claude-SearchBot, PerplexityBot) and training crawlers (GPTBot, ClaudeBot, Google-Extended) are separate, so the user can allow search and still block training.
|
|
65
|
+
|
|
66
|
+
## geo/faq-schema (warn)
|
|
67
|
+
|
|
68
|
+
Measures: some JSON-LD node has `@type` `FAQPage`.
|
|
69
|
+
|
|
70
|
+
Fix only when the page has a real, visible FAQ section:
|
|
71
|
+
- Build `FAQPage` with `mainEntity`: one `Question` per FAQ item, `name` is the question, `acceptedAnswer` is an `Answer` with `text`.
|
|
72
|
+
- Use the exact question and answer text from the page. Generate it from the same data the FAQ section renders.
|
|
73
|
+
|
|
74
|
+
If the page has no FAQ: do not write one to pass this rule. Leave the finding open and tell the user the page has no FAQ. Suggest they add one if they want, with their own questions.
|
|
75
|
+
|
|
76
|
+
## geo/ssr-content (error)
|
|
77
|
+
|
|
78
|
+
Measures: the server HTML (no JavaScript run) has at least 400 characters of visible text in `<body>`.
|
|
79
|
+
|
|
80
|
+
Fix:
|
|
81
|
+
- Render the main content on the server. Most crawlers for AI do not run JavaScript; a client-only page looks empty to them.
|
|
82
|
+
- Next.js: keep the page a Server Component. Move `'use client'` down to small interactive parts. Do not load copy in `useEffect` or with `dynamic(..., { ssr: false })`.
|
|
83
|
+
- TanStack Start: do not set `ssr: false` on the route or use SPA mode. Load data in the route `loader`.
|
|
84
|
+
- Text that only appears after an animation still counts if it is in the HTML. Animate with CSS from the rendered state, do not insert text with JavaScript.
|
|
85
|
+
- Do not add hidden text to reach 400 characters. If the page is short by design, say so in the summary.
|
|
86
|
+
|
|
87
|
+
## geo/hero-statement (warn)
|
|
88
|
+
|
|
89
|
+
Measures: a `<p>` with text follows the `<h1>`.
|
|
90
|
+
|
|
91
|
+
Fix: the hero usually has a subheadline already. If it is a `<div>` or `<span>`, make it a `<p>` with the same classes. If the hero has no subheadline, ask the user for one sentence, or take one from the page's own intro text. Do not invent a tagline.
|
|
92
|
+
|
|
93
|
+
## geo/hero-length (info)
|
|
94
|
+
|
|
95
|
+
Measures: the first sentence of the paragraph after the `<h1>` is 30 words or fewer, so AI answers can quote it.
|
|
96
|
+
|
|
97
|
+
Fix: optional. If it is longer, suggest a shorter split of the same sentence to the user. This is a copy change, so keep the words and meaning, and list it as a visible change.
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
# Next.js 16 (App Router) recipes
|
|
2
|
+
|
|
3
|
+
Use the files the project already has. Check `package.json` for the Next.js version and `next.config.ts` for flags like `cacheComponents`. Next.js 16 renamed `middleware.ts` to `proxy.ts`; look in both for headers.
|
|
4
|
+
|
|
5
|
+
Replace `https://example.com` with the real production domain. If you do not know it, ask the user. A common pattern is one constant:
|
|
6
|
+
|
|
7
|
+
```ts
|
|
8
|
+
// lib/site.ts
|
|
9
|
+
export const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://example.com";
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Metadata
|
|
13
|
+
|
|
14
|
+
Root layout sets the base and defaults. Pages set their own values.
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
// app/layout.tsx
|
|
18
|
+
import type { Metadata, Viewport } from "next";
|
|
19
|
+
import { SITE_URL } from "@/lib/site";
|
|
20
|
+
|
|
21
|
+
export const metadata: Metadata = {
|
|
22
|
+
metadataBase: new URL(SITE_URL),
|
|
23
|
+
title: { default: "Product: what it does", template: "%s | Product" },
|
|
24
|
+
description: "One or two sentences from the hero that say what the product does.",
|
|
25
|
+
openGraph: { type: "website", siteName: "Product" },
|
|
26
|
+
twitter: { card: "summary_large_image" },
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
export const viewport: Viewport = {
|
|
30
|
+
width: "device-width",
|
|
31
|
+
initialScale: 1,
|
|
32
|
+
};
|
|
33
|
+
|
|
34
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
35
|
+
return (
|
|
36
|
+
<html lang="en">
|
|
37
|
+
<body>{children}</body>
|
|
38
|
+
</html>
|
|
39
|
+
);
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```tsx
|
|
44
|
+
// app/page.tsx
|
|
45
|
+
import type { Metadata } from "next";
|
|
46
|
+
|
|
47
|
+
export const metadata: Metadata = {
|
|
48
|
+
title: "Product: what it does",
|
|
49
|
+
description: "...",
|
|
50
|
+
alternates: { canonical: "/" },
|
|
51
|
+
openGraph: {
|
|
52
|
+
title: "Product: what it does",
|
|
53
|
+
description: "...",
|
|
54
|
+
url: "/",
|
|
55
|
+
images: [{ url: "/og.png", width: 1200, height: 630, alt: "..." }],
|
|
56
|
+
},
|
|
57
|
+
twitter: {
|
|
58
|
+
card: "summary_large_image",
|
|
59
|
+
title: "Product: what it does",
|
|
60
|
+
description: "...",
|
|
61
|
+
images: ["/og.png"],
|
|
62
|
+
},
|
|
63
|
+
};
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
- `metadataBase` turns relative `canonical`, `og:url` and image paths into absolute URLs.
|
|
67
|
+
- `generateMetadata` works the same way for dynamic routes; it returns the same object.
|
|
68
|
+
- A plain `title` string on the root layout bypasses the template. Pick one style and stay with it.
|
|
69
|
+
- An Open Graph image can also come from `app/opengraph-image.png` (static file) or `app/opengraph-image.tsx` (generated with `ImageResponse`). Use the page's own title, colors and font.
|
|
70
|
+
- Favicon: put `app/icon.png` or `app/icon.svg` (and `app/favicon.ico`). Next.js adds the link tags.
|
|
71
|
+
- Do not set `robots: { index: false }` on production pages.
|
|
72
|
+
|
|
73
|
+
## robots.txt
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
// app/robots.ts
|
|
77
|
+
import type { MetadataRoute } from "next";
|
|
78
|
+
import { SITE_URL } from "@/lib/site";
|
|
79
|
+
|
|
80
|
+
export default function robots(): MetadataRoute.Robots {
|
|
81
|
+
return {
|
|
82
|
+
rules: { userAgent: "*", allow: "/" },
|
|
83
|
+
sitemap: `${SITE_URL}/sitemap.xml`,
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
To treat AI crawlers on their own, `rules` takes an array: `[{ userAgent: "*", allow: "/" }, { userAgent: ["GPTBot", "ClaudeBot"], allow: "/" }]`.
|
|
89
|
+
|
|
90
|
+
## sitemap.xml
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
// app/sitemap.ts
|
|
94
|
+
import type { MetadataRoute } from "next";
|
|
95
|
+
import { SITE_URL } from "@/lib/site";
|
|
96
|
+
|
|
97
|
+
export default function sitemap(): MetadataRoute.Sitemap {
|
|
98
|
+
const lastModified = new Date(); // build time; use real content dates when you have them
|
|
99
|
+
return [
|
|
100
|
+
{ url: `${SITE_URL}/`, lastModified },
|
|
101
|
+
{ url: `${SITE_URL}/pricing`, lastModified },
|
|
102
|
+
];
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
List only pages that exist. Both files are static by default and run at build time.
|
|
107
|
+
|
|
108
|
+
## llms.txt and llms-full.txt
|
|
109
|
+
|
|
110
|
+
Keep the page copy in one module that the page and the text routes both import. Then the text files are built from the same content and cannot drift. If the copy is inline JSX, move only the strings the text files need (hero, sections, FAQ) into that module. Keep the JSX and its classes as they are.
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
// app/content.ts
|
|
114
|
+
export const hero = { title: "Product", summary: "What it is and who it is for." };
|
|
115
|
+
export const sections = [{ heading: "Feature", body: "..." }];
|
|
116
|
+
export const faq = [{ q: "Question from the page?", a: "Answer from the page." }];
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
```ts
|
|
120
|
+
// app/llms.txt/route.ts
|
|
121
|
+
import { hero } from "@/app/content";
|
|
122
|
+
import { SITE_URL } from "@/lib/site";
|
|
123
|
+
|
|
124
|
+
export const dynamic = "force-static";
|
|
125
|
+
|
|
126
|
+
export function GET() {
|
|
127
|
+
const body = [
|
|
128
|
+
`# ${hero.title}`,
|
|
129
|
+
"",
|
|
130
|
+
`> ${hero.summary}`,
|
|
131
|
+
"",
|
|
132
|
+
"## Pages",
|
|
133
|
+
"",
|
|
134
|
+
`- [Home](${SITE_URL}/): what the landing page covers`,
|
|
135
|
+
"",
|
|
136
|
+
"## Optional",
|
|
137
|
+
"",
|
|
138
|
+
`- [Full text](${SITE_URL}/llms-full.txt): the full page content as markdown`,
|
|
139
|
+
"",
|
|
140
|
+
].join("\n");
|
|
141
|
+
return new Response(body, { headers: { "Content-Type": "text/plain; charset=utf-8" } });
|
|
142
|
+
}
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
// app/llms-full.txt/route.ts
|
|
147
|
+
import { faq, hero, sections } from "@/app/content";
|
|
148
|
+
|
|
149
|
+
export const dynamic = "force-static";
|
|
150
|
+
|
|
151
|
+
export function GET() {
|
|
152
|
+
const parts = [`# ${hero.title}`, "", `> ${hero.summary}`, ""];
|
|
153
|
+
for (const s of sections) parts.push(`## ${s.heading}`, "", s.body, "");
|
|
154
|
+
if (faq.length) {
|
|
155
|
+
parts.push("## FAQ", "");
|
|
156
|
+
for (const item of faq) parts.push(`### ${item.q}`, "", item.a, "");
|
|
157
|
+
}
|
|
158
|
+
return new Response(parts.join("\n"), { headers: { "Content-Type": "text/plain; charset=utf-8" } });
|
|
159
|
+
}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The folder name is `llms.txt`, with the dot. If `next.config.ts` sets `cacheComponents: true`, remove the `dynamic` export (it is not allowed there); a GET handler that reads no request data is still prerendered.
|
|
163
|
+
|
|
164
|
+
## JSON-LD
|
|
165
|
+
|
|
166
|
+
Render it in the page (a Server Component), built from an object:
|
|
167
|
+
|
|
168
|
+
```tsx
|
|
169
|
+
// app/page.tsx (inside the component)
|
|
170
|
+
const jsonLd = {
|
|
171
|
+
"@context": "https://schema.org",
|
|
172
|
+
"@graph": [
|
|
173
|
+
{ "@type": "SoftwareApplication", name: "Product", description: "...", url: SITE_URL, applicationCategory: "BusinessApplication", operatingSystem: "Web" },
|
|
174
|
+
{ "@type": "FAQPage", mainEntity: faq.map((f) => ({ "@type": "Question", name: f.q, acceptedAnswer: { "@type": "Answer", text: f.a } })) },
|
|
175
|
+
],
|
|
176
|
+
};
|
|
177
|
+
|
|
178
|
+
<script
|
|
179
|
+
type="application/ld+json"
|
|
180
|
+
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
|
|
181
|
+
/>
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Add the `FAQPage` node only if the page shows that FAQ.
|
|
185
|
+
|
|
186
|
+
## Server-rendered content
|
|
187
|
+
|
|
188
|
+
- `app/page.tsx` stays a Server Component (no `'use client'` at the top).
|
|
189
|
+
- Put `'use client'` in small leaf components (a menu toggle, a carousel), and pass server-rendered text to them as props or children.
|
|
190
|
+
- Do not fetch copy in `useEffect`. Do not use `dynamic(() => import(...), { ssr: false })` for content.
|
|
191
|
+
|
|
192
|
+
## Images
|
|
193
|
+
|
|
194
|
+
```tsx
|
|
195
|
+
import Image from "next/image";
|
|
196
|
+
import hero from "@/public/hero.png"; // static import gives width, height and blur data
|
|
197
|
+
|
|
198
|
+
<Image src={hero} alt="Dashboard showing ..." preload sizes="(max-width: 768px) 100vw, 1200px" />
|
|
199
|
+
<Image src="/shot.png" alt="..." width={1200} height={800} sizes="(max-width: 768px) 100vw, 600px" />
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
- Every `Image` has `width` and `height`, or `fill` inside a sized parent plus `sizes`.
|
|
203
|
+
- The LCP hero image gets `preload` (Next.js 16; `priority` in older versions). Other images lazy load by default.
|
|
204
|
+
- Remote images need `images.remotePatterns` in `next.config.ts`.
|
|
205
|
+
|
|
206
|
+
## Fonts
|
|
207
|
+
|
|
208
|
+
```ts
|
|
209
|
+
// app/fonts.ts
|
|
210
|
+
import { Inter } from "next/font/google"; // or next/font/local for the project's own files
|
|
211
|
+
|
|
212
|
+
export const sans = Inter({ subsets: ["latin"], display: "swap", variable: "--font-sans" });
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Apply `sans.variable` on `<html>` and use `var(--font-sans)` in CSS. Keep the font the project already uses; `next/font` only changes how it loads (self-hosted, preloaded, metric fallback).
|
|
216
|
+
|
|
217
|
+
## Dark mode
|
|
218
|
+
|
|
219
|
+
```css
|
|
220
|
+
/* app/globals.css */
|
|
221
|
+
:root {
|
|
222
|
+
color-scheme: light dark;
|
|
223
|
+
--bg: #ffffff;
|
|
224
|
+
--fg: #111111;
|
|
225
|
+
}
|
|
226
|
+
@media (prefers-color-scheme: dark) {
|
|
227
|
+
:root {
|
|
228
|
+
--bg: #0b0b0c;
|
|
229
|
+
--fg: #ededed;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
body { background: var(--bg); color: var(--fg); }
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Tailwind v4: `dark:` variants follow `prefers-color-scheme` by default. If the project uses a class toggle (`@custom-variant dark (&:where(.dark, .dark *));`), keep it.
|
|
236
|
+
|
|
237
|
+
## Reduced motion
|
|
238
|
+
|
|
239
|
+
```css
|
|
240
|
+
@media (prefers-reduced-motion: reduce) {
|
|
241
|
+
.marquee, .hero-glow { animation: none; }
|
|
242
|
+
* { scroll-behavior: auto; }
|
|
243
|
+
}
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
Or wrap the animation in `@media (prefers-reduced-motion: no-preference)`. Tailwind: `motion-safe:animate-...`. Motion: `<MotionConfig reducedMotion="user">` in a client provider in the root layout.
|
|
247
|
+
|
|
248
|
+
## Production check
|
|
249
|
+
|
|
250
|
+
```sh
|
|
251
|
+
npm run build && npm run start # next build && next start, default port 3000
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Use the project's package manager. Stop the server when done.
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# PageSpeed
|
|
2
|
+
|
|
3
|
+
`npx sugikit psi <url>` (or `sugikit check <url> --psi`) runs PageSpeed Insights (Lighthouse on Google's servers) for mobile and desktop, keeps the best score of 3 runs, and stores `scores.pagespeed` with performance, accessibility, best practices and SEO per strategy. It needs `PSI_API_KEY` and a public URL. Localhost does not work.
|
|
4
|
+
|
|
5
|
+
Each failing Lighthouse audit (score under 0.9) becomes a finding with id `pagespeed/<audit-id>`, for example `pagespeed/render-blocking-resources`. Severity is `error` under 0.5, else `warn`. `fix.summary` holds Lighthouse's own text and, for common audits, a framework hint. Look up the audit id below.
|
|
6
|
+
|
|
7
|
+
Scores move a few points between runs. Compare best-of-3 runs, not single runs. Mobile is the harder target; fix for mobile first.
|
|
8
|
+
|
|
9
|
+
Never remove a feature (analytics, chat widget, video, animation, font, section) to gain points without asking the user. Make it load later or lighter instead, and list the trade-off.
|
|
10
|
+
|
|
11
|
+
## Core metrics
|
|
12
|
+
|
|
13
|
+
- **Largest Contentful Paint (LCP)**: time until the biggest element (usually the hero image or headline) shows. Target 2.5 s or less.
|
|
14
|
+
- **Cumulative Layout Shift (CLS)**: how much the page jumps while it loads. Target 0.1 or less.
|
|
15
|
+
- **Total Blocking Time (TBT)**: main thread blocked by JavaScript. Lab stand-in for INP. Target 200 ms or less.
|
|
16
|
+
- **First Contentful Paint (FCP)** and **Speed Index**: how soon anything shows.
|
|
17
|
+
|
|
18
|
+
## Common audits and fixes
|
|
19
|
+
|
|
20
|
+
### largest-contentful-paint-element, lcp-lazy-loaded, prioritize-lcp-image
|
|
21
|
+
|
|
22
|
+
- Find the LCP element in the audit details.
|
|
23
|
+
- If it is an image: do not lazy load it. Give it `fetchpriority="high"` (Next.js: `priority` or `preload` on `next/image`; check the docs for the installed version). Serve a resized AVIF or WebP.
|
|
24
|
+
- If it is text: make sure the font does not block it (see fonts below) and no client JavaScript renders it.
|
|
25
|
+
- Do not hide the hero behind an entry animation that starts at `opacity: 0`. Start visible, or animate only transform.
|
|
26
|
+
|
|
27
|
+
### render-blocking-resources
|
|
28
|
+
|
|
29
|
+
- Inline or reduce critical CSS. Remove unused CSS imports.
|
|
30
|
+
- Load third-party scripts with `async` or `defer`, or after load (Next.js `next/script` with `strategy="afterInteractive"` or `"lazyOnload"`).
|
|
31
|
+
|
|
32
|
+
### font-display, font preload
|
|
33
|
+
|
|
34
|
+
- Self-host fonts (Next.js `next/font`, or files in `public/` with `@font-face`). Use `font-display: swap`.
|
|
35
|
+
- Preload only the one or two font files the hero uses.
|
|
36
|
+
- Use a fallback with matched metrics (`next/font` does this) to cut layout shift.
|
|
37
|
+
- Keep the same fonts. Subset or limit weights to the ones in use.
|
|
38
|
+
|
|
39
|
+
### uses-responsive-images, modern-image-formats, uses-optimized-images, offscreen-images
|
|
40
|
+
|
|
41
|
+
- Serve images at their display size with `srcset` and `sizes`.
|
|
42
|
+
- Use AVIF or WebP.
|
|
43
|
+
- Lazy load images below the fold (`loading="lazy"`), never the hero.
|
|
44
|
+
|
|
45
|
+
### unsized-images, layout-shift-elements, cumulative-layout-shift
|
|
46
|
+
|
|
47
|
+
- Give every image and video `width` and `height` or `aspect-ratio`.
|
|
48
|
+
- Reserve space for banners, embeds and late content with a min height.
|
|
49
|
+
- Do not insert content above existing content after load.
|
|
50
|
+
|
|
51
|
+
### unused-javascript, bootup-time, mainthread-work-breakdown, total-blocking-time
|
|
52
|
+
|
|
53
|
+
- Keep the page server-rendered; ship client JavaScript only for interactive parts.
|
|
54
|
+
- Code-split heavy widgets (`dynamic()` import in Next.js, `React.lazy`) and load them on interaction or when visible.
|
|
55
|
+
- Load analytics and chat widgets after load or on idle. Do not remove them without asking.
|
|
56
|
+
- Check for large libraries used for small things (a full icon set, a date library, an animation library for one fade).
|
|
57
|
+
|
|
58
|
+
### third-party-summary, third-party-facades
|
|
59
|
+
|
|
60
|
+
- Replace heavy embeds (YouTube, maps, chat) with a facade: a static preview that loads the real embed on click.
|
|
61
|
+
|
|
62
|
+
### uses-text-compression, uses-long-cache-ttl, server-response-time
|
|
63
|
+
|
|
64
|
+
- These depend on the host. Production hosts (Vercel, Netlify, Cloudflare) usually handle compression and caching. Check them only on the production URL, not on a preview with auth or a dev server.
|
|
65
|
+
|
|
66
|
+
### Accessibility and SEO categories in PSI
|
|
67
|
+
|
|
68
|
+
PSI also scores accessibility, best practices and SEO. Sugikit's polish and SEO checks cover most of these. Fix them through the Sugikit findings, not separately.
|
|
69
|
+
|
|
70
|
+
## Setup findings
|
|
71
|
+
|
|
72
|
+
These say PageSpeed did not run. They are not page problems.
|
|
73
|
+
|
|
74
|
+
### pagespeed/local-url (info)
|
|
75
|
+
|
|
76
|
+
The URL is localhost or a private address. PSI cannot reach it. Use a public preview URL (see below).
|
|
77
|
+
|
|
78
|
+
### pagespeed/no-key (info)
|
|
79
|
+
|
|
80
|
+
`PSI_API_KEY` is not set. Ask the user to set it (see below). Never write the key into a file in the repo.
|
|
81
|
+
|
|
82
|
+
### pagespeed/api-error (warn)
|
|
83
|
+
|
|
84
|
+
PSI returned no result for mobile or desktop. `evidence` has the API errors. Check that the URL is public (no auth wall) and the key is valid, then run `npx sugikit psi <url>` again later.
|
|
85
|
+
|
|
86
|
+
## When there is no public URL
|
|
87
|
+
|
|
88
|
+
Tell the user:
|
|
89
|
+
|
|
90
|
+
1. Deploy a preview (Vercel, Netlify, Cloudflare Pages, or the project's host).
|
|
91
|
+
2. Get a free PageSpeed Insights API key in the Google Cloud console (enable "PageSpeed Insights API", create an API key).
|
|
92
|
+
3. Set `PSI_API_KEY` in the shell, then run `npx sugikit psi <public-url>`.
|
|
93
|
+
|
|
94
|
+
The preview must be public (no password or auth wall), or PSI measures the login page.
|