DEV Community: Mark

A roof calculator that multiplies length by width is lying to you

Mark — Thu, 18 Jun 2026 01:58:53 +0000

I started building a roof area calculator thinking it would be a weekend thing. You take the length, you take the width, you multiply, you show a number. Roofs are rectangles. How hard can it be.

It is not a rectangle. That was the whole project, really — slowly understanding all the ways "length times width" is wrong, and that the wrongness compounds the moment someone tries to actually buy materials with your number.

The roof you measure isn't the roof you walk on

Here's the thing that took me embarrassingly long to internalize. The footprint of a house — the shadow it casts at noon — is flat. But the roof is tilted. The shingles cover the slanted surface, not the shadow. So the area you care about is always bigger than the footprint, and how much bigger depends entirely on the slope.

Roofers express slope as "rise over run" — a 6:12 roof goes up 6 inches for every 12 inches it goes sideways. To get from footprint to actual surface area you multiply by what's called the pitch factor, which is just the hypotenuse of that little triangle divided by the run:

// rise per 12" of run -> area multiplier
const pitchFactor = Math.sqrt(144 + pitchX * pitchX) / 12;

For a 6:12 roof that's sqrt(144 + 36) / 12 ≈ 1.118. So a house with a 1,500 sq ft footprint actually has about 1,677 sq ft of roof. That's 177 square feet you'd have just... not ordered. Almost two full squares of shingles (a "square" is 100 sq ft — roofing has its own units for everything). On a steeper 12:12 roof the factor is 1.414 and you'd be short by 40%.

The naive calculator doesn't return a slightly-off answer. It returns an answer that gets someone to the supply yard one delivery short, on a Saturday, with the old roof already torn off and rain in the forecast. The error has a cost and the cost lands on a specific bad afternoon.

So the geometry is the easy part once you see it. I put all the conversions in one place so a pitch could never mean two different things in two different spots:

export function calculatePitch(riseInches: number, runInches: number) {
  const slope = riseInches / runInches;
  const angleDeg = Math.atan(slope) * (180 / Math.PI);
  const pitchPer12 = slope * 12;
  const rafterPer12 = Math.sqrt(144 + pitchPer12 * pitchPer12);
  return {
    angleDegrees: angleDeg,         // 6:12 -> 26.57°
    pitchFactor: rafterPer12 / 12,  // 6:12 -> 1.118
    // ...
  };
}

I figured that was the project. It was not the project.

Area is necessary and completely insufficient

The moment I had a correct area number, I tried to answer the question people actually have, which is "okay, what do I buy." And area gets you exactly one line of the shopping list: the field shingles.

Everything else on a roof is sold by the edge, not the surface. Walk a roof in your head:

Drip edge runs along the eaves and rakes — the bottom and the slanted sides.
Starter strip runs along those same perimeters.
Ridge cap runs along the ridges and hips — the top lines and the diagonal corners.
Ice & water shield runs in a band along the eaves and up the valleys.

None of those scale with area. A long skinny ranch house and a compact two-story can have identical square footage and wildly different amounts of edge. So a "roofing calculator" that only knows area literally cannot tell you how many boxes of drip edge to buy. It's not that it's imprecise. It's missing the input.

Which means to do the real job, you can't ask for area at all. You have to ask for the shape and derive both the area and every edge length from it. So the calculator that started as one multiplication became a little parametric model of a roof:

export function calculateRoofShape(
  shape: "gable" | "hip" | "shed",
  length: number,
  width: number,
  pitchX: number
) {
  const pf = Math.sqrt(144 + pitchX * pitchX) / 12;
  const roofArea = length * width * pf;

  if (shape === "gable") {
    return {
      roofArea,
      edges: {
        eaves: 2 * length,
        rakes: 2 * width * pf,   // rakes follow the slope, so they get the factor too
        ridges: length,
        hips: 0,
        valleys: 0,
      },
    };
  }
  // hip and shed each have their own edge geometry...
}

The detail I love in that snippet, and the one I got wrong the first time: the rakes get the pitch factor and the eaves don't. The eave runs horizontally along the bottom — it's a true plan-view length. The rake climbs the slope from eave to ridge, so its real length is the plan length stretched by the same pf. Two edges of the same triangle, one scaled and one not. Get that backwards and your drip-edge count is fine but your starter-strip count drifts, and nobody notices until they're 8 feet short on the last run.

Once the shape gives you every edge, the bill of materials falls out of dividing lengths by coverage rates:

const capBundles     = Math.ceil((ridges + hips) / 25);   // ~25 lf per bundle
const starterBundles = Math.ceil((eaves + rakes) / 100);  // ~100 lf per bundle
const dripEdgePieces = Math.ceil((eaves + rakes) / 10);   // 10 ft pieces

Math.ceil everywhere, because you can't buy 0.3 of a bundle, and rounding down is the same Saturday problem in a smaller font.

The boring decision that mattered most

There's a calculator page, and there are written guides with worked examples ("a 1,500 sq ft 6:12 roof needs..."), and there are little reference tables. Early on, the worked examples were prose. I'd typed the numbers by hand. And of course one of them disagreed with what the calculator produced for the same inputs, because I'd updated a coverage assumption in the code and not in the paragraph I'd written three weeks earlier.

That's the failure mode that actually erodes trust in a tool like this. Not being wrong — being inconsistently wrong, where the calculator says one thing and the explanation under it says another, and now the reader has no idea which to believe. For a tool whose entire pitch is "trust this number," two numbers is worse than a wrong one.

So the rule became: there is exactly one file that knows how to do roofing math, and every surface — the calculator, the worked examples, the reference tables — imports from it. If a constant changes, it changes in one place and everything downstream moves together. The published assumptions (bundle coverage, waste factor, nails per square) live next to the functions that use them, so the "how we calculate this" page can't drift from the calculation either. It's not clever. It's just refusing to keep the same fact in two places.

The takeaway, if there is one

The lesson I keep relearning on these little domain tools: the naive model isn't a simpler version of the real thing, it's a different thing that happens to return a number in the same units. "Length times width" and "the actual surface area of a tilted plane with this much edge perimeter" aren't 80% the same answer. They diverge exactly where it costs the user money.

The interesting work was never the trigonometry. It was noticing that the question "how big is my roof" is secretly the question "what do I buy," and that the second one needs you to model the shape, not just scale a rectangle.

I put the whole thing online as a set of free calculators — pitch, area, the full material takeoff — at roofing-calculator.io if you want to poke at it, and there's a methodology page that lays out every assumption so you can argue with the numbers. If you've built tools in a domain where the obvious formula turns out to be quietly lying, I'd genuinely like to hear what tipped you off.

The worked example that disagreed with its own calculator

Mark — Wed, 17 Jun 2026 01:17:24 +0000

I run a small site of home-improvement cost calculators (costto.build) — pick a project, get a low / average / high estimate with a materials-and-labor breakdown. Boring on the surface. The interesting part is that every page has the same number in four different places, and for a while, those four places didn't agree.

This is a post about that bug, why it was inevitable, and the one rule that made it impossible to repeat.

Four sources of truth for one number

A single calculator page — say, the room-addition one — shows a cost in four spots:

The interactive widget, driven by a calculate() function (low/avg/high).
A static "cost by size" reference table above the fold.
A couple of worked examples written out in prose ("a 20×20 in-law suite runs about…").
The FAQ, with its own cost bands.

When I built the first batch, I wrote all four by hand. The widget had its formula. The table had numbers I'd typed from research. The prose examples had numbers I'd reasoned out while writing the paragraph. They were close enough that nothing looked wrong.

Then I ran a consistency pass and found this: the in-law-suite worked example said $62,300. The widget, fed the exact same square footage and finish level, returned $56,779.

Same project. Two pages of the same page. A $5,500 gap.

Why it happened (and why it was always going to)

The numbers weren't random — they came from different assumptions that nobody had written down.

The prose example assumed a brand-new HVAC unit for the addition. The calculate() function assumed you extend the existing system. Both are defensible. But one lived in my head as I wrote a paragraph at 11pm, and the other lived in a TypeScript function I'd written two weeks earlier. Nothing connected them.

This is the ordinary failure mode of derived data: the moment you store the same fact in two spots, they start drifting the instant you look away. It's the DRY principle, except the duplicated thing isn't code — it's a value a function already knows how to produce. I'd just chosen to retype it.

A static table of "costs by size" is, definitionally, a table of calculate() outputs. A worked example is calculate() plus a sentence explaining it. I had been hand-copying a function's return value into prose and calling it content.

The fix: compute the page from the calculator

The rule I landed on — I call it source-first — has two halves.

Half one: calculate() is the only place a cost is born. Everything else is derived from it at build time. The reference table isn't typed; it's generated by calling calculate() across a range of sizes. Same for the example numbers.

// Before: a hand-typed table that rots independently
const costBySize = [
  { sqft: 200, low: 22000, avg: 32000, high: 48000 }, // typed from "research"
  { sqft: 400, low: 40000, avg: 58000, high: 86000 }, // ...probably
];

// After: the table IS the calculator, sampled at build time
const costBySize = [200, 300, 400, 500].map((sqft) => ({
  sqft,
  ...calculate({ sqft, finish: "mid" }), // single source of truth
}));

Static export makes this clean — it all runs once at build, ships as plain HTML, and there's no way for the table to disagree with the widget because they're the same function. (This is Next.js 16 with output: export, so the page is fully rendered text by the time Google or a user sees it. That matters more than it sounds — but that's a different post.)

The worked examples got the same treatment. Instead of writing "$62,300," the example pulls the real figure and the prose explains the assumption around it:

const inLaw = calculate({ sqft: 400, finish: "mid", hvac: "extend" });
// example text references inLaw.avg, and states the "extend existing" assumption out loud

The $62,300 figure didn't get corrected to $56,800. It stopped existing. There was no longer a number to be wrong.

Half two: every born number carries where it came from. A calculate() is only as honest as its anchor, so each calculator now ships a small provenance object that renders on the page:

costBasis: {
  scenario: "Mid-range room addition, national average",
  nationalAvg: 56800,
  source: "Industry cost data, 2026",
  accessed: "2026-06",
  reviewBy: "2026-12",
}

That reviewBy date is the part I'd push on anyone building this kind of site. Cost data isn't a fact, it's a perishable fact. Putting an expiry on it — visible to the reader, and a reminder to me — is the difference between "numbers I sourced once" and "numbers I maintain."

The counterpoint, because there is one

Generating everything from one function has a failure mode: if the anchor is wrong, it's now wrong consistently, across all four spots, very convincingly. Hand-written numbers at least disagree loudly enough to tip you off — which is exactly how I caught this bug in the first place.

So source-first only pays off if you pair it with the provenance half. The single anchor has to be sourced and dated, not vibes. Otherwise you've just made it easier to be uniformly wrong. I'd still take that trade — a contradiction a user can spot destroys trust faster than an error they can't — but it's a trade, not a free win.

There's also real content this approach can't generate: the why. A function can tell you a 400 sq ft addition averages $56,800. It can't tell you the permit will hold you up six weeks or that the HVAC decision is where people overspend. That part stays hand-written. The rule is narrow: stop hand-writing numbers a function already computes — not stop writing.

What I'd take to the next project

If two places on a page show the same number, one of them should be importing it, not retyping it. This is just DRY, but it's weirdly easy to forget that data is code.
Build-time generation (static export, or any SSG) turns "keep these in sync" from a discipline problem into an impossibility-of-drift property. Let the build do the copying.
Any number that can go stale should ship with a visible source and a review date. It costs five lines and it's the most honest thing on the page.

The whole thing was maybe a day of refactoring across the calculators on costto.build, most of it deleting numbers rather than writing them. The codebase got smaller and stopped lying about itself. That's a good day.

The third enum variant that stopped my tax calculator from lying

Mark — Tue, 16 Jun 2026 01:56:54 +0000

I built a small thing that estimates what a US pay raise actually lands in your pocket after federal tax, FICA, state tax, and inflation. The arithmetic is the boring part. The part that took three rewrites was deciding how to represent fifty states plus DC when you don't actually have clean data for all of them on day one.

This is a writeup of that one decision, because it generalizes well beyond taxes.

The problem isn't the math, it's the gaps

Federal brackets are easy. There's one set of numbers, the IRS publishes them, and progressive tax is a five-line loop:

function taxFromBrackets(taxable: number, brackets: Bracket[]): number {
  if (taxable <= 0) return 0;
  let tax = 0;
  let prevCap = 0;
  for (const { upTo, rate } of brackets) {
    const band = Math.min(taxable, upTo) - prevCap;
    if (band <= 0) break;
    tax += band * rate;
    prevCap = upTo;
  }
  return tax;
}

State tax is the same loop with different numbers. The trouble is that "different numbers" hides a lot. Nine states don't tax wage income at all. A couple (New Hampshire, Tennessee) don't tax wages but have historically taxed other things, so you can't just lump them with Texas without a footnote. Some states publish 2026 figures early; others inflation-index their brackets and won't publish the new thresholds until mid-year. And when I started, I had verified numbers for about ten states and unverified-but-plausible numbers for the rest.

That last category is the dangerous one. The easy move is to ship the plausible numbers and fix them later. The problem is that a wrong tax estimate doesn't look wrong. It looks like a number. Someone in Oregon types in their salary, sees a confident dollar figure, and has no way to know it was a placeholder I never got around to checking.

Two variants felt like enough. It wasn't.

My first model was the obvious one:

type StateTax =
  | { kind: "none"; code: string; name: string; note: string }
  | { kind: "taxed"; code: string; name: string; brackets: ...; standardDeduction: ... };

This is clean and it compiles and it's a lie. It forces every state to be either "no tax" or "here are the exact brackets," which means the moment I add a state to the union, I'm implicitly claiming I've verified it. There's no way for the type to say this state taxes income, but I haven't confirmed the numbers yet. So either I block the entire feature until all 51 are done, or I quietly promote guesses to facts.

The fix was a third variant whose only job is to represent honesty about the gap:

/** Taxing state not yet data-verified — selectable, but calc returns 0 with a UI caveat. */
type PendingState = { kind: "pending"; code: string; name: string };

type StateTax = NoneState | PendingState | TaxedState;

pending means: yes, this state taxes wages, no, I will not pretend to know how much. The calculator returns 0 for it, and the UI renders a visible caveat instead of a clean dollar amount. It's selectable so the dropdown still lists every state, but it can't masquerade as a verified result.

The calculation function gets to stay honest because the type makes the gap unrepresentable as a real value:

function calcStateTax(gross: number, status: FilingStatus, code: string | null): number {
  if (gross <= 0 || !code) return 0;
  const st = STATES_2026[code];
  if (!st || st.kind !== "taxed") return 0; // none AND pending both fall through here
  const taxable = Math.max(0, gross - st.standardDeduction[status]);
  return taxFromBrackets(taxable, st.brackets[status]);
}

The single line st.kind !== "taxed" is the whole point. There is exactly one branch that produces a state-tax number, and it's only reachable when the data has been verified. A pending state and a no-tax state both return 0, but they mean completely different things, and the UI is allowed to treat them differently because the variant carries that distinction.

"Verified" needed a definition I could check later

Once pending existed, I had to define what it took for a state to leave pending. Hand-wavy "I looked it up" doesn't survive contact with a tax year that changes under you. So every taxed state carries its own provenance:

type TaxedState = {
  kind: "taxed";
  brackets: Record<Filing, Bracket[]>;
  standardDeduction: Record<Filing, number>;
  provenance: Provenance; // where each number came from + a dated note
};

The rule I held myself to: a state's numbers only graduate to taxed when they're cross-checked against two independent sources — the state's own Department of Revenue, and an outside table (I used the Tax Foundation's bracket data). Both agree, or it stays pending. The provenance.note records the date and any caveat, like "state inflation-indexes brackets and hasn't published 2026 thresholds, so rates are exact and thresholds are the latest complete schedule."

That sounds like bureaucracy for a side project. But it's the difference between a number I can defend and a number I'm hoping is right. Six months from now when a state changes its top rate, the provenance tells me which states to recheck instead of re-auditing all of them.

The inflation formula people get wrong

Separate gotcha, same theme of "the obvious version is subtly false." A "real" raise — what your raise is worth after inflation eats some of it — is not nominal minus inflation. A 5% raise in 4% inflation is not a 1% real raise.

It's multiplicative, because you're dividing two ratios of purchasing power:

function calcRealRaise(nominalPct: number, inflationPct: number): number {
  const n = nominalPct / 100;
  const i = inflationPct / 100;
  return ((1 + n) / (1 + i) - 1) * 100; // ≈ 0.96%, not 1%
}

The gap is small at low inflation and embarrassing at high inflation. Subtraction says a 10% raise in 9% inflation keeps 1% of growth; the real figure is about 0.92%. At the inflation levels of the last few years that error is big enough to flip "you beat inflation" into "you didn't." I shipped the subtraction version first. A spreadsheet caught me.

What I'd take to the next project

The reusable lesson has nothing to do with taxes:

Model the absence of data as a first-class state, not a falsy placeholder. 0, null, and undefined all collapse "no value" and "value I haven't verified" into the same shape. A named variant keeps them apart and lets the UI tell the user which one they're looking at.
If a number is going to be presented as authoritative, make "unverified" unrepresentable as that number. The type system can enforce that the only code path producing a real figure runs on real data.
Attach provenance to data that decays. Tax tables, prices, anything time-sensitive — a dated source note turns "is this still right?" from a re-audit into a lookup.

The calculator is at raise-calculator.com if you want to poke at the output (the take-home page is where all of this surfaces). But honestly the interesting artifact was the tagged union, not the website. I've started reaching for a pending-style variant in unrelated code now — anywhere I'm tempted to ship a guess that looks like a fact.

If you've got a cleaner way to model "taxing state, unknown brackets" than a third variant, I'd genuinely like to hear it.

What I learned building an after-tax raise calculator

Mark — Mon, 15 Jun 2026 03:02:16 +0000

I built a pay raise calculator because I got a raise, multiplied my salary by 1.05, and then watched my actual paycheck go up by a lot less than I expected. The gap between "5% raise" and "the extra money that shows up" turned out to be wide enough that I wanted to understand it properly — and once I started writing the code, "what's my raise worth?" split into three completely different questions.

This is a write-up of the small TypeScript engine behind it, and the three gotchas that made the math less obvious than salary * 1.05.

Question 1: the gross number (the easy one)

This is the only part that is salary * 1.05:

const newSalary = currentSalary * (1 + raisePct / 100);

A $80,000 salary with a 5% raise is $84,000. A $4,000 raise. Done. This is the number everyone quotes, and it's the least useful one, because you never see $4,000.

Question 2: the after-tax number (where the marginal bracket bites)

The first thing people get wrong — including me, before I wrote this — is assuming a raise is taxed at your average rate. It isn't. A raise lands entirely on top of your existing income, so it's taxed at your marginal rate: the bracket your last dollar falls into.

The other thing people get wrong is the opposite, and it's a myth I wanted the tool to kill: "a raise can bump me into a higher bracket and leave me with less money." That can't happen with progressive brackets — only the dollars inside the higher band are taxed at the higher rate. The brackets are bands, not switches.

So the engine computes total tax at the old and new salary and just subtracts:

type Bracket = { upTo: number; rate: number };

function taxFromBrackets(taxable: number, brackets: Bracket[]): number {
  let tax = 0;
  let prevCap = 0;
  for (const { upTo, rate } of brackets) {
    const band = Math.min(taxable, upTo) - prevCap;
    if (band <= 0) break;
    tax += band * rate;   // only THIS band's dollars get THIS rate
    prevCap = upTo;
  }
  return tax;
}

function netRaise(currentGross: number, newGross: number): number {
  const taxBefore = totalTax(currentGross); // federal + FICA + state
  const taxAfter  = totalTax(newGross);
  return (newGross - currentGross) - (taxAfter - taxBefore);
}

The federal part is easy once you have taxFromBrackets. FICA is where the cliffs live, and it's the part most back-of-envelope calculators skip:

function calcFica(gross: number): number {
  // Social Security: 6.2%, but ONLY up to the annual wage base.
  const ss = Math.min(gross, SS_WAGE_BASE) * 0.062;

  // Medicare: 1.45% on everything...
  let medicare = gross * 0.0145;
  // ...plus a 0.9% surtax on dollars above a high threshold.
  if (gross > ADDITIONAL_MEDICARE_THRESHOLD) {
    medicare += (gross - ADDITIONAL_MEDICARE_THRESHOLD) * 0.009;
  }
  return ss + medicare;
}

That Math.min(gross, SS_WAGE_BASE) is the interesting line. Social Security stops being withheld once you cross the wage base for the year — so the same 5% raise keeps a wildly different fraction of itself depending on where you sit relative to that cap. A raise that straddles the wage base is partly free of the 6.2%; a raise entirely below it isn't. A flat "multiply by 0.92 for taxes" can't express that.

Worked example, $80,000 → $84,000, single filer, no state tax:

	Amount
Gross raise	$4,000
Extra federal tax (22% marginal band)	−$880
Extra FICA (6.2% + 1.45%)	−$306
Net raise	$2,814

You keep about 70% of it. The headline "$4,000" was never going to hit your account. And note the federal hit is 22% even though this person's effective federal rate is around 11% — that's the marginal-vs-average gap in one number.

Question 3: the real number (inflation eats the rest)

Here's the question that actually matters and almost no calculator answers: did your purchasing power go up?

If prices rose 3.3% over the year and your raise was 5%, you are not 5% richer and you're not even 1.7% richer (the naive subtraction). The correct relationship is multiplicative, because you're deflating next year's dollars back to today's:

function realRaise(nominalPct: number, inflationPct: number): number {
  const n = nominalPct / 100;
  const i = inflationPct / 100;
  return ((1 + n) / (1 + i) - 1) * 100;
}

realRaise(5, 3.3); // → 1.645...  not 1.7

So the $4,000-that's-really-$2,814 raise is, in purchasing-power terms, about a 1.6% real raise. And the uncomfortable corollary the tool makes very visible: any nominal raise below the inflation rate is a real pay cut, even though the number on the letter is positive. A "3% raise" in a 3.3% year means you can buy less than you could last year.

The architecture decision that mattered most: one source of truth

The boring part turned out to be the most important. Early on I had tax constants and "current inflation" hardcoded into page copy — $168,600 here, "3.2%" in one blog post, "3.3%" in another. They drifted. A site whose entire pitch is accurate numbers had inconsistent numbers, which is the worst possible failure mode.

The fix was to make every displayed figure — including the ones baked into prose and reference tables — derive from a single constants module, and to compute the example tables at build time from the same engine that powers the live calculator:

// data/tax-2026.ts — the only place a tax/inflation number is written down,
// each one cross-checked against two independent sources before it lands.
export const CPI_U_LATEST = { rate: 0.033, periodLabel: "12 months ending March 2026" };
export const SS_WAGE_BASE = 184_500;
// ...brackets, deductions, FICA rates...

Now a reference table like "what a 3% / 5% / 7% raise nets at $60k / $80k / $100k" isn't typed out by hand — it's a .map() over the same calcRaiseAfterTax the interactive tool calls. The numbers in the article body cannot disagree with the calculator, because they're the same function. Updating for next tax year is a one-line edit to the constants, and the whole site re-derives. (It's a Next.js static export, so all of this runs at build time and ships as plain HTML.)

If I'd known one thing starting out, it's this: for any "calculator" content site, the moment a number exists in two places it's already wrong. Treat the constants as code, compute the prose from them, and never let a human re-type a figure that a function can produce.

Takeaways

A raise is taxed at your marginal rate, not your average — but progressive brackets mean a raise can never lower your take-home.
FICA wage-base and surtax thresholds create cliffs that flat "multiply by 0.9" estimates silently miss.
Real (inflation-adjusted) raise is (1+n)/(1+i) − 1, not n − i, and it's the only one of the three numbers that tells you whether you're actually better off.
Derive every displayed figure from one constants module. If a number lives in two files, you have a bug waiting to surface.

The live version with the interactive math is at raise-calculator.com if you want to plug in your own numbers — but honestly the three formulas above are the whole thing. Happy to talk through the bracket edge cases in the comments.

Generating valid .ics calendar feeds at build time

Mark — Sun, 14 Jun 2026 03:45:33 +0000

A few weeks ago I shipped a feature I'd been putting off because it felt like it needed a backend: subscribable calendar feeds. "Add this holiday to Google Calendar." "Subscribe to all your country's public holidays so they show up in Apple Calendar forever."

Every calendar competitor has this. My site had none. The catch: the whole thing is a static export — next build produces a folder of HTML/CSS/JS that I drop on Cloudflare Pages. No server, no API routes at request time, no ISR. So how do you serve a .ics feed that a calendar app polls every few hours?

Turns out you don't need a server at all. Here's the approach, the RFC 5545 gotchas that bit me, and the parts I'd tell my past self.

The "aha": a feed is just a file

A .ics subscription feed is not a live API. It's a static text file that calendar clients re-fetch on a schedule. So for a static site, the idiomatic move is a post-build emitter: after next build, run a Node script that walks your data and writes assets straight into out/.

# scripts/deploy.sh
npx next build
node scripts/emit-feeds.mjs   # writes .ics + .json into out/

That's the entire architecture. The emitter reads the same JSON the pages render from, so the feeds can never drift out of sync with the site — there's one source of truth. It emits:

a per-year feed (holidays-de-2026.ics)
a per-holiday feed (one event, for the "download this day" button)
an all-years subscription feed (the one you point webcal:// at)
and, almost for free in the same loop, a JSON API under out/api/

No new pages, no new routes. Just files.

RFC 5545: all-day events are sneakier than they look

I assumed an all-day event on Jan 1 would be DTSTART:20260101, DTEND:20260101. Wrong. DTEND is exclusive. A one-day all-day event ends on Jan 2:

BEGIN:VEVENT
UID:de-2026-neujahr@calendana.com
DTSTAMP:20260614T101500Z
DTSTART;VALUE=DATE:20260101
DTEND;VALUE=DATE:20260102
SUMMARY:Neujahr
TRANSP:TRANSPARENT
CATEGORIES:Holiday
END:VEVENT

Get this wrong and some clients render a zero-length event, or silently drop it. Other things the spec is quietly strict about, all of which I learned by importing broken files into Apple Calendar and watching nothing appear:

CRLF line endings. Not \n. \r\n, everywhere.
75-octet line folding. Lines longer than 75 bytes (not chars — bytes) must be folded, with continuation lines starting with a single space. The byte distinction matters the moment you have non-ASCII content; you must never split a multi-byte UTF-8 codepoint across the fold.
TEXT escaping. Commas, semicolons, backslashes and newlines in SUMMARY/DESCRIPTION have to be escaped (\, \; \\ \n).
A stable UID. If the UID changes between rebuilds, every subscriber gets duplicate events on the next poll. Mine is deterministic: {locale}-{year}-{key}@domain.

The folding function is the bit worth copying, because the byte-vs-char trap is easy to miss:

function foldLine(line) {
  const bytes = new TextEncoder().encode(line);
  if (bytes.length <= 75) return line;
  const dec = new TextDecoder();
  const out = [];
  let start = 0;
  let limit = 75;
  while (start < bytes.length) {
    let end = Math.min(start + limit, bytes.length);
    // back off if the cut lands mid-codepoint (UTF-8 continuation = 10xxxxxx)
    while (end < bytes.length && (bytes[end] & 0xc0) === 0x80) end--;
    out.push((start === 0 ? "" : " ") + dec.decode(bytes.slice(start, end)));
    start = end;
    limit = 74; // continuation lines spend 1 octet on the leading space
  }
  return out.join("\r\n");
}

The zero-infra trick: deeplinks

The .ics files cover "download" and "subscribe." But the highest-intent button — "Add to Google Calendar" — needs no file at all. Google and Outlook both accept a URL that pre-fills a new event:

function googleHref({ name, date }) {
  const compact = (iso) => iso.replace(/-/g, "");
  const next = nextDay(date); // remember: end is exclusive
  const p = new URLSearchParams({
    action: "TEMPLATE",
    text: name,
    dates: `${compact(date)}/${compact(next)}`,
  });
  return `https://calendar.google.com/calendar/render?${p}`;
}

One <a href>. No JS, no library, works on a static page. (Outlook's equivalent is outlook.live.com/calendar/0/deeplink/compose — note the deeplink segment; I shipped it once without it and the prefill silently failed.)

Serving the right MIME type on a static host

If you serve .ics as text/plain, some clients refuse it. On Cloudflare Pages a single _headers file in public/ handles it:

/*.ics
  Content-Type: text/calendar; charset=utf-8
  Cache-Control: public, max-age=86400
/api/*
  Content-Type: application/json; charset=utf-8
  Access-Control-Allow-Origin: *

The part that's actually hard: 15 languages

This is the bit I keep coming back to. The site runs in 15 locales, and the temptation with any multilingual feature is to write the English microcopy once and machine-translate it ×15. Don't. For a content/SEO site that's a fast track to thin, near-duplicate pages that search engines won't index — and for a calendar, it's also just wrong. A Mexican user wants "Agregar a Google Calendar" for "días festivos"; a Spaniard wants "Añadir" for "festivos"; an Argentine says "feriados." Same language, three different words. Those got hand-written per locale, sharing one strings file that both the Node emitter and the React components read, so the button label and the feed's calendar name always agree.

That single-source-of-everything theme — one holiday JSON feeding the pages, the feeds, and the API; one strings file feeding the emitter and the UI — is what kept this feature from becoming a maintenance swamp.

Where it lives

The site is Calendana — printable calendars plus public-holiday and school-holiday data for a bunch of countries, all static, all free, ad-supported, no login. The calendar-export work is live on every holiday page now. If you just want to see the feed format, grab one and open it:

https://calendana.com/de/holidays/2026/holidays-de-2026.ics

or the JSON, if you're building something:

https://calendana.com/api/holidays/de/2026.json

Takeaways

"Needs a backend" is often a reflex, not a requirement. A subscription feed is a file. A "create event" button is a URL. Both fit a static site fine.
Read the RFC. All-day DTEND is exclusive, lines fold on bytes, endings are CRLF. The spec is boring and it is right.
Generate sibling artifacts from one source. Pages, .ics, and JSON all come from the same data in one build step, so they can't disagree.
Localize the words, not just the dates. Especially when "the same language" means different words in different countries.

Happy to answer questions on the emitter or the folding/escaping details in the comments — that's where most of the sharp edges were.

Encoding FIFA’s 495 third-place scenarios for the 2026 World Cup

Mark — Wed, 27 May 2026 08:04:24 +0000

I expected the 2026 World Cup bracket to be a sorting problem.

It turned out to be a sorting problem plus a lookup table.

I recently worked on a small World Cup 2026 bracket project, and the strangest part was not building the knockout bracket itself. It was handling the third-placed teams.

The new format has:

48 teams
12 groups
24 teams qualifying as group winners and runners-up
8 more teams qualifying as the best third-placed teams
a new Round of 32

At first, this sounded straightforward.

Rank the third-placed teams, take the best 8, then put them into the knockout bracket.

But the last step is where it gets weird.

Ranking third-placed teams is the easy part

Once every group has a table, each group gives you one third-placed team.

That gives you 12 third-placed teams.

From there, the basic ranking can be represented as a normal sorting problem:

type GroupId =
  | "A" | "B" | "C" | "D"
  | "E" | "F" | "G" | "H"
  | "I" | "J" | "K" | "L";

type TeamStanding = {
  teamId: string;
  group: GroupId;
  position: number;
  points: number;
  goalDifference: number;
  goalsFor: number;
  fairPlayPoints: number;
};

A simplified ranking function might look like this:

function rankThirdPlacedTeams(teams: TeamStanding[]) {
  return [...teams].sort((a, b) =>
    b.points - a.points ||
    b.goalDifference - a.goalDifference ||
    b.goalsFor - a.goalsFor ||
    a.fairPlayPoints - b.fairPlayPoints
  );
}

This is not the complete official tie-breaker system, but it shows the shape of the problem.

You filter the third-placed teams:

const thirdPlacedTeams = groupTables
  .map(group => group.standings.find(team => team.position === 3))
  .filter(Boolean);

Then you take the top 8:

const qualifiedThirds = rankThirdPlacedTeams(thirdPlacedTeams).slice(0, 8);

So far, this still feels like a normal algorithm problem.

But then comes the awkward part.

The bracket position is not simply “best third-place team goes here”

My first assumption was that the best third-placed team would go into one slot, the second-best into another slot, and so on.

That is not how it works.

The Round of 32 matchup depends on which groups the qualifying third-placed teams came from.

For example, if the qualifying third-placed teams come from groups:

["C", "D", "E", "F", "G", "I", "K", "L"]

that combination maps to one specific set of Round of 32 positions.

If the qualifying groups are:

["B", "D", "E", "F", "G", "I", "K", "L"]

that maps differently.

So the key is not only ranking the third-placed teams.

The key is identifying the set of groups they came from.

With 12 groups and 8 third-placed teams qualifying, the number of possible group combinations is:

C(12, 8) = 495

That means there are 495 possible sets of qualifying third-placed groups.

This is where the implementation stops being a clean formula and becomes a data problem.

Turning the qualified groups into a key

The simplest way I found to model this was to turn the list of qualifying third-place groups into a stable key.

function getThirdPlaceCombinationKey(teams: TeamStanding[]) {
  return teams
    .map(team => team.group)
    .sort()
    .join("");
}

So if the qualified third-placed teams came from groups C, D, E, F, G, I, K, and L, the key becomes:

"CDEFGIKL"

This key can then be used to look up the official mapping for the Round of 32.

const qualifiedThirds = rankThirdPlacedTeams(thirdPlacedTeams).slice(0, 8);

const combinationKey = getThirdPlaceCombinationKey(qualifiedThirds);

Now we can use that key to answer the real question:

Where does each third-placed team go in the bracket?

Representing the mapping as data

Instead of trying to derive the Round of 32 slots every time, I treated the official scenarios as a lookup table.

A simplified version looks like this:

type RoundOf32Slot =
  | "1A" | "1B" | "1D" | "1E"
  | "1G" | "1I" | "1K" | "1L";

type ThirdPlaceSource = `3${GroupId}`;

type ThirdPlaceMapping = Record<RoundOf32Slot, ThirdPlaceSource>;

const thirdPlaceSlotMap: Record<string, ThirdPlaceMapping> = {
  CDEFGIKL: {
    "1A": "3E",
    "1B": "3G",
    "1D": "3I",
    "1E": "3D",
    "1G": "3F",
    "1I": "3C",
    "1K": "3L",
    "1L": "3K",
  },

  BDEFGIKL: {
    "1A": "3E",
    "1B": "3G",
    "1D": "3I",
    "1E": "3D",
    "1G": "3F",
    "1I": "3B",
    "1K": "3L",
    "1L": "3K",
  },

  // ...493 more combinations
};

The exact values need to come from the official table, but the structure is the important part.

The code is not trying to be clever.

It is just making the official tournament rules usable inside an app.

Filling the actual teams into the bracket

Once the mapping is known, the rest is more mechanical.

For each Round of 32 slot, find the third-placed team from the mapped group.

function getThirdPlacedTeamFromGroup(
  qualifiedThirds: TeamStanding[],
  source: ThirdPlaceSource
) {
  const group = source.replace("3", "") as GroupId;

  return qualifiedThirds.find(team => team.group === group);
}

Then apply the mapping:

function resolveThirdPlaceSlots(
  qualifiedThirds: TeamStanding[],
  mapping: ThirdPlaceMapping
) {
  return Object.entries(mapping).map(([slot, source]) => {
    return {
      slot,
      source,
      team: getThirdPlacedTeamFromGroup(qualifiedThirds, source),
    };
  });
}

And the full flow becomes:

const qualifiedThirds = rankThirdPlacedTeams(thirdPlacedTeams).slice(0, 8);

const combinationKey = getThirdPlaceCombinationKey(qualifiedThirds);

const mapping = thirdPlaceSlotMap[combinationKey];

const resolvedSlots = resolveThirdPlaceSlots(qualifiedThirds, mapping);

At this point, the app can place the correct third-placed teams into the Round of 32.

What made this interesting

I usually prefer deriving things from rules instead of hardcoding large tables.

But this was a case where the table itself is part of the rule.

The bracket is not just:

sort teams → seed teams → generate matches

It is closer to:

sort teams → identify qualified groups → use official mapping → generate matches

That small difference changes the architecture.

The app needs both:

normal ranking logic
a predefined scenario table

That is what made this more interesting than a standard tournament bracket.

Why I did not want to hide all of this

From the user’s point of view, none of this should feel complicated.

They should be able to fill out groups, move into the knockout rounds, and understand what happened.

But from the developer’s point of view, the Round of 32 is doing quite a lot behind the scenes.

That also creates a UX question:

How much of this logic should be visible?

If you expose every rule, the page starts to feel like documentation.

If you hide everything, the bracket can feel random.

That balance was one of the harder parts of the project.

The working version

I used this logic in a small bracket predictor here:

https://bracket2026.com

The main goal was to make the new 48-team format easier to play with, especially the Round of 32.

Building it reminded me that some “simple” sports tools are not simple because the UI is complex.

They are complex because the real-world rules are strange.

And sometimes the cleanest code is not the cleverest algorithm.

Sometimes it is a boring lookup table that faithfully represents the rules.

References

Building a shift schedule generator taught me that scheduling is harder than it looks

Mark — Sat, 09 May 2026 14:15:20 +0000

I recently built a small tool called Shift Schedule Maker.

At first, I thought shift scheduling would be a fairly straightforward problem.

You have employees.
You have shifts.
You assign people to shifts.

That sounds like a simple table.

But once I started building it, I realized scheduling is less like filling out a calendar and more like solving a constraint problem.

A valid schedule is not necessarily a good schedule.

For example, the system has to think about things like:

Does every shift have enough people?
Is anyone assigned to two overlapping shifts?
Is someone working too many days in a row?
Are night shifts distributed fairly?
Are weekends always falling on the same person?
What happens when one person is unavailable?
Can the schedule still work if the team size is small?

The tricky part is that these rules often conflict with each other.

You might want perfect fairness, but still need full coverage.
You might want to respect everyone’s availability, but only have a limited number of people.
You might want a simple repeating pattern, but real-life exceptions break the pattern very quickly.

That made me think about scheduling differently.

Instead of treating it as a calendar UI problem, I started treating it as a constraint-solving problem.

Each shift becomes a slot that needs to be filled.
Each employee has limits, availability, and workload history.
Each rule adds pressure to the system.

Some rules are hard constraints:

A person cannot work two shifts at the same time.
A shift cannot be left uncovered.
An unavailable employee should not be assigned.

Other rules are softer:

Try to balance total working hours.
Try to distribute unpopular shifts.
Try to avoid too many consecutive workdays.
Try to keep the result understandable for a human manager.

That last part is easy to underestimate.

A schedule can be mathematically valid and still feel wrong.

For example, if one person gets all the night shifts, the algorithm might still satisfy coverage. But from a team perspective, the result is bad. So the goal is not just “generate something that works.” The goal is to generate something that feels reasonable.

Another challenge was templates.

Many industries already use known rotation patterns, like 12-hour shifts, 4-on/2-off, Pitman-style schedules, or 2-2-3 rotations. These patterns are useful because they give structure. But once you add employee availability or custom rules, the template becomes only the starting point.

So the product became a mix of two ideas:

Start with common scheduling patterns.
Adjust the actual result based on constraints and fairness rules.

I’m still improving the logic, especially around edge cases where the input is technically possible but very tight.

For example, if there are too few employees for too many required shifts, the system should not simply fail. It should explain what is making the schedule difficult.

That is probably the most interesting part of the project so far: not just generating the schedule, but helping people understand why a schedule is hard to generate.

I made the tool public here:

https://shiftschedulemaker.net/

It is still evolving, but building it has made me appreciate how much hidden complexity exists behind something as ordinary as a weekly shift calendar.

Curious if anyone here has worked on scheduling, constraint solving, workforce planning, or optimization problems.

How would you approach fairness in a scheduling system?

I built a World Cup 2026 bracket predictor for the new 48-team format

Mark — Thu, 07 May 2026 13:14:25 +0000

I built a World Cup 2026 bracket predictor for the new 48-team format

The 2026 FIFA World Cup format is surprisingly complicated.

Instead of the old 32-team structure, the tournament now has:

48 teams
12 groups
a new Round of 32
third-place qualification rules

I realized that most existing bracket tools were still based on the old format and felt awkward once you tried modeling the new tournament structure.

So I built this:

https://bracket2026.com

The idea was simple:

predict all group-stage standings
automatically generate the Round of 32
continue predicting all knockout rounds
share or export the completed bracket

One interesting challenge was handling the knockout path generation.

With 12 groups and third-place advancement, the Round of 32 is no longer fixed in a straightforward way. The bracket depends on which third-place teams qualify, so the UI and logic both become more dynamic compared to previous World Cups.

I also tried to keep the experience lightweight:

no signup
mobile friendly
fast interactions
easy sharing

It was a fun side project to build, especially because sports tournament structures are basically a weird mix of UI design, state management, and combinatorics.

Would love feedback from other developers or football fans — especially around the UX and whether the new format feels understandable.