DEV Community: Alan

Build-time content linting: transpiling data files in memory and grading strictness by entry date

Alan — Wed, 04 Nov 2026 07:50:41 +0000

MakeInfographics.ai keeps its infographic gallery entries, fill-in templates, blog posts and Pinterest pin metadata in TypeScript arrays: 270 records at the time of writing. The editing rules for them live in a checklist in the repository, and the header of scripts/content-lint.mjs says the point of the script is to turn that checklist into build-time constraints. It runs as prebuild, so next build stops when a rule fails. The script loads the data modules without compiling the app: it transpiles each .ts file in memory with the typescript package the project already has, runs the emitted CommonJS, then walks every record.

The code is from the repository as of 2026-11-04 (commit 2217330, last touching the script on 2026-10-29). The counts and timings below are from my machine on the same day (Node 22.12.0, macOS). The script's messages are in Chinese; I translate the ones I quote.

Why not import the data from Next?

typescript is already in devDependencies (^5). A second runner such as ts-node or esbuild-register would work, but reusing what npm install already pulls in meant no new dependency. The loader is about 15 lines:

const moduleCache = new Map();
function loadTs(file) {
  if (moduleCache.has(file)) return moduleCache.get(file);
  const source = fs.readFileSync(file, "utf8");
  const { outputText } = ts.transpileModule(source, {
    compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2020 },
  });
  const mod = { exports: {} };
  moduleCache.set(file, mod.exports);
  const req = (spec) => (spec.startsWith("./") ? loadTs(path.join(path.dirname(file), `${spec}.ts`)) : require(spec));
  new Function("module", "exports", "require", outputText)(mod, mod.exports, req);
  moduleCache.set(file, mod.exports);
  return mod.exports;
}

Relative imports recurse through the same function and npm packages go through Node's normal require. The cache is written twice: once before the module runs, so a file that is imported while it is still loading gets its partly filled exports instead of looping, and once after. transpileModule only strips types, it does not type-check, so this is a loader and not a compiler.

Some failures happen before any lint rule runs. The data files call assertUnique and assertRedirectsValid at the top level (for example assertUnique(BLOG_POSTS, (p) => p.slug, "blog slug") in blog-data.ts), and they throw while the module loads. The script catches that, prints a load error and exits with 1. That is deliberate: a duplicate slug should stop the build before any word-count rule is checked.

Hard errors and a dated "strict mode"

Not every rule should apply to an entry written months ago. The script has a cutoff, compared as a string against each entry's dateAdded (infographics, templates, pins) or date (blog posts):

const STRICT_FROM = process.env.CONTENT_LINT_STRICT_FROM || "2026-10-11";
const graded = (isNew, scope, msg) => (isNew ? err(scope, msg) : warn(scope, msg));
// isNew = entry.dateAdded >= STRICT_FROM   (post.date for blog posts)

Hard errors fail for every entry regardless of age. Examples from the script: a broken internal link; an infographic body under 600 words; a gallery thumbnail key with no matching infographic; an unknown category; a printable PDF that is missing or does not start with %PDF-; and Pinterest limits such as title over 100 characters, description over 500, an image path that does not match the pin id, or more than five pins on one calendar day.

Graded rules go through graded. For an entry on or after STRICT_FROM a violation is an error, for an older entry the same violation is a warning and the build goes on. These include the number of keyFacts (5 to 8) and FAQ entries, blog word count (1,500 to 2,500), the length of a template's whyThisTemplate text (at least 400 characters), and near-duplicate infographic titles (Jaccard similarity of title tokens at or above 0.5). A hard-coded set, REVIEWED_DISTINCT_PAIRS, exempts ten older slug pairs that were reviewed by hand and found to target different search intents. A new entry that collides with anything is still an error.

Warnings are grouped: the console shows the first three of a kind and a count for the rest ("9 more of the same kind"), and --verbose lists everything.

What one run covers

After loading, the script validates the four main arrays and also the satellite modules: legal copy, pricing, competitor comparison pages, localized landing pages, /make/ tool pages, use cases and fill-in scenarios. Fill-in templates also get checks that the fields and the promptTemplate agree and that the printable PDFs exist. Pins have to match their board's rules and have a 2:3-ish image, and the same landing page may not receive more than a set number of pins in any seven days (2 by default, 5 for the two boards that fan out into many example pins).

If ../backend/app/catalog.py exists next to the web folder, the script also compares credit counts and USD prices with pricing.ts and the backend's free_quota with the frontend's FREE_GENERATIONS. That backend folder is on my machine, so those checks ran; in a checkout with only the frontend they are skipped without a message.

What I measured on 2026-11-04

I ran node scripts/content-lint.mjs three times from the web folder. Each run took 0.31 s wall time (/usr/bin/time -p; about 0.66 s of user CPU). The summary line, translated:

content lint: infographic 149 · template 54 · blog 21 · pin 46 (strict from 2026-10-11)

That is 270 records in the four main arrays, plus 6 scenarios and 4 infographic examples from scenarios.ts. The exit code was 0 and there were 0 hard errors. I also counted how many entries fall on each side of the cutoff with a separate small script that loads the same files:

Content type	Entries	On or after 2026-10-11 ("strict")	Older ("legacy")
Infographics	149	12	137
Templates	54	17	37
Blog posts	21	2	19
Pinterest pins	46	46	0

With --verbose the run printed 12 warnings, all the same kind: a day between 2026-10-24 and 2026-11-04 with fewer than the recommended 3 to 5 pins. The script only warns for dates from STRICT_FROM up to today, so pins scheduled for the future do not trigger it early. It also printed one informational line: 11 source organisations whose websites could not be confirmed are kept as plain text.

Four patched copies

The script only reads files. To see what it catches without touching the git tree, I copied the web folder to /tmp, symlinked node_modules, applied one patch at a time, ran the linter once and restored the file before the next patch. The patches are in a small script that selects entries by slug, so the run repeats exactly.

Patch	Entry age	Result
Added a link to `/infographic/this-slug-does-not-exist` in a blog post	any	1 error, exit 1: broken internal link
Cut `keyFacts` of `artificial-intelligence-trends-2026` (`dateAdded` 2026-09-07) to 1 item	legacy	1 extra warning ("keyFacts 1, should be 5-8"), exit 0
Cut `whyThisTemplate` of `elegant-destination-guide` (`dateAdded` 2026-10-22) to 29 characters	strict	1 error, exit 1 ("29 characters, needs at least 400")
Put "The moon is made of cheese." at the start of the body of `artificial-intelligence-trends-2026`	legacy	nothing reported, exit 0

The second and third rows are the same kind of mistake with different outcomes, and the entry's date is the only thing that differs. The last row is the limit of the whole approach: the script counts words and follows links, it cannot tell whether a sentence is true.

What I would change

I have not changed the linter.

Turn the four patches above into fixtures with expected exit codes. Today they are a script I ran by hand, not a test.
Validate CONTENT_LINT_STRICT_FROM. It is compared as a string, so a value that is not YYYY-MM-DD would silently move the cutoff, and I found no check on the variable. The pins validate their dates with a regex, but the cutoff itself is not validated.
Read "passes lint" as "structurally sound", not as "reviewed". The 149 infographics include statistics that the script never re-checks against their sources.

What this does not show

Factual accuracy. Word counts, links and image files are checked. Whether a figure matches the report it cites is not, as the last patch shows.
A clean checkout. I ran the script on one working copy that has local PDFs and an image-manifest.json. I did not try a fresh clone where images exist only on the CDN.
The frontend-only case. The pricing and quota checks ran because ../backend exists on my machine. I did not run the script without it.
Every strict rule on every legacy entry. I patched one legacy infographic and one strict template, so I cannot say how many other entries would fail today's rules.
Anything at runtime. I did not open the site in a browser or run the generation flow.

If you keep marketing data in TypeScript, how do you gate its quality: eslint plugins, code generation, or a script like this one?

The Monthly Budget Planner template page is an example of the fill-in template records this script validates (fields, prompt template and printable PDF paths).

This article was drafted with help from an AI assistant and edited by me. The code excerpts come from the project's repository, and the measurements are from my own runs on 2026-11-04.

Keeping noindex, the sitemap and the image sitemap in agreement for programmatic pages

Alan — Mon, 02 Nov 2026 14:48:00 +0000

Google's documentation for sitemaps says to "include the URLs in your sitemap that you want to see in Google's search results". Its documentation for the robots meta tag says the noindex rule means: "Do not show this page, media, or resource in search results." A URL that carries both is giving two answers, and when the pages are generated from one array it is easy for them to drift apart without anyone noticing.

LandscapeCraft (landscapecraft.ai) is a Next.js App Router site with 40 design-style pages generated from one TypeScript array. A style can have a long MDX write-up in content/styles/. A style without one falls back to a short generic template, and the site treats that page as thin: it renders noindex, follow, and its URL stays out of both sitemap.xml and image-sitemap.xml.

This post is about those three places: how the code keeps them in step, how I checked that it does, and where it can still drift. The code is from the repository as of 2026-11-02, and the live numbers are from the same day. Code comments below are translated from Chinese.

One question, asked three times

The helper is small:

export function getStyleContent(slug: string): StyleContent | null {
  const filePath = path.join(STYLES_CONTENT_DIR, `${slug}.mdx`);
  if (!fs.existsSync(filePath)) return null;
  const raw = fs.readFileSync(filePath, "utf-8");
  const { content } = matter(raw);
  return { slug, content };
}

The style page asks it for its metadata:

// app/styles/[slug]/page.tsx, inside generateMetadata()
// Style pages without long-form content (they fall back to the generic template) stay out of the index
noIndex: !getStyleContent(slug),

buildMetadata turns that flag into metadata.robots = { index: false, follow: true }, which renders as <meta name="robots" content="noindex, follow">. sitemap.ts asks the same question:

// app/sitemap.ts
// Style pages without a long-form MDX are rendered as noindex (see app/styles/[slug]/page.tsx),
// so they must not appear in the sitemap.
const stylePages = ALL_STYLES.filter((s) => !!getStyleContent(s.slug)).map((s) => ({
  url: `${SITE_URL}/styles/${s.slug}`,
  // ...
}));

and so does the image sitemap route:

// app/image-sitemap.xml/route.ts
for (const style of ALL_STYLES) {
  // Style pages without long-form MDX are noindex; keep them out of the image sitemap
  if (!getStyleContent(style.slug)) continue;
  // ...
}

Nothing ties the three together except that predicate and a comment in each file. robots.txt is a fourth party: it disallows only /api/, on purpose. Google's robots meta documentation says that if a page is disallowed in robots.txt, its indexing rules "will not be found and will therefore be ignored", so blocking a noindex page there would defeat the noindex. app/robots.ts has a comment saying the same.

What does a thin page look like here? The fallback is three headings ("About … Design", "Key Design Elements", "Who Is This Style For?") and four generic bullets such as "Signature materials and textures". The 40 MDX write-ups run from 765 to 2,265 words (median 1,104), counted after the front matter.

A guard that has never fired

Before trusting the guard I wanted to see it do something, so I looked at the history first. The commit that added all three filters (2026-10-09) also added the last 12 MDX files: its parent had 33 styles and 21 write-ups, the commit itself 33 and 33. I checked each of the ten commits from that one to today, and none of them has a style without an MDX file. On 2026-11-02, 7 new styles arrived together with their 7 write-ups, making it 40 and 40. As far as the history shows, the noindex branch of the style page has never had a page to act on.

So I tested it on a copy. I exported the committed files with git archive, built them with Next.js 16.3.4 on Node 22.12.0 (macOS) and ran next start. The unmodified copy matched the live site: 249 URLs in sitemap.xml and 199 <url> entries in the image sitemap, 40 of each being style pages. Then I deleted one file, content/styles/wabi-sabi-interior.mdx, rebuilt and measured again:

	all 40 write-ups	`wabi-sabi-interior.mdx` deleted
`/styles/wabi-sabi-interior`	`index, follow` (live site)	HTTP 200, `noindex, follow`, generic template
URLs in `sitemap.xml`	249 (40 style pages)	248 (39)
`<url>` entries in `image-sitemap.xml`	199 (40)	198 (39)

The three move together because one predicate drives them. The page still answers 200 and keeps a canonical pointing at itself: noindex hides a page, it does not remove it.

The same pattern, live today

A second place uses the same idea and does fire right now. A blog category page is indexable only with at least 3 posts (MIN_POSTS_FOR_INDEX). The site has 39 posts in 4 of its 6 categories: 17, 13, 5 and 4. On 2026-11-02 the two empty categories, diy-projects and trends, return 200 with noindex, follow and are in neither sitemap. The other four are index, follow and in sitemap.xml. The image sitemap does not list category pages at all, so it agrees by leaving them out.

This rule is written in two shapes. The sitemap asks getIndexableCategories(), which keeps categories with >= MIN_POSTS_FOR_INDEX posts. The page asks getPostsByCategory(category).length < MIN_POSTS_FOR_INDEX. It is the same constant with opposite operators, in different files.

Where it can still drift

Three things I found, with what I ran for each.

1. The filter covers one page type. The site also has 69 /ideas/<category>/<style> pages. In the copy with wabi-sabi-interior.mdx deleted, its idea page /ideas/bedroom/wabi-sabi-interior stays index, follow and stays in both sitemaps, and it links to the noindex style page twice (the /styles index links to it once). I did not judge whether those idea pages are thin; the point is only that the rule is per page type, not per style.

The idea pages also show a smaller asymmetry. sitemap.ts lists every entry of each category's recommendedStyleSlugs. The image sitemap skips an entry whose style does not exist, and the page itself calls notFound() for one. Reading the code, a typo in a slug would put a URL that returns 404 into sitemap.xml and nowhere else. I did not try it. Today both files list the same 69 URLs.

2. The files are decided at different times. The build output marks /sitemap.xml as static (○) and /image-sitemap.xml as dynamic (ƒ). That matches the Next.js docs: Route Handlers are not cached by default, while sitemap.ts stays static unless it uses request-time APIs. So the style pages' robots tag and sitemap.xml are fixed at build time, while the image sitemap is built on each uncached request by reading content/ from the disk of the running server. The route sets Cache-Control: public, max-age=3600, s-maxage=3600.

To see what that means, I started the unmodified build with next start and renamed content/ while it was running:

	`content/` present	`content/` renamed
`sitemap.xml`	249 URLs, 40 style pages	249, 40
`/styles/japandi-interior` robots	`index, follow`	`index, follow`
`image-sitemap.xml`	199 entries, 40 style pages	120, 0

Renaming it back restored 199. The 79 missing entries are the 40 style pages and the 39 blog posts, which are also read from content/ at request time. This is an artificial failure, not one I have seen in production. On the live site the image sitemap lists all 40 style pages, so the production runtime can see the folder right now. I did not look at how the site is deployed.

3. Nothing checks it. package.json has dev, build, start and lint, and the repository has no test files. The agreement rests on three call sites and some comments.

A smaller thing about the image sitemap

Google's image sitemap documentation requires only <image:image> and <image:loc>, and allows up to 1,000 images per <url>. It also says caption, geo_location, title and license were deprecated in 2022: they have no effect on indexing and search features after 2022-08-06, though you can leave them in place "without drawbacks". This sitemap has 298 images, each with an image:title and an image:caption. That is 596 elements, 67,247 of 138,920 bytes (48.4%). The largest <url> is /gallery with 50 images, far below 1,000. Nothing is broken, but half the file is text Google no longer reads.

What I would change

I haven't made any of these changes.

Write the rule once, for example an isStyleIndexable(slug) used by the metadata, sitemap.ts and the image sitemap. The category rule would get the same treatment.
Add a check after the build: every URL in the image sitemap must be in sitemap.xml, and no URL in either may be noindex. On 2026-11-02 the first holds (199 of 199 image sitemap URLs are in sitemap.xml, with identical lastmod), and the second held for the nine pages I fetched. I did not fetch all 249.
Decide the image sitemap in the same place as sitemap.xml, for instance by rendering it at build time too (export const dynamic = 'force-static' is the documented switch for caching a GET handler).

What this does not show

Whether Google follows any of this. I did not look at Google's index or Search Console for the site.
Anything beyond Next.js 16.3.4 on one machine, built from the committed files and not from the deployed build.
More than one failure shape for each check: one deleted file, one hidden folder.

If you generate noindex, a sitemap and an image sitemap from the same data, how do you test that they still agree? I would like to hear what has worked.

The pages this post is about are the style pages, for example the Japandi Interior page.

This article was drafted with help from an AI assistant and edited by me. The code excerpts come from the project's repository, and the measurements are from my own runs on 2026-11-02.

Checking the numbers in a calculator FAQ against the code behind it

Alan — Mon, 02 Nov 2026 08:32:18 +0000

A reader who types a FAQ's own example into the calculator should get the FAQ's answer. I had never checked whether that is true on my site.

LandscapeCraft (landscapecraft.ai) has three small material calculators: mulch, gravel and pavers. The calculation functions and the page copy live in one file, lib/calculators.ts, and four of the nine FAQ answers contain a number the functions can reproduce. This post is the check: which numbers match, which ones only match under a condition the reader cannot see, and the one place where a floating-point guard decides the answer. The code is from the repository as of 2026-11-02 (commit a0694ab), and the live-page checks are from the same day. The one code comment below is translated from Chinese.

Where the numbers live

FAQ entries are plain strings in an array, one array per calculator:

// lib/calculators.ts (mulch calculator)
{
  q: "How much does a cubic yard of mulch cover?",
  a: "At a depth of 3 inches, one cubic yard covers roughly 108 square feet. At 2 inches it covers about 162 square feet.",
},

The page renders the same array twice, once as visible text and once as FAQPage JSON-LD:

// app/calculators/[slug]/page.tsx
{
  "@type": "FAQPage",
  mainEntity: c.faqs.map((f) => ({
    "@type": "Question",
    name: f.q,
    acceptedAnswer: { "@type": "Answer", text: f.a },
  })),
},

On the three live pages, the 9 visible answers and the 9 JSON-LD answers are character-for-character identical. I am not claiming the markup helps search: Google's documentation updates page says the FAQ rich result "will no longer appear in Google Search starting May 7, 2026", and a later entry says its documentation was removed because the feature "is no longer shown in Google Search results". The reason it matters here is simpler: one wrong sentence in the array is published twice.

The check

The calculators are pure functions, so the check is a loop. Node 22.12 can import the TypeScript file directly with --experimental-strip-types. This is the first FAQ number, and I wrote the same loop for the others:

import * as m from "./lib/calculators.ts";

for (const extra of [0, 10]) {
  const v = m.computeVolume(108, 3, extra); // 108 sq ft, 3 in deep
  console.log(`${extra}%`, v.cuYdWithExtra.toFixed(2));
}
// 0% 1.00
// 10% 1.10

The second case is the page default: in components/calculators/calculator.tsx the allowance starts as useState("10"), and all three calculators use that state. Here is every FAQ figure the functions can reproduce, with the function's answer at 0% and at the default 10%. Each area is the whole number the FAQ implies, and results are formatted to two decimals:

FAQ says	Exact value	At 0% allowance	At the default 10%
Mulch, 3 in deep: 1 cu yd covers about 108 sq ft	108	108 sq ft → 1.00 cu yd	1.10 cu yd
Mulch, 2 in deep: about 162 sq ft	162	162 sq ft → 1.00 cu yd	1.10 cu yd
1 cu yd is 13.5 bags of 2 cu ft, or 9 bags of 3 cu ft	13.5 and 9	108 sq ft at 3 in → 14 and 9 bags	15 and 10 bags
Gravel at 2 in, 1.4 t/cu yd: 1 ton covers about 115 sq ft	115.71	115 sq ft → 0.99 t	1.09 t
Gravel at 3 in: about 77 sq ft	77.14	77 sq ft → 1.00 t	1.10 t
100 sq ft of 12 × 12 pavers with 10% extra: 110	110	not applicable, the answer states 10%	110

For the 108 sq ft case I also checked the live page: 12 ft by 9 ft with the defaults shows "Cubic yards 1.10" with the note "1.00 before the 10% allowance", "Cubic feet 29.7" and "Bags (2 cu ft) 15". The other two calculators I only ran as functions.

None of the FAQ figures is wrong as arithmetic. "About 115" is 115.71 rounded down, which "about" covers. The FAQ answers a geometry question (how much does a yard cover) and the calculator answers a buying question (how much should I order). Five of the six rows assume no allowance, while the default adds 10%. The page admits it in a small note next to the result, and the FAQ never mentions it, so a reader who tests the FAQ against the tool lands 10% off. The bag row shows a second effect: 13.5 is a conversion, but you cannot buy half a bag, so the calculator rounds up to 14 at 0% and to 15 at the default.

The one answer that includes the allowance

The pavers answer is the one FAQ number that does include the allowance: 100 sq ft of 12 × 12 pavers is 100 pavers, plus 10%. In JavaScript:

100 * 1.1;            // 110.00000000000001
Math.ceil(100 * 1.1); // 111

The pavers formula is area × 144 ÷ (length × width), times (1 + waste ÷ 100), rounded up. Without a guard, the FAQ's own example would show 111 on the page next to an FAQ that says 110. The file has the guard:

/** Strip floating-point error before rounding up (e.g. 100 × 1.1 = 110.00000000000001 should not become 111) */
const ceilClean = (n: number) => Math.ceil(Math.round(n * 1e6) / 1e6);

How often does it matter? Rather than argue, I compared three implementations over a grid: the five preset paver sizes, waste of 5, 10, 15 and 20 percent, and every whole area from 1 to 2,000 sq ft, which is 40,000 inputs. The reference is exact integer arithmetic with BigInt, which avoids floats entirely:

const ceilDiv = (a, b) => (a + b - 1n) / b;
// ceil(area × 144 × (100 + waste) / (length × width × 100)), all whole numbers
const exact = Number(ceilDiv(BigInt(area) * 144n * BigInt(100 + waste), BigInt(l * w) * 100n));
const naive = Math.ceil(((area * 144) / (l * w)) * (1 + waste / 100));
const clean = m.computePavers({ areaSqFt: area, paverLengthIn: l, paverWidthIn: w, wastePercent: waste, baseDepthIn: 0, sandDepthIn: 0 }).pavers;

Paver size (in)	Inputs	Unguarded `Math.ceil` differs from exact
12 × 12	8,000	112
12 × 24	8,000	54
16 × 16	8,000	7
4 × 8	8,000	52
6 × 9	8,000	187
Total	40,000	412

In all 412 differing cases the unguarded version asked for more pavers than exact arithmetic, and in none did it ask for fewer. For 12 × 12 pavers all 112 are at 10% waste, and the FAQ's 100 sq ft is one of them (50, 90, 100, 110 and 170 are the first five).

The guard has a price. It rounds to six decimals first, so an area a hair above a whole number counts as that whole number: in my run 100.0000004 sq ft gave 110 and 100.000001 gave 111. Nobody types those, so I think the trade is right, but it is a trade.

What I would change

I haven't changed any of this.

Say what each number assumes. The three answers about mulch coverage, mulch bags and gravel coverage could say "before any allowance", or give both figures.
Do not type derived numbers into copy. Build the answer strings from the same functions, so a changed default or formula changes the sentence too.
Keep the grid comparison as a test. The repository has no test files (package.json has dev, build, start and lint), so today the guard is protected by a comment.

What this does not show

Three calculators on one site. I ran the functions directly and checked the page itself for the mulch calculator only.
The exact reference needs whole-number areas and percentages. Beyond that I tried five areas around 100.
Whether the numbers are right for real materials. Density and bag size are inputs, and I only checked that the copy matches the code.
Anything about how search engines treat the markup.

How do you keep numbers in page copy honest: generate the text from the code, or test it? I would like to hear what has worked.

The page with the 110 is the paver calculator.

This article was drafted with help from an AI assistant and edited by me. The code excerpts come from the project's repository, and the measurements are from my own runs on 2026-11-02.

Printing 72 vector PDFs from HTML and CSS with headless Chrome

Alan — Mon, 26 Oct 2026 11:21:18 +0000

A blank weekly planner has to be one page on US Letter (8.5×11 in) and on A4 (210×297 mm). A4 is narrower and taller, so a layout tuned for one sheet can spill onto a second page or leave a gap on the other.

MakeInfographics.ai offers its templates as free printable PDFs. There are 12 layouts, each in 3 color themes and 2 paper sizes, which makes 72 files. They come from a small Node script that writes HTML and asks Chrome to print it. The project has no PDF library: none in dependencies or devDependencies, and the script imports only Node built-ins and its own modules.

This post covers how the script is organized, how one layout fits both papers, and what its one-page check does and does not catch. I ran everything below on 2026-10-26 with Chrome 155 on macOS (Apple M4 Pro).

Four pieces

scripts/printables/
  registry.mjs   which layouts exist, plus the theme and paper IDs
  base.mjs       page skeleton, CSS and small HTML helpers
  layouts/*.mjs  one file per layout (12 files)
  build.mjs      renders every combination with Chrome

build.mjs is 158 lines, base.mjs is 114, and the 12 layouts add up to 325. The registry is a list plus two constants, so 12 × 3 × 2 = 72:

export const PRINTABLES = [
  { archetype: "weekly-meal-planner", templateId: "handdrawn-weekly-meal-planner", title: "Weekly Meal Planner", pinTheme: "sage" },
  { archetype: "study-schedule-planner", templateId: "playful-study-schedule-planner", title: "Weekly Study Schedule", pinTheme: "blush" },
  // ...10 more
];

export const THEME_IDS = ["mono", "sage", "blush"];
export const PAPER_IDS = ["letter", "a4"];

A layout only says what is on the page. Here is the monthly budget planner, with some parts shortened:

import { box, field, table } from "../base.mjs";

const money = (labels) =>
  table({
    cols: "1.6fr 1fr 1fr",
    header: ["Category", "Planned", "Actual"],
    rows: labels.map((l) => [l, "", ""]),
  });

export default {
  title: "Monthly Budget Planner",
  subtitle: "Know where every dollar goes — planned versus actual.",
  meta: `${field("Month", "1.3in")}${field("Take-home income", "1.1in")}`,
  body: `
<div class="row" style="flex:1">
  <div class="col" style="flex:1">
    ${box("Income", money(["Salary", "Side income", "Other"]), "flex:0 0 auto;")}
    ${box("Fixed expenses", money([/* 8 labels */]), "flex:1")}
  </div>
  <div class="col" style="flex:1">
    ${box("Variable expenses", money([/* 8 labels */]), "flex:1")}
    <!-- savings goal box -->
  </div>
</div>
<!-- three summary boxes -->`,
};

The layout contains no paper size, no colors and no page margins.

One sheet, sized to the paper

base.mjs owns the page. The two papers are two entries in a map:

export const PAPERS = {
  letter: { css: "8.5in 11in", width: "8.5in", height: "11in" },
  a4: { css: "210mm 297mm", width: "210mm", height: "297mm" },
};

The stylesheet turns the chosen paper into an @page size and a fixed-size sheet:

@page { size: ${p.css}; margin: 0; }
:root { --ac:${t.ac}; --soft:${t.soft}; --line:${t.line}; --ink:${t.ink}; --mute:${t.mute}; --pw:${p.width}; --ph:${p.height}; }
.sheet { width: var(--pw); height: var(--ph); padding: 0.5in 0.55in 0.35in; display: flex; flex-direction: column; gap: 9px; overflow: hidden; background: #fff; }
.body { flex: 1; min-height: 0; display: flex; flex-direction: column; gap: 9px; }
.lines > i { flex: 1; min-height: 14px; border-bottom: 0.6pt solid var(--line); }

The trick that lets one layout serve both papers is that rows do not have heights. Writing lines are flex: 1, boxes take a flex share, and the table helper gives its rows auto repeat(n, 1fr): a header row plus equal rows that split what is left. On Letter the body is about 11 in tall minus padding, on A4 about 297 mm minus padding, and the rows stretch to fit. All 72 files come out as one page.

A light palette

Each theme is a handful of colors:

mono: { ac: "#374151", soft: "#f3f4f6", line: "#b7bcc5", ink: "#111827", mute: "#6b7280", pinBg: "#eef0f3" },

The accent color goes on the title, the rule under it, the small box headings and the table headers. Boxes, tables and writing lines use pale fills and hairlines between 0.6 and 0.75 pt, so a page has no large areas of solid color.

The stylesheet also sets -webkit-print-color-adjust: exact; print-color-adjust: exact;. MDN describes economy, the default, as letting a browser leave backgrounds out when printing, and exact as asking it not to. I tried removing the line: headless Chrome 155 printed the pale fills either way, and the two renders had identical pixel counts for the fill color. I kept it for other print paths, but I could not make it matter here.

Driving Chrome

build.mjs writes one HTML file per PDF into a temp folder and prints it through a file:// URL:

const chromeBase = [
  "--headless=new",
  "--disable-gpu",
  "--no-sandbox",
  "--hide-scrollbars",
  "--force-device-scale-factor=1",
  "--virtual-time-budget=15000",
  "--run-all-compositor-stages-before-draw",
];

function renderPdf(url, out) {
  fs.mkdirSync(path.dirname(out), { recursive: true });
  execFileSync(CHROME, [...chromeBase, "--no-pdf-header-footer", `--print-to-pdf=${out}`, url], { stdio: "pipe" });
}

It is one Chrome process per file, run one after another. Generating all 72 took 74.9 seconds on my machine, about a second each.

The pages load Inter and DM Serif Display from Google Fonts when they are rendered, so the script needs a network connection and a local Chrome (CHROME_PATH overrides the default macOS path). I also tried removing two flags. Without --virtual-time-budget, the PDF embedded the same fonts. Without --no-pdf-header-footer, pdftotext found no header or footer text. I did not find a case where either mattered, but I only tested one Chrome version, so I am leaving them in.

What is inside the PDFs

I looked at the 72 committed files:

Page size. The 36 Letter files are 612 × 792 pt. The 36 A4 files are 594.96 × 841.92 pt, where exact A4 is 595.28 × 841.89 pt. The difference is about 0.1 mm. I did not look into why.
File size. 96 to 146 KB, 118 KB on average.
No bitmaps. I searched the raw bytes of all 72 files for /Subtype /Image and found none. pdftotext returns the layout's text, so it is real text and not outlines.
Fonts. pdffonts lists 852 font entries across the 72 files, all embedded and subset. DM Serif Display is a CID TrueType font; Inter comes out as Type 3. I did not look into why.

The one-page check, and what it cannot see

After each render the script counts pages by looking for page objects in the raw PDF bytes:

function pageCount(pdfFile) {
  const text = fs.readFileSync(pdfFile).toString("latin1");
  return (text.match(/\/Type\s*\/Page[^s]/g) || []).length;
}

The [^s] matters. A PDF also has a page-tree node, /Type /Pages. In a one-page PDF I rendered the same way, /Type /Pages appears once, the pattern with [^s] matches once, and without [^s] it matches twice. If any file has a page count other than 1, the script reports it and exits with an error.

What does that catch? I tested two ways of making a layout too big. First, a block 14 in tall inside a Letter sheet, with the word TOPMARKER at its top edge and BOTTOMMARKER at its bottom edge:

The file still has 1 page.
pdftotext finds TOPMARKER and the footer, but not BOTTOMMARKER.
The same block at 8 in tall shows both markers.

Because .sheet has a fixed height and overflow: hidden, a layout that is too tall is cut off at the page edge. It does not spill onto page two. Second, when I replaced the .sheet rule with one that has no fixed height and no overflow: hidden, a 14 in block produced 2 pages, and the check fails.

So the check protects against the sheet becoming taller than the paper. It does not detect a layout that is too tall for its sheet: that content is clipped and the file still reports one page. The script's error message suggests looking for overflow, but this check cannot see it, and there is no check for clipping in the script today.

There is a second check in the Next.js build. A prebuild step runs a content linter that, for every template with a printable, confirms each PDF exists, starts with %PDF- and is at most 400 KB. It does not look at page count or content either.

Same HTML, other outputs

The preview images and the Pinterest pins use the same layouts. sheetHtml can return the CSS and the sheet separately, and a second function places the sheet on a 1000 × 1500 canvas:

const { css, sheet } = sheetHtml(layout, { theme, paper: "a4", templateId: item.templateId }, { wrap: false });

Chrome takes a screenshot with --screenshot and --window-size=1000,1500, and cwebp -quiet -q 84 converts the preview to WebP. The pin variant adds a title and a brand bar, tilts the sheet by 3 degrees and uses the theme's background color.

What it does not do

It does not detect clipped content, as shown above.
It needs a local Chrome, a network connection for fonts and, for previews, cwebp.
It runs by hand with npm run printables; it is not part of the Next.js build.
I have not tested other Chrome versions or other operating systems.

If you have a cheap way to detect overflow in a print-to-PDF pipeline like this, I would like to hear it in the comments.

The files this script produces are the free downloads on pages such as the Monthly Budget Planner.

This article was drafted with help from an AI assistant and edited by me. The code excerpts come from the project's repository, and the measurements are from my own runs on 2026-10-26.

Checking an image against platform specs in the browser, without uploading it

Alan — Fri, 23 Oct 2026 11:51:01 +0000

A 2.3 MB thumbnail is inside YouTube's limit when you upload it from a computer and over it when you upload from the mobile app. YouTube allows 50 MB from a computer and 2 MB from the app, so the same file passes in one place and not in the other.

Most of what makes an image wrong for a platform can be read from the file itself: pixel size, aspect ratio, byte size, file type, transparency and, for marketplace photos, how white the background is. We built a checker for this in PiCraft (picraft.ai). It runs entirely in the browser and nothing is uploaded. This post covers how it reads each of those things, and where it is only estimating.

What the checker needs from a file

Six values:

Width and height in pixels
Size in bytes
File type
Share of transparent pixels
Share of the border that is pure white
How much of the frame the non-white content spans

The first three are read from the file. The last three come from a reduced copy of the image, so they are estimates.

Pixels and bytes: let the browser decode it

URL.createObjectURL gives you a URL for a local File without reading or sending it anywhere. Load that URL into an Image and naturalWidth and naturalHeight are the pixel size. The byte size is file.size.

function loadImage(url: string): Promise<HTMLImageElement> {
  return new Promise((resolve, reject) => {
    const image = new Image();
    image.onload = () => resolve(image);
    image.onerror = () => reject(new Error("The browser could not open this file."));
    image.src = url;
  });
}

async function readImage(file: File) {
  const url = URL.createObjectURL(file);
  try {
    const image = await loadImage(url);
    const width = image.naturalWidth;
    const height = image.naturalHeight;
    if (!width || !height) throw new Error("This file has no pixel size, so it cannot be checked.");
    return { url, width, height, bytes: file.size, image };
  } catch (error) {
    URL.revokeObjectURL(url); // on success the URL stays alive for the preview
    throw error;
  }
}

File type: we trust the MIME type and the extension

The checker decides the format from file.type and falls back to the extension when the type is empty:

function detectFormat(file: File) {
  const type = file.type.toLowerCase();
  const extension = file.name.toLowerCase().split(".").pop() ?? "";
  if (type === "image/jpeg" || (!type && (extension === "jpg" || extension === "jpeg"))) return "jpg";
  if (type === "image/png" || (!type && extension === "png")) return "png";
  // webp, gif and tiff work the same way; anything else is "other"
  return "other";
}

This is cheap, and it is wrong for a file that was renamed from .jpg to .png with the type missing or edited. If that matters to you, read the first bytes instead. The checker does not do this yet; this is what it would look like:

async function sniffFormat(file: File): Promise<"jpg" | "png" | "gif" | "webp" | "tiff" | "other"> {
  const b = new Uint8Array(await file.slice(0, 12).arrayBuffer());
  const ascii = (from: number, to: number) => String.fromCharCode(...b.slice(from, to));
  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return "jpg";
  if (b[0] === 0x89 && ascii(1, 4) === "PNG") return "png";
  if (ascii(0, 3) === "GIF") return "gif";
  if (ascii(0, 4) === "RIFF" && ascii(8, 12) === "WEBP") return "webp";
  const little = b[0] === 0x49 && b[1] === 0x49 && b[2] === 0x2a && b[3] === 0;
  const big = b[0] === 0x4d && b[1] === 0x4d && b[2] === 0 && b[3] === 0x2a;
  if (little || big) return "tiff";
  return "other";
}

Looking at the pixels without reading all of them

Transparency, a white background and "does the product fill the frame" all need pixel values. Looping over every pixel of a 4000×3000 photo is more work than these checks need, so the checker draws the image onto a canvas whose longest side is at most 400 px and reads that.

const SAMPLE_SIDE = 400;

function samplePixels(image: HTMLImageElement, width: number, height: number) {
  const scale = Math.min(1, SAMPLE_SIDE / Math.max(width, height));
  const sw = Math.max(1, Math.round(width * scale));
  const sh = Math.max(1, Math.round(height * scale));
  const canvas = document.createElement("canvas");
  canvas.width = sw;
  canvas.height = sh;
  const context = canvas.getContext("2d", { willReadFrequently: true });
  if (!context) return { transparentShare: 0, whiteBorderShare: 0, fill: 0 };
  context.drawImage(image, 0, 0, sw, sh);
  const data = context.getImageData(0, 0, sw, sh).data;

  const ring = Math.max(1, Math.round(Math.min(sw, sh) * 0.01)); // the outer 1% is "the border"
  let transparent = 0, border = 0, whiteBorder = 0;
  let minX = sw, maxX = -1, minY = sh, maxY = -1;

  for (let y = 0; y < sh; y++) {
    for (let x = 0; x < sw; x++) {
      const i = (y * sw + x) * 4;
      const alpha = data[i + 3];
      if (alpha < 250) transparent++;

      // Composite on white, the way the pixel would look on a white page.
      const mix = (channel: number) => (channel * alpha + 255 * (255 - alpha)) / 255;
      const lowest = Math.min(mix(data[i]), mix(data[i + 1]), mix(data[i + 2]));

      if (lowest < 245) { // not white: part of the content
        if (x < minX) minX = x;
        if (x > maxX) maxX = x;
        if (y < minY) minY = y;
        if (y > maxY) maxY = y;
      }
      if (x < ring || y < ring || x >= sw - ring || y >= sh - ring) {
        border++;
        if (lowest >= 250) whiteBorder++;
      }
    }
  }

  const fill = maxX < 0 ? 0 : Math.max((maxX - minX + 1) / sw, (maxY - minY + 1) / sh);
  return {
    transparentShare: transparent / (sw * sh),
    whiteBorderShare: border === 0 ? 0 : whiteBorder / border,
    fill,
  };
}

Two choices in there are worth explaining.

Transparent pixels count as white. A product cutout with a transparent background looks white on a white page, so the white-border test composites each pixel on white first. Fully transparent pixels come back from getImageData as (0, 0, 0, 0), so without that step they would look black and the test would fail for exactly the files that are fine.

Fill is a bounding box, not an area. "The product fills at least 85% of the frame" is the kind of rule marketplaces state but do not define. The checker measures how far the non-white content spreads across the frame, the larger of width and height. It is a guide. The output says so ("estimate"), and it does not claim to know how any marketplace measures it.

The cost of the 400 px copy is that very thin details can disappear: a faint shadow a pixel or two wide at full size is gone. For pass or fail on pixel size, ratio and bytes that does not matter, because those use the real file. It matters only for the three pixel-based values. The two that are judgement calls, the white background and the fill, are labelled "estimate" in the results.

Rules as data, checks as pure functions

Every platform rule is a preset in a JSON file, and the checks are pure functions of (preset, imageInfo). The same file runs on the server (to render the preset table) and in the browser (to run the checks), so it cannot import anything server-only.

A preset is a handful of optional fields. The YouTube thumbnail looks like this:

{
  "id": "youtube-thumbnail",
  "width": 1280,
  "height": 720,
  "minWidth": 640,
  "aspect": [16, 9],
  "formats": ["jpg", "png"],
  "warnBytes": 2097152,
  "maxBytes": 52428800,
  "bytesNote": "YouTube allows 2 MB from its mobile app and 50 MB from a computer."
}

warnBytes and maxBytes are the answer to the opening problem. A limit that depends on which device you upload from cannot be a single pass or fail. Over 2 MB is a warning, with the note that the app has the stricter limit, and over 50 MB is a failure.

The other thresholds are plain numbers in the same style:

Aspect ratio: off by more than 1% is a warning, more than 5% is a failure, and the message says how much to crop and from which edges.
Print resolution: dpi = min(width / frameWidthInches, height / frameHeightInches). At least 299 passes, 150 to 299 warns, below that fails.
White background: at least 98% of border pixels pure white passes, 90% to 98% warns.
Transparency: at least 1% of pixels transparent.

Print presets carry the bleed. A US business card is 3.5×2 in, and with 0.125 in of bleed per edge the file is 3.75×2.25 in, which is 1125×675 px at 300 DPI.

What it does not do

It does not read DPI metadata. DPI is worked out from the pixel size and the print size.
It does not check color mode (RGB or CMYK), color profiles, or fonts in PDFs.
It cannot see text, logos or watermarks, which marketplaces forbid on main images.
It labels the white-background and fill results "estimate", because they come from the 400 px copy.

Every preset links to the size guide behind it, and the guide cites the official page the numbers came from, so you can check a rule before you trust it: picraft.ai/tools/image-size-checker. It is free, needs no account and uploads nothing.

If you have a rule that is missing or out of date, tell us in the comments. Platforms change their numbers.

This article was drafted with help from an AI assistant and edited by a person at PiCraft. The code excerpts come from the checker's source, and the YouTube limits are from YouTube Help (checked 2026-10-23).

Every number on my calculator site has a source and a date. Here is the data architecture

Alan — Wed, 21 Oct 2026 15:55:17 +0000

I run a free financial calculator site: 38 calculators, Next.js App Router, fully static, all math in the browser. When I audited it last month I found the problem you probably have in your own app too: reference numbers copy-pasted into too many places.
The 2026 tax brackets lived in four calculators, three articles and a dozen FAQ answers. The default mortgage rate was typed into eight calculators, and every worked example computed from it went stale the week the rate moved. Worse, the FAQ answers feed JSON-LD, so a stale number was also stale in search results.

One module per kind of reference data

// src/lib/market-data.ts
import type { SourceLink } from "@/components/Sources";
export const MORTGAGE_MARKET = {
  thirtyYear: 7.4,            // Freddie Mac PMMS, %
  thirtyYearYearAgo: 6.27,
  asOf: "2026-10-15",
  asOfLabel: "October 15, 2026",
  checkedOn: "2026-10-20",
  checkedLabel: "October 2026",
} as const;
export const MORTGAGE_MARKET_SOURCES: SourceLink[] = [
  { label: "Freddie Mac PMMS (Oct. 15, 2026)", href: "https://www.freddiemac.com/pmms" },
];
export const DEFAULT_MORTGAGE_RATE = String(MORTGAGE_MARKET.thirtyYear);

Calculators import the default. Articles build their sentences from the constants instead of pasting "7.40%". Tax data has the same shape in tax-data.ts: values, taxYear, checkedOn, sources. A refresh is now a one-file edit plus recomputing the examples.

The client/server boundary bug

My first version exported these constants from the calculator component. The calculator is a "use client" file; the article that quotes the rate is a server component. In the App Router, anything you import from a "use client" module into a server component is a client reference, not the value. The fix is boring: shared constants live in plain lib modules that both sides import.

Make the citation a component, not a convention

<Sources
  items={MORTGAGE_MARKET_SOURCES}
  checked={MORTGAGE_MARKET.checkedLabel}
  note="Your lender's quote will differ."
/>

Programmatic variant pages carry the same data (sources, sourcesChecked, sourcesNote on the variant type), so a page cannot quote a rate without rendering where it came from and when it was checked.

Verify the built HTML, not the source

There is no browser test suite, so after next build I check .next/server/app/**/*.html:

Strip tags and assert the pre-filled calculator's output appears in the text (for example $2,401.16 on the house payment page). This catches FAQ text that drifted from the calculator.
Parse every JSON-LD block (652 of them):

for (const [, json] of html.matchAll(/<script type="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g)) {
  JSON.parse(json);
}

Grep for joined text: rg "</(strong|a|em|b)>[A-Za-z0-9]" .next/server/app. In my setup, a multi-line JSX text node containing ' swallowed the space after a preceding inline element and rendered "Label:text". Writing literal characters instead of entities fixed it. ## Measure statistics, do not recall them An article table claimed healthcare inflation of 5.2% a year and college tuition of 6.0%, "based on CPI component data". I pulled the BLS series through FRED and computed the compound annual change from September 2006 to September 2026:

const cagr = (a, b, years) => (Math.pow(b / a, 1 / years) - 1) * 100;
cagr(338.3, 593.651, 20); // medical care (CPIMEDNS)               -> 2.85
cagr(481.7, 938.353, 20); // college tuition and fees (CUUR0000SEEB) -> 3.39

The real numbers are 2.9% and 3.4%. The page now names the series and the window, and a planning assumption like "model 5% for college" is labeled as a stress test next to the measured rate.

Embeds that resize themselves

Calculators can be embedded with an iframe. Inside the frame, a small client component reports its height:

useEffect(() => {
  const el = document.getElementById(targetId);
  if (!el || window.parent === window) return;
  let last = 0;
  const report = () => {
    const height = Math.ceil(el.getBoundingClientRect().height);
    if (height === last) return;
    last = height;
    window.parent.postMessage({ type: "calcwise:resize", slug, height }, "*");
  };
  const observer = new ResizeObserver(report);
  observer.observe(el);
  report();
  return () => observer.disconnect();
}, [slug, targetId]);

The optional host script checks event.origin, matches frame.contentWindow === event.source, and clamps the height to 200-4000px. The message contains a height and nothing else, which is why "*" as the target origin is acceptable here. To pick sensible default heights I load each embed in a hidden 720px iframe and read the messages. That caught four calculators whose layout had grown since the last measurement.

Refresh on events, not on a schedule

A daily refresh job mostly produced date bumps. Now it is event-driven: the IRS inflation-adjustment Rev. Proc. (usually October or November), the SSA COLA, a 0.25-point move in the Freddie Mac average, Census ACS releases, and a quarterly sweep.
If you want to see the result, the methodology page lists how each figure is sourced, the calculators are free to embed, and the state-level dataset is at /reports/mortgage-affordability-by-state.

Generating Image Sitemaps, RSS and a Pinterest Feed in Next.js Route Handlers

Alan — Wed, 21 Oct 2026 03:19:53 +0000

For a content-heavy site, you want your pages and images discoverable on as many channels as possible: Google (including image search), RSS readers, and Pinterest.

On Belle AI, I generate all three from the same typed content data using plain Next.js route handlers. No plugins needed.

Disclosure: I'm the developer of Belle AI.

The idea: one source of truth

My content lives in typed TypeScript modules: season palettes, lookbooks, face shape guides, blog posts. Each has slugs, titles, and image paths.

import { SEASON_PALETTES, SEASON_SLUGS } from "@/lib/color-palette-data";
import { LOOKBOOK_DATA } from "@/lib/lookbook-data";
import { getAllPosts } from "@/lib/blog";

The sitemap and the feeds all read from these modules. If I add a new lookbook entry, it appears in every output automatically. No second list to forget to update.

Route handlers can return any XML

A file at app/sitemap-images.xml/route.ts is served at /sitemap-images.xml. Return a Response with the right content type:

export async function GET() {
  const entries: ImageEntry[] = buildEntries();
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
${entries.map(renderUrl).join("\n")}
</urlset>`;

  return new Response(xml, {
    headers: {
      "Content-Type": "application/xml; charset=utf-8",
      "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
    },
  });
}

Always escape your XML

Titles and captions contain &, quotes and apostrophes. One unescaped character makes the whole file invalid, and crawlers will silently drop it.

function esc(value: string): string {
  return value
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&apos;");
}

Escape & first, or you'll double-escape the others.

Absolute URLs and locale paths

Sitemaps need absolute URLs. With a default locale that has no prefix and other locales that do, I use two small helpers:

function localePath(locale: string, path: string): string {
  const isDefault = locale === routing.defaultLocale;
  return isDefault
    ? `${SITE_URL}${path || "/"}`
    : `${SITE_URL}/${locale}${path}`;
}

function absUrl(imagePath: string): string {
  if (imagePath.startsWith("http")) return imagePath;
  return `${SITE_URL}${imagePath.startsWith("/") ? imagePath : `/${imagePath}`}`;
}

Use one SITE_URL constant everywhere. Mixing www and non-www hosts in a sitemap is a quiet way to create duplicate-content signals.

Image sitemaps: attach images to page URLs

Each <url> can contain <image:image> entries, which helps Google discover images that are rendered by components or loaded lazily:

interface ImageEntry {
  loc: string;
  images: { url: string; title?: string; caption?: string }[];
}

For pages without a hand-picked image, I point to the dynamic opengraph-image route, so every page still contributes an image.

The Pinterest feed

Pinterest can ingest an RSS feed, and each item needs an image. I reuse the same data and shape each item like this:

interface FeedItem {
  title: string;
  link: string;
  description: string;
  imageUrl: string;
  pubDate: string;
  category: string;
}

const items: FeedItem[] = [];

for (const post of getAllPosts("en")) {
  if (!post.image) continue; // Pinterest needs an image
  items.push({
    title: post.title,
    link: `${SITE_URL}/blog/${post.slug}`,
    description: post.description,
    imageUrl: absUrl(post.image),
    pubDate: new Date(post.date).toUTCString(),
    category: "Blog",
  });
}

The same loop pattern then adds lookbook images, transformation galleries and guides, each with its own category.

Per-language feeds

Because Next.js page alternates replace layout-level ones, I expose a feed per locale and advertise it from the same helper that builds canonical and hreflang tags:

function rssTypes(locale: string) {
  return {
    "application/rss+xml":
      locale === routing.defaultLocale
        ? `${SITE_URL}/feed.xml`
        : `${SITE_URL}/feed/blog/${locale}.xml`,
  };
}

Every page's <head> now points readers to the right feed for their language.

Checklist

One typed data source feeds the sitemap, RSS and Pinterest feed
Escape all dynamic text in XML
Use absolute URLs and one canonical host
Skip items with no image in the Pinterest feed
Add cache headers so crawlers don't hammer your server
Advertise feeds in <head> via alternates.types

You can see the site these routes belong to here.

Do you generate feeds and sitemaps from content data like this, or do you use a plugin? Curious what trade-offs others have hit.

Why Hosted Checkout Breaks Your Analytics (and How I Fixed Attribution with Webhooks)

Alan — Mon, 19 Oct 2026 02:51:59 +0000

When I started selling subscriptions for Belle AI, I added the usual GA4 purchase event on the thank-you page.

It reported almost nothing.

The reason is simple: with a hosted checkout, users pay on the provider's domain and often never return to your site. The browser-side event never fires. Revenue shows up in the payment dashboard but not in analytics, and you can't tell which channel earned it.

Disclosure: I'm the developer of Belle AI.

Here's the setup I ended up with. It has three parts.

Part 1: Capture first-touch attribution on landing

When someone arrives with UTM parameters or from an external site, store it once in localStorage. Don't overwrite it on later visits, otherwise a direct visit next week erases the source that actually brought them.

const ATTR_KEY = "attribution";

export function captureAttribution(): void {
  const params = new URLSearchParams(window.location.search);
  const current = {
    utm_source: params.get("utm_source") ?? undefined,
    utm_medium: params.get("utm_medium") ?? undefined,
    utm_campaign: params.get("utm_campaign") ?? undefined,
    ref: params.get("ref") ?? undefined,
    referrer_host: externalReferrerHost(), // e.g. www.google.com
  };

  const hasSignal = Object.values(current).some(Boolean);
  if (!hasSignal) return;

  const stored = readStored();
  if (stored && (stored.utm_source || stored.referrer_host || stored.ref)) {
    return; // keep the first touch
  }

  localStorage.setItem(
    ATTR_KEY,
    JSON.stringify({ ...current, landing: location.pathname, ts: Date.now() }),
  );
}

Two details matter here:

Organic traffic (search, Pinterest) has no UTMs, so I also keep referrer_host and the landing path.
Wrap storage access in try/catch. Private mode can make localStorage throw.

Part 2: Send attribution with the order

At checkout, I pass the stored attribution plus the GA identifiers into the order's metadata. The payment provider echoes this metadata back in its webhook.

// Read the GA4 client_id from the _ga cookie
export function getGaClientId() {
  const m = document.cookie.match(/(?:^|;\s*)_ga=GA\d+\.\d+\.(\d+\.\d+)/);
  return m?.[1];
}

// Read the current GA4 session id from the _ga_<container> cookie
export function getGaSessionId(measurementId: string) {
  const name = `_ga_${measurementId.replace(/^G-/, "")}`;
  const m = document.cookie.match(
    new RegExp(`(?:^|;\\s*)${name}=GS\\d\\.\\d\\.(?:s)?(\\d+)`),
  );
  return m?.[1];
}

The session_id is what makes this work. Without it, server-side purchases often land in (not set) instead of the real traffic channel.

Part 3: Fire the purchase from the webhook

When the payment provider confirms payment, the webhook handler sends a purchase event through the GA4 Measurement Protocol, reusing the client_id and session_id captured earlier:

async function sendGaPurchase(userId: string, data: any, metadata: Record<string, string>) {
  const apiSecret = process.env.GA_API_SECRET;
  if (!apiSecret) return; // silently skip if not configured

  const value = Number(data.chargedAmount);
  if (!(value > 0)) return;

  await fetch(
    `https://www.google-analytics.com/mp/collect?measurement_id=${GA_ID}&api_secret=${apiSecret}`,
    {
      method: "POST",
      body: JSON.stringify({
        client_id: metadata.ga_cid || `server.${userId}`,
        user_id: userId,
        events: [{
          name: "purchase",
          params: {
            transaction_id: data.paymentId,
            value,
            currency: data.currency || "USD",
            campaign_source: metadata.utm_source,
            campaign_medium: metadata.utm_medium,
            campaign_name: metadata.utm_campaign,
            referrer_host: metadata.referrer_host,
            landing_page: metadata.landing,
            ...(metadata.ga_sid
              ? { session_id: Number(metadata.ga_sid), engagement_time_msec: 1 }
              : {}),
          },
        }],
      }),
    },
  );
}

One note: custom params like referrer_host and landing_page only show up in GA4 reports after you register them as event-scoped custom dimensions.

The webhook itself needs to be boring and safe

Since money is involved, a few rules I follow:

Verify the signature first. Return 401 on failure.
Make it idempotent. Providers redeliver events. I build an event key (eventType:eventId) and let the backend de-duplicate in the database. An in-memory Set breaks with multiple instances or restarts.
Return 500 on transient failures so the provider retries. A paid order that never grants access is the worst bug you can have.
Return 200 for permanent failures (like "user not found"), and alert a human. Retrying won't fix it.
Only report to analytics on the first delivery. If the backend says "already processed", skip the GA call so you don't double-count revenue.

if (code >= 500 || code === 403) {
  return new Response("Backend processing failed", { status: 500 }); // retry
}
if (code === 404) {
  await alertHuman("user not found", orderId);
  return NextResponse.json({ received: true, warning: "user not found" }); // don't retry
}
if (result.message !== "Event already processed") {
  await sendGaPurchase(userId, data, metadata);
}
return new Response("OK");

Result

Revenue now shows up in GA4 under the actual channel: a Pinterest pin, a search landing page, a directory listing, or a referral code. That changed which channels I invest in.

If you want to see the product this runs on, it's here.

Question for the comments: how do you attribute revenue when checkout happens off-site? Anything better than first-touch in localStorage?

Polling Long-Running AI Jobs on Mobile Web: Retries, Backoff, and the visibilitychange Trick

Alan — Sun, 18 Oct 2026 03:00:46 +0000

Most AI features I've shipped have the same shape: the user uploads something, the server kicks off a job that takes anywhere from a few seconds to a minute, and the client has to wait.

In Belle AI (a selfie-based color analysis tool), a report takes about 10-60 seconds. Most users are on phones, so the "just poll every N seconds" approach fell apart quickly.

This post covers the four things I had to fix. It's a follow-up to my earlier post on the Next.js SEO lessons from this project.

Disclosure: I'm the developer of Belle AI.

The shape of the API

Two calls: one to create a task, and one to poll it.

const { data } = await createTask(imageUrl, "color_analysis", "en");
// data.task_id

const res = await pollTask(data.task_id);
// res.data.status: "pending" | "done" | "failed"

Simple enough. The trouble starts with the real world.

Problem 1: Uploads fail randomly on mobile

Before the job even starts, the selfie has to be uploaded. On mobile networks, timeouts and dropped connections are routine.

I added a per-attempt timeout and up to three attempts with linear backoff. The important detail is what you retry:

const UPLOAD_MAX_ATTEMPTS = 3;
const UPLOAD_TIMEOUT_MS = 45_000;

export async function uploadImage(base64: string) {
  let lastError: unknown = null;

  for (let attempt = 1; attempt <= UPLOAD_MAX_ATTEMPTS; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), UPLOAD_TIMEOUT_MS);
    try {
      const res = await fetch("/upload", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ imageBase64: base64, fileType: "jpg" }),
        signal: controller.signal,
      });

      // Retry only on 5xx. 4xx is the caller's fault; retrying won't help.
      if (res.status >= 500 && attempt < UPLOAD_MAX_ATTEMPTS) {
        lastError = new Error(`HTTP ${res.status}`);
      } else {
        return await res.json();
      }
    } catch (err) {
      lastError = err; // network error or abort
      if (attempt === UPLOAD_MAX_ATTEMPTS) throw err;
    } finally {
      clearTimeout(timer);
    }
    await new Promise((r) => setTimeout(r, attempt * 1000)); // 1s, 2s
  }
  throw lastError instanceof Error ? lastError : new Error("upload_failed");
}

Retry network errors and 5xx. Return business errors (4xx, or an error code in the body) straight to the caller.

Problem 2: Waiting a full interval before the first poll

If you poll every 10 seconds, the user stares at a spinner for 10 seconds even when the job finished in 4.

Use a shorter first delay:

const FIRST_POLL_DELAY_MS = 3000;

await waitForNextPoll(first ? Math.min(FIRST_POLL_DELAY_MS, intervalMs) : intervalMs);

Problem 3: Backgrounded tabs freeze your timers

This was the sneaky one. A user taps "Analyze", switches to another app while waiting, then comes back. Mobile browsers throttle or freeze timers in background tabs, so the job is long done but the progress bar is still crawling.

The fix is to wait for either the timer or the tab becoming visible again:

function waitForNextPoll(ms: number): Promise<void> {
  return new Promise((resolve) => {
    let finished = false;
    const finish = () => {
      if (finished) return;
      finished = true;
      clearTimeout(timer);
      document.removeEventListener("visibilitychange", onVisible);
      resolve();
    };
    const onVisible = () => {
      if (document.visibilityState === "visible") finish();
    };
    const timer = setTimeout(finish, ms);
    document.addEventListener("visibilitychange", onVisible);
  });
}

When the user returns, we poll immediately instead of waiting for a frozen timer.

Problem 4: "Max attempts" lies when timers are throttled

My original timeout was maxAttempts * intervalMs, counted in loop iterations. With frozen timers, iterations stop happening, so the budget stretches unpredictably.

Use wall-clock time instead:

const deadline = Date.now() + maxAttempts * intervalMs;

for (let first = true; ; first = false) {
  if (!first && Date.now() > deadline) break;
  await waitForNextPoll(first ? 3000 : intervalMs);
  // ...poll
}
throw new Error("Timed out");

Time spent in the background now counts against the budget, which is what the user expects.

Bonus: Tolerate a few poll errors, not unlimited ones

A single failed poll shouldn't kill a job that's still running. But five in a row probably means something is wrong:

let consecutiveErrors = 0;
const maxConsecutiveErrors = 5;

try {
  const res = await pollTask(taskId);
  if (res.code === 500) {
    if (++consecutiveErrors >= maxConsecutiveErrors) throw new Error("Server error");
    continue;
  }
  consecutiveErrors = 0; // any success resets the counter
  // ...
} catch (err) {
  if (err instanceof TypeError) { // fetch network failure
    if (++consecutiveErrors >= maxConsecutiveErrors) throw new Error("Network error");
    continue;
  }
  throw err;
}

Summary

Problem	Fix
Flaky uploads	Timeout + 3 attempts, retry only network errors and 5xx
Slow first feedback	Shorter first poll delay
Frozen background timers	Resolve the wait on `visibilitychange`
Unreliable max attempts	Wall-clock deadline
Transient poll errors	Tolerate N consecutive failures, reset on success

If you'd rather not poll at all, SSE or WebSockets are options, but polling is simple, works behind every proxy, and with these fixes it behaves well on phones.

Want to see it in action? Try the web version or the iOS app.

How do you handle long-running jobs on the client: polling, SSE, or WebSockets? I'd love to hear what's worked for you.

I Built an AI Color Analysis App in 9 Languages: Next.js SEO Lessons I Wish I Knew Earlier

Alan — Fri, 16 Oct 2026 08:00:59 +0000

Over the last few months I've been building Belle AI, an app that takes a single selfie and tells you your seasonal color type (the 12-season system), your most flattering makeup shades, and your face shape.

It ships as an iOS app and a Next.js website. The website turned out to be where I learned the most, mostly about multilingual SEO. This post covers what I built and the mistakes that cost me the most time.

Disclosure: I'm the developer of Belle AI. The links below point to my project.

What it does

Personal color analysis is usually done by a human stylist who drapes colored fabrics under your face. It typically costs $150-400 and takes a couple of hours.

Belle AI approximates that with a vision model pipeline:

You upload a selfie.
The model estimates skin undertone, eye color, hair color and contrast level.
It maps you to one of 12 seasons (Spring, Summer, Autumn, Winter, each with Light, Warm, Soft, Cool, Deep or Bright variants).
It generates a report with a palette for clothing, makeup, hair and jewelry.

You can try it here: aicoloranalysis.io

The stack

Web: Next.js (App Router), React, Tailwind CSS, next-intl for i18n
Auth and payments: Auth.js, plus a merchant-of-record payment provider
Backend: Python API that talks to generative AI models
Mobile: native iOS app (App Store)
Locales: English, Chinese, Japanese, Korean, Spanish, French, German, Russian, Turkish

Lesson 1: Next.js metadata is replaced, not merged

This one bit me hard. In the App Router, if a page exports its own openGraph or twitter object, it replaces the one from your layout. It does not merge with it.

So any page that defined its own openGraph without images silently lost its share preview image. Pinterest and X showed blank cards.

The fix is boring: export shared constants and include them explicitly everywhere.

export const OG_IMAGES = [
  { url: `${SITE_URL}/opengraph-image`, width: 1200, height: 630 },
];
export const TWITTER_IMAGES = [`${SITE_URL}/opengraph-image`];

If a page has its own opengraph-image file, skip the shared constant there.

Lesson 2: hreflang only works if it's reciprocal

My first approach was to emit hreflang alternates for every locale on every page. That was wrong.

Not every blog post exists in every language, and some thin translations are noindex. Pointing hreflang at a 404 or a noindex page breaks the reciprocal rule, and Google can ignore the whole group.

So I only list locales that actually exist and are indexable:

export function buildAlternatesForLocales(
  locale: string,
  path: string,
  availableLocales: readonly string[],
) {
  const languages: Record<string, string> = {};
  for (const l of availableLocales) {
    languages[l] =
      l === routing.defaultLocale
        ? `${SITE_URL}${path}`
        : `${SITE_URL}/${l}${path}`;
  }
  if (availableLocales.includes(routing.defaultLocale)) {
    languages["x-default"] = `${SITE_URL}${path}`;
  }
  return { canonical: canonicalUrl(locale, path), languages };
}

Lesson 3: Pick one canonical host and enforce it

example.com, www.example.com, and example.com/en/ can all serve the same page. I standardized on one host and made the default locale prefix-free. Everything else, including sitemaps, canonicals, hreflang and outbound links, uses that single form.

It sounds trivial, but it removed a whole class of duplicate-content problems.

Lesson 4: RSS auto-discovery is per page

Another Next.js metadata gotcha is that alternates on a page overrides the layout's alternates. If you only declare the RSS link in the layout, most pages won't expose it in <head>.

I moved RSS discovery into the same helper that builds canonicals and hreflang, so every page gets it automatically, and each language points to its own feed.

Lesson 5: Track attribution from day one

Every outbound link I post gets UTM parameters (utm_source, utm_medium, utm_campaign). Without this, you can't tell which channel brings signups or revenue. Adding it later means losing months of data.

What's next

More tools: undertone test, face shape quiz, hair color preview
Better handling of lighting differences in selfies (the hardest accuracy problem so far)
More languages

Try it and tell me what you think

Website: aicoloranalysis.io

I'd love feedback from other devs, especially on:

How you handle lighting variance in photo-based ML features
Your multilingual SEO setup in Next.js
Anything that looks broken on the site

Thanks for reading!