DEV Community: Nicolas Bouvrette

The Last Capacity Planning Sheet You'll Ever Need

Nicolas Bouvrette — Sat, 06 Jun 2026 17:37:21 +0000

Originally published at theendofcoding.com.

It's the last week of the quarter. The team is going to miss two of the five committed epics — they already know it. The retro that follows will use the word "velocity" eleven times and the word "capacity" zero. The plan they committed to was a target with a spreadsheet stapled to it. The capacity model — the actual arithmetic of who would be available for how many days, doing what kind of work — never existed.

Frederick Brooks wrote the line that explains why, fifty years ago, in a chapter that has aged better than most:

"How does a project get to be a year late? … One day at a time."

— Frederick P. Brooks, Jr., The Mythical Man-Month (1975) (source)

Quarters get late the same way. A holiday gets missed in the math. Two devs become one when the senior gets pulled into a hiring loop. Support load eats six weeks nobody planned for. By the time you're building the plan for the next quarter, the previous one's arithmetic is so quietly wrong that you stop trusting arithmetic at all — and switch to story points, velocity, and the reassuring vagueness of relative sizing.

This article is about what to do instead. The argument is that capacity planning, done in real units with a real allocation split, on a single sheet, is the last honest conversation left in the quarter — and most teams don't have it. The ones that do, ship.

At the end of the article: a public, read-only Google Sheet you can copy into your own Drive, fill in, and use this Friday. Free. Argument first; link last; the agreement the model requires in between.

The argument in 6 steps

Capacity planning was invented to be honest. Software made it dishonest.
Yes, one framework formally plans capacity in points. It does not work.
The unit you plan in is the truth you will or will not face.
Most capacity plans miss the same six things.
The allocation split is where the actual fight is.
AI didn't change the model. It made the model matter more.

Capacity planning was invented to be honest. Software made it dishonest.

Capacity planning is older than software by half a century. Henry Gantt designed his eponymous chart for the U.S. Army Ordnance Department during the First World War, and the version that ended up coordinating shipbuilding and munitions logistics had a property modern Gantt charts have lost: every bar represented a person's available hours, and the bar was either filled with work or it wasn't. The point of the chart was that you could not pretend a person had eighty hours of capacity in a forty-hour week. The unit was real. The math forced reality on the conversation.

Software adopted the form and dropped the unit. We kept the bar charts and the swim lanes, then replaced "hours" with "story points" — an abstract sizing scale that began life in late-1990s Extreme Programming as a renaming of "ideal days." Ron Jeffries, widely credited with the invention, later wrote that the rename was a response to stakeholder confusion: "the result was that our stakeholders were often confused by how it could keep taking three days to get a day's work done." Allen Holub, writing from the longer-running #NoEstimates tradition, reads the same move less charitably:

"Story Points were invented to obfuscate duration so that certain managers would not pressure the team over estimates."

— Allen Holub, #NoEstimates, An Introduction (source)

Both readings can coexist. Whatever the original intent, the effect was the same: by the early 2000s, "story points" had become a planning currency that nobody could convert back into anything physical even when they wanted to. You cannot subtract a holiday from a story point. You cannot add up nine team members' story points and get a meaningful total because their points don't mean the same thing. (For the deeper case on why story points were never part of Scrum and what the original Scrum Guide actually mandates, see Your Scrum Isn't Scrum.)

Jeffries himself, in his 2019 piece Story Points Revisited, publicly walked back the practice his own term enabled — "I like to say that I may have invented story points, and if I did, I'm sorry now." Holub goes further in the same #NoEstimates piece: "Point values are irrelevant," he argues, with the right response being throughput measurement of completed work rather than relative sizing of work that has not yet started.

Yes, one framework formally plans capacity in points. It does not work.

The honest answer to "does anyone actually plan capacity in story points?" is: outside of one framework, almost no one. Inside that framework — the Scaled Agile Framework, better known as SAFe — it is mandated. SAFe's PI Planning event prescribes "Team PI Capacity," computed in normalized story points via the canonical rule of eight points per full-time developer per iteration, summed into a Program Increment of typically eight to twelve weeks. This is the only place I am aware of where capacity planning in story points exists as a documented, named, official practice.

It does not work, and the documentation of why does not come from outside SAFe — it comes from inside the SAFe consultancy ecosystem itself. The Wibas analysis of the canonical PI Planning capacity slide, written by SAFe-certified coaches, is direct about the failure mode:

"This is an important but also tricky slide that leads many people to misunderstand estimation in SAFe. … It would be a big mistake to calculate Capacity based on '8 points for every full-time developer' in every Iteration/Sprint."

— Wibas, A Tricky Slide About Story Points and Capacity in SAFe (source)

What the Wibas piece, the Mercedes-Benz Tech Innovation case study, and similar inside-SAFe critiques converge on is the same set of failures the rest of this article will name in any capacity model — holidays not modeled per person, support load not deducted, the "8 points per developer" formula treated as a recurring truth rather than a one-time baseline — wrapped in an additional translation layer (the "normalized" velocity) that obscures rather than reveals where the math is wrong. The unit makes the trade-offs harder to see, not easier.

Outside SAFe, in everything I have personally seen across more than a decade across multiple organizations, capacity planning in points is not a real practice. What is a real practice — pervasive, almost universal in points-using teams — is the inverse: teams that estimate in time and then launder the estimate back into points to satisfy a tooling or reporting requirement. Santiago Valdarrama named the pattern bluntly in 2024:

"Everyone I've seen—and I mean everyone—uses points as a measure of time: 1 point = 2 hours, 3 points = 1 day, 5 points = 3 days."

— Santiago Valdarrama, on the lived practice of story-point estimation (2024) (source)

The laundering is bitterly ironic given the origin story. Jeffries' original purpose for points was to encrypt time from managers; teams in 2026 spend cognitive effort decrypting time back out of points to make any planning conversation work. The result is the worst of both: the dysfunction tax of points (the rituals, the planning poker, the Fibonacci arguments, the velocity charts) without any of the originally intended benefit (genuine abstraction from time-as-contract). The unit is doing no work that hours or developer-weeks would not do better.

The fix is not to use story points more carefully or to find the right velocity-normalization formula. The fix is to plan capacity in time, at every level, and stop translating.

The unit you plan in is the truth you will or will not face.

Plan in developer-weeks. One developer, one week of pure coding time, average. Whole numbers when possible, halves when not. Treat the developer-week as the only unit that crosses the boundary between "work to be done" and "people who will do it."

Two things change when you switch.

First, the math becomes auditable. A team of six people running an eleven-week quarter has a maximum theoretical capacity of sixty-six developer-weeks. From that you subtract holidays, vacation days, on-call rotations, hiring panels, mentoring overhead, and the percentage of time each person realistically spends writing code rather than reviewing, attending meetings, or unblocking peers. The result — usually somewhere between thirty-five and forty-five percent of the theoretical maximum — is a number you can defend out loud. It survives a one-on-one with a skeptical CEO because every line beneath it is a real subtraction from a real calendar.

Second, the conversation about commitment becomes precise. "Can we fit a fifth epic?" stops being a vibe-check and becomes "Do we have eight more developer-weeks of business capacity than we've already allocated?" Either you do or you don't. If you do, name them. If you don't, name what's getting cut. The unit makes the negotiation sharper for everybody at the table — engineering and product alike — and the sharpness is the point.

The objection lands every time: but we don't know how long any given epic will take in developer-weeks. Correct. You will be wrong, often badly. You will become less wrong faster than you expect, because the unit gives you a calibration target other than a vibes-based velocity number. Three quarters of dev-week estimation produces an engineering team measurably better at it than three years of story-point velocity tracking, because the unit doesn't shift between teams or quarters or framework redesigns. It is the same unit Brooks used in 1975 and Gantt used in 1917. There is a reason it has outlived its replacements.

Most capacity plans miss the same six things.

The failure modes are unglamorous and predictable. Every team I've audited has hit at least three of them at the same time. The first one is the foundational mistake — the rule that, when broken, makes every other failure on this list inevitable:

Conflating effort with duration. The capacity sheet contains exactly one duration: the period's start and end dates. Everything else — every developer-week on every row, every estimate on every epic — is pure dev effort at one hundred percent focus. Vacations, holidays, meetings, the percentage of any given week that is genuinely available for development work: those have already been deducted on the capacity side of the math. Re-deducting them on the estimate side double-counts the deduction and produces estimates that bear no relationship to reality. The sheet's job is not to predict the date each line item ships. It is to confirm the work fits inside the period. Inside the period, the team will continue to juggle priorities, vacations, support rotations, and unplanned events — that is a runtime concern, not a planning concern. The moment the sheet starts trying to predict per-item dates, it stops being a capacity model and starts becoming a Gantt chart, and you have rebuilt the heavy project management apparatus this approach was meant to replace.
Holidays modeled as a single team-level number. A team distributed across three time zones has three different holiday calendars. Treating them as a single average undercounts the absences and lands the plan in the red by week six. Model holidays per person, not per team, and let the per-person rows roll up to the team total.
New hires counted at full capacity from day one. The first month is onboarding, environment setup, codebase orientation, and the steady drip of "I just need to ask one question" interruptions to the rest of the team. Realistically, a new senior is at twenty percent the first month, fifty the second, eighty the third. Anything more optimistic is the plan lying to itself, and the lie compounds because their notional capacity is pulling roadmap commitments forward.
Tech leads counted as developers. A staff engineer or tech lead who reviews half the team's PRs and runs architecture office hours is, charitably, a thirty-percent contributor to roadmap effort. Their high-leverage work shows up as everybody else's velocity, not their own. Model their personal coding capacity at thirty percent and stop pretending — the multiplier they create across the team is real, and it doesn't need to be double-counted on their row.
No support deduction. Most teams have a steady operational load — escalations, customer-specific bugs, on-call investigations, the recurring asks that never quite become a project. If your team historically spends twenty percent of any given week on this work, twenty percent of capacity is gone before any roadmap planning starts. Deduct it explicitly. If support load consistently exceeds the deduction, that is signal — usually a product-investment signal, not a "the team should work harder" signal.
No allocation gut-check. A capacity plan that lands the math on developer-weeks but treats them as a single bucket misses the most useful question the model is built to answer: are we investing where we said we wanted to invest? Most teams want some level of technical work — refactors, tech-debt paydown, internal tooling, observability — funded each quarter, and most teams discover, when they actually run the math, that they are not. The audit ends on this question because everything else is arithmetic; this is the only step where the math meets strategic intent. The next section is about that step in full.

Each of these is arithmetic, not strategy — except the last, which is strategy hiding inside arithmetic. The reason teams miss them is that nobody is responsible for the math. The capacity model is owned by the engineering manager, validated with the team, and reviewed with product — not delegated to a tool that auto-calculates a velocity from last quarter's points and renders it as a confident green number on a dashboard.

A note on the buffer question, since it always comes up: I do not recommend adding a padding buffer to a capacity plan. Estimates already represent the midpoint between the aggressive and the conservative read of each piece of work; padding on top of that compounds the conservatism and produces plans that succeed by accomplishing less than the team could have. It is materially better to fail a plan estimated honestly than to succeed a plan that was over-padded. A plan that lands above one hundred percent of capacity is allowed — provided the over-commit is visible on the summary row and the success rate is understood to be lower. Capacity planning is a forecast, not a contract. The goal is predictability, not invulnerability.

The allocation split is where the actual fight is.

Most teams that survive the unit problem still misplan the quarter, because they treat capacity as a single bucket. It isn't. The single most useful thing a capacity model can make explicit is what kind of work the capacity is funding.

Three categories cover most of it:

Feature work — the user-facing work the product or commercial side of the company is asking for.
Technical work — refactors, tech-debt paydown, platform investment, internal tooling, the tests and observability the team will regret not having.
Support — escalations, ops work, recurring customer-specific work, the unplanned tax on every quarter.

The fight is over the split, and the fight is healthy. Engineering will argue for more technical work; product will argue for more feature work; support load is whatever it actually is, and pretending otherwise is what got the team here. The point of the sheet is not to dictate the split. The point is to make the split visible so the conversation is about the percentages instead of the individual line items.

A team I worked with had been running, for over a year, at roughly seventy percent feature work and ten percent technical work. Nobody had decided that. It had emerged, the way most allocation does — through the path of least leadership resistance. The capacity sheet, when we finally built it, made the proportion legible for the first time, and the leadership conversation that followed was the first one in eighteen months that actually engaged with allocation. It set a target of sixty / twenty-five / fifteen across feature, technical, and support, and moved the team measurably toward it the next quarter. The numbers themselves are not what mattered. The visibility was the unlock.

If you do not define an allocation target, you cannot later evaluate whether you respected it. If you consistently underinvest in technical work — and most teams do — you are accumulating structural debt whether you've named the trade or not. The same is true in the other direction: a team that lands one hundred percent technical work for two quarters running has misread the strategic moment, and the sheet will tell you that just as readily as it will tell you the inverse.

AI didn't change the model. It made the model matter more.

When AI compresses execution, the constraint moves. Writing the code stops being the bottleneck. What gets written, in what order, against what trade-offs — the planning layer — becomes the constraint instead. Bad allocation in an AI-multiplied org isn't a small drag, the way it was in the pre-AI world. It is the dominant drag, because the multiplier is now applied to the wrong work faster than ever.

This is the version of capacity planning that survives the shift: a plan that knows the unit, knows the allocation, and is honest about both.

The sheet doesn't change shape because of AI. The thing that changes is what's on the right-hand side of the table. AI absorbs more of the operational tax — recurring report generation, customer-specific configuration work, repeat escalations — and frees real capacity. That reclaimed capacity has to land somewhere on the allocation split, and most teams discover, when they actually measure it, that the savings get silently consumed by more feature work rather than the technical investment that created the leverage in the first place. Without the sheet, that consumption is invisible. With the sheet, it is a line you can defend or a line you can change. Both options beat the alternative of pretending the capacity reclaim happened uniformly across categories, because it never does.

There is a second AI shift that matters for capacity planning specifically: estimating itself has gotten faster. The historical pain of capacity planning was that the estimate column required real engineering attention — reading code, modeling integrations, sketching solutions — for every line on the roadmap, including the ones that would never get prioritized. AI removes most of that cost. A senior engineer with a current AI loadout can produce a credible developer-week estimate on an unfamiliar epic in minutes rather than hours, and a directional one in seconds. Use that.

The corollary matters more than it sounds: match estimation depth to prioritization confidence. A line item that has not been triaged through intake yet does not need a forty-five-minute estimation conversation. A directional pass — small / medium / large in developer-weeks, produced cheaply with AI assistance — is enough to support the prioritization decision. Tighter estimates earn their cost only after the work has cleared the bar to enter capacity planning. Estimating everything to the same precision is a habit from when estimation was expensive; it now produces planning theatre.

This is also where spikes earn their place back. Some work is genuinely under-specified — research-heavy investigation, integrations into systems nobody on the team has touched, requirements that need contact with reality before they can be sized. The right answer is not to estimate harder. The right answer is to fund a small exploration window — a spike — out of capacity, take its findings into the next planning conversation, and re-estimate with the new information. Spikes used to be expensive enough that teams skipped them and ate the estimation error downstream. AI compresses spike cost the same way it compresses estimation cost, which means the right-shaped capacity plan now has more spikes in it, not fewer.

The sheet

Why a spreadsheet, of all things? Because the single most important property of a capacity plan is that the numbers balance — and balancing numbers is the one thing spreadsheets exist to do. The team total ties to the per-person rows, the planned-effort total ties to the epic list, every edit propagates instantly. Slides, decks, and Notion pages cannot do that, no matter how nicely they present the result.

Most teams will not enjoy being presented a spreadsheet at a leadership review, and that is fine — build whatever presentation layer your audience needs on top of it. Just minimize the copy-paste between source and presentation, because plans move often and any part of the plan that lives outside the spreadsheet will be stale by the second week. Find the recipe that works for your org. The presentation is negotiable. The math has to balance.

Get the free Capacity Planning Sheet template →

The structure is intentionally simple — six sections on a single tab, in this order:

Period. Start date, end date, number of weeks computed.
Team. One row per person — name, location, role, coding-time %, time off, holidays — with calculated developer-week capacity per person rolled up into a team total.
Support allocation. A single percentage deducted from team capacity to reflect the steady operational load before any roadmap work gets funded. Set it from historical data, not optimism.
Planned Work. One row per epic — name, type (Feature work / Technical work), effort in developer-weeks, an Included toggle (Yes / No), and notes. Order by priority — when the math forces a cut, you start from the bottom. The toggle records the cut without deleting the row, so the line stays visible when leadership asks "what got dropped?". A ranked list beats heavier prioritization frameworks like MoSCoW here: once the rows are sorted, the labels add vocabulary without adding signal.
Capacity Allocation by Type. Roll-up of effort across Feature / Technical / Support / Unallocated, with a pie chart for at-a-glance visibility. This is where "are we investing where we said we wanted to invest?" gets answered without needing a separate review meeting.
Capacity Summary. Total capacity, total planned effort, remaining capacity, capacity used %. The decision surface — not a recommendation to pad.

Copy it, replace the example data with your team's, and run a planning conversation against it tomorrow. Resist the urge to add tabs — the point of one sheet is that the whole quarter fits on one screen and the trade-offs cannot hide behind a tab nobody clicks.

If you want the deeper case for why the model is shaped this way — and the rest of the operating model that surrounds it: intake discipline, a planning cadence, a continuous learning loop on estimation accuracy — that's a longer argument than one spreadsheet can hold. The sheet is the part you can adopt tomorrow, on its own, without waiting for the rest.

The agreement this approach requires

The sheet only works if a few preconditions hold. None of them are technical:

The engineering manager owns the math. Not the tool, not the PMO. The EM builds the capacity model, defends the numbers in the room where commitments are made, and updates them when reality moves. Numerical correctness is non-delegable — the math is wrong or right, not negotiated. Allocation is the next bullet, and a different question entirely.
Allocation is a collaboration that evolves. The feature / technical / support split is built jointly between the EM and the product manager, shaped by leadership and stakeholder feedback, and revisited mid-period when reality moves — which it does, often. The sheet keeps the conversation honest as the plan iterates; it does not pre-decide the answer. When the same imbalance shows up period after period — support load consistently exceeding budget, technical work consistently slipping below target — read it as a structural signal worth raising at the next planning cycle, not a one-period anomaly.
Product accepts the unit. Capacity is in developer-weeks; commitments will be expressed in developer-weeks; can we fit it? gets answered in developer-weeks. Translating in or out of story points to satisfy a parallel reporting workflow is the dysfunction this model is replacing, not a parallel track to keep running alongside it.
Everyone treats the plan as a forecast, not a contract. No estimation is failproof, and the sheet does not pretend otherwise. The point is to predict what the next period will most likely deliver — and to be more predictable over time, not perfect any single quarter. A team that lands above one hundred percent capacity with that over-commit clearly visible is doing capacity planning correctly. A team that sandbags below capacity to guarantee a green dashboard is not.

Without those, no spreadsheet survives contact with the politics. With them, this one is enough.

Close

Capacity planning is not the most exciting part of running an engineering team. Quietly, it is the part that decides whether anything else you do this quarter actually ships. Plan in real units. Make the allocation visible. Cap the buffer at the start, not the end. Then the rest of your work — the architecture choices, the AI leverage, the team rituals — gets to operate against a true picture of what's possible, instead of a fictional one held together by a velocity number nobody owns.

The sheet is here. Take it. Make it yours. And the next time someone asks "can we fit one more?" — you'll have an answer that survives the quarter, not a hope dressed up as a plan.

Your Scrum Isn't Scrum. The Scrum Guide Is 13 Pages. Your Process Has 300.

Nicolas Bouvrette — Sun, 10 May 2026 18:06:57 +0000

Originally published at theendofcoding.com.

The Scrum Guide is 13 pages. The terms "user story" and "epic" never appear in it. The word "velocity" appears zero times. Story points have not been mentioned since 2010. Planning poker, Fibonacci, "As a user, I want," Given/When/Then, two-week sprints — none of it is in there. What most engineering organizations call Scrum is a folk overlay assembled on top of the Guide over twenty years by books, tools, and consultants. Most of what your team fights about at sprint planning was never Scrum.

This is not a critique of Scrum. The Scrum Guide is fine. The bloat this article catalogs was added to Scrum — by mid- and large-sized enterprises that grafted on practices from books, tools, and consultants left and right until what took ten minutes to read became a process that takes three hundred pages to document. Most of it was added with good intentions. None of it was ever required.

That bloat is what compounds under AI acceleration. When execution was the bottleneck, an extra ceremony and a Fibonacci debate cost a sprint. When AI collapses the cost of writing code by an order of magnitude, the same ceremony and the same debate cost the entire week of work that used to live inside them. Process overhead that was tolerable at human-keyboard speed is now the bottleneck. The teams shipping at the speed AI actually enables are the teams that have stripped enterprise Scrum back to something close to the original 13-page document — and replaced the rest with workflows designed for the speed they work at, not the speed of fifteen years ago.

What the Scrum Guide actually contains

The Scrum Guide — written by Ken Schwaber and Jeff Sutherland, last rewritten in November 2020 — prescribes remarkably little:

Three roles (Product Owner, Scrum Master, Developers).
Five events (the Sprint itself, Sprint Planning, Daily Scrum, Sprint Review, Sprint Retrospective).
Three artifacts (Product Backlog, Sprint Backlog, Increment).
A Definition of Done.
Sprints of "one month or less."

Each rewrite has removed prescription, not added it. Everything below is folk overlay — here are the ten biggest, with what to do about each.

The 10 myths at a glance

Scrum requires user stories (and epics)
Story points are a Scrum concept
Planning poker is a Scrum ceremony
Sprints must be two weeks
Velocity is a Scrum metric
"As a user, I want…" is mandatory
Fibonacci scales are more accurate
The Sprint Retrospective must be ritualized and recurring
Backlog refinement is a required ceremony
The Daily Scrum is a status-update meeting

Myth 01 — Scrum requires user stories (and epics)

The claim. Scrum teams track work as user stories. Larger groupings are epics. That's the structure.

The Scrum Guide. Refers to "Product Backlog Items." The terms user story and epic never appear in any version of the Guide.

The origin. Both come from Extreme Programming. Kent Beck's Extreme Programming Explained (1999) used "story" for a unit of user-facing work, with "epic" as the colloquial term for a story too large to deliver in one cycle. Mike Cohn formalized both in User Stories Applied (2004) and Agile Estimating and Planning (2005). Atlassian's Jira then institutionalized the Epic → Story → Sub-task hierarchy as a product feature, and a generation of tools followed Jira's lead. None of which makes any of it Scrum.

Do this instead. The term doesn't matter — different systems use different ones (issue, ticket, work item, task) and they all work fine. What matters is the underlying concept: a unit of work, ordered in a backlog. Hierarchy is useful — group related work together so progress on a larger initiative is visible — but two levels handles most needs: a grouping concept on top, a unit of work below. Two types — feature-shaped work and pure-technical work — is usually enough. Resist the temptation to configure ten work-item types each with their own custom workflow. Simpler tools are faster, the team's mental model stays lighter, and the simplification compounds with AI: agents reasoning about your backlog work better when there are fewer types and shapes to disambiguate.

Myth 02 — Story points are a Scrum concept

The claim. Every "real" Scrum team estimates in story points.

The Scrum Guide. Mandates estimation, prescribes no method. The Guide has not mentioned story points since 2010.

The origin. Ron Jeffries coined story points as part of Extreme Programming in the late 1990s — initially to abstract "ideal days" into a unitless number that prevented managers from locking in rigid commitments. Mike Cohn popularized them in Agile Estimating and Planning (2005). In a 2019 blog post titled "Story Points Revisited," Jeffries himself wrote:

"I like to say that I may have invented story points, and if I did, I'm sorry now."

— Ron Jeffries, 2019 (source)

He went on to call comparing teams on velocity "harmful." The person credited with inventing the unit publicly disowned it.

Do this instead. Estimate in real time units. Effort in hours. Duration derived from real team capacity, accounting for vacations, support load, and the percentage of development time that actually exists in a working week. The unit business leadership needs to plan around is a delivery date — and story points were a translation layer between something developers could approximate and something the business could schedule. Every link in that translation introduces distortion. Skip the layer.

Myth 03 — Planning poker is a Scrum ceremony

The claim. Real Scrum teams play planning poker to estimate together.

The Scrum Guide. Never mentions it. In any version.

The origin. James Grenning introduced planning poker in a 2002 paper titled "Planning Poker or How to avoid analysis paralysis while release planning" — written for Extreme Programming release planning, not Scrum. Mike Cohn later popularized it for Scrum teams in Agile Estimating and Planning (2005), which is also how it spread.

Do this instead. Asynchronous breakdown, AI-first estimation. Modern AI tools can read a change description, propose a breakdown, and estimate both the AI execution portion and the human review-and-validation portion as separate components of each work unit. Developers review those numbers the same way they review AI-generated code — not from scratch, but with judgment applied to a draft. Combining the AI portion and the human portion in each unit of work is often more accurate than a developer guessing in isolation, because both pieces become quantifiable once the scope is explicit. Dev leads clarify requirements where the AI was uncertain. The kickoff that replaces sprint planning is for alignment, not estimation: is the scope coherent, are the dependencies visible, is the duration realistic, are the risks understood. Planning poker made sense when estimation was hard and group calibration required a synchronous ritual. With AI carrying the first-pass numbers, the calibration ceremony has shrunk to a confirmation conversation.

Myth 04 — Sprints must be two weeks

The claim. A proper sprint is two weeks. One week is too short, three weeks is too long.

The Scrum Guide. "One month or less." That is the entire prescription. No specific duration.

The origin. The two-week default crystallized in the early 2000s as a compromise between "weekly is too much overhead" and "monthly is too long for feedback." Then Jira shipped two-week sprints as a default template in the mid-2000s, and a generation of teams inherited the cadence without questioning it.

Do this instead. Variable durations derived from effort and capacity. Each initiative gets its own duration window — calculated from estimated effort divided by available developer capacity, with a multiplier for meetings, reviews, and overhead. A small initiative might run a week. A platform migration might run six weeks. Forcing both into the same fixed two-week container is what makes sprints feel arbitrary — because they are.

Myth 05 — Velocity is a Scrum metric

The claim. You measure team performance with velocity. A healthy team has stable velocity.

The Scrum Guide. The word "velocity" appears zero times in any version of the Scrum Guide. It has never been a Scrum concept.

The origin. Velocity comes from Mike Cohn's books and the broader Agile-coaching ecosystem of the early 2000s. It became universal because dashboards needed something to chart and story-point throughput was easy to count.

Do this instead. Effort-based burndown tracked against a real time budget. Estimate effort in time units, log time as work progresses, watch the burndown deviate. Spike upward in remaining work? Scope was added — make the trade-off visible. No movement? Something is blocked — surface it. Steady drift? Underestimate — recalibrate. Burndown is variance detection, not performance scoring. It tells you when to have a conversation about reality, not when to congratulate or punish.

Myth 06 — "As a user, I want…" is mandatory

The claim. Every story must follow the "As a [role], I want [feature], so that [benefit]" template. It is what makes a story a "user story."

The Scrum Guide. Never mentions user stories or the template. The Guide refers to Product Backlog Items — no format prescribed.

The origin. The template was invented at Connextra Ltd., a London software company, in 2001 — originally called "role-feature-reason." Mike Cohn popularized it in User Stories Applied (2004). The Agile Alliance's own glossary, maintained by the organization that stewards the Agile Manifesto, describes the template this way:

"Training wheels… often outgrown once past the novice stage. Many novice teams fall into rote application… spending much effort and time on complying with user story templates is without much point."

— Agile Alliance glossary (source)

The Agile Alliance is, in effect, telling you to stop using their own template once you know what you are doing.

Do this instead. Direct, scannable titles that read as actions. Add auth retry logic. Implement search filtering. Refactor API query boundaries. The discipline the template was trying to instill — name the user, the capability, the reason — is still product thinking. You do not need a template to have that conversation. You need a team that asks those questions, and increasingly, AI assistance that translates intent into whatever structured artifact a downstream system actually needs.

Myth 07 — Fibonacci scales are more accurate

The claim. Estimating in 1, 2, 3, 5, 8, 13 is more accurate than linear scales because it acknowledges uncertainty grows with size.

The Scrum Guide. Does not mention Fibonacci.

The origin. Mike Cohn's Agile Estimating and Planning (2005). The argument was theoretically defensible — you cannot meaningfully distinguish between an 8 and a 9, so the gaps in the scale should grow. In practice, the gaps just give teams more numbers to argue about.

Do this instead. You don't need a scale at all, and most teams shouldn't have one. Estimate in real time — hours, days, whatever unit fits the work. Aim for the midpoint between your most optimistic case and your worst case: not so aggressive you fail most of your estimates, not so padded that you become the team consistently under-delivering against your own capacity. Precision improves as ideation gets closer to execution — rough estimates for early-stage ideas, refined as the work enters the planning window. Fewer layers between estimate and reality means more clarity for everyone — leadership, developers, the people doing the planning. If your tooling forces a numeric scale on you (some systems do), keep the mapping as simple as the team can guess on sight: every number is days is the safest bet. The anti-pattern is abstract, team-specific points that mean different things to different people across the org.

Myth 08 — The Sprint Retrospective must be ritualized and recurring

The claim. Every sprint ends with a one-hour retro. Three columns: what went well, what didn't, what to try next.

The Scrum Guide. The Sprint Retrospective exists as one of the five events. Its format is unspecified. Its frequency follows the sprint cadence — but the sprint cadence itself is up to the team.

The origin. The format with three columns and the standard prompts comes from agile-coaching practice, not the Guide. It is reasonable as a starting structure. It became a problem when teams kept doing it on autopilot for years, with the same stale findings, in meetings everyone attended out of obligation.

Do this instead. Inspect-and-adapt is the principle. The recurring meeting is not the principle. If the retro produces meaningful change, keep doing it. If it produces stale lists nobody acts on, change the format, change the cadence, replace it with a written reflection, or run it only when the team has something real to discuss. Rituals that no one believes in corrode trust. The Guide gives you permission to vary the format — most teams have just never used that permission.

Myth 09 — Backlog refinement is a required ceremony

The claim. Friday afternoons are for backlog refinement. The whole team. Two hours. Walk through the upcoming stories.

The Scrum Guide. Refinement is described as an ongoing activity — refining backlog items as needed throughout the sprint. No ceremony, no scheduled meeting, no required cadence is prescribed.

The origin. The recurring two-hour refinement meeting is enterprise-Scrum optimization for a world where everything had to happen synchronously and breaking down work required collective interpretation.

Do this instead. Just-in-time breakdown. The Dev Lead refines stories shortly before they enter execution. AI assists with decomposition, surfaces ambiguities, and drafts acceptance criteria. Targeted conversations replace whole-team meetings. Heavy upfront refinement on stories that may shift in priority is wasted effort. The simplest test: ask whether your refinement meeting changed anything you would not have figured out anyway. If not, it is overhead.

Myth 10 — The Daily Scrum is a status-update meeting

The claim. Stand up. Three questions. What I did yesterday, what I'll do today, what's blocking me. Round-robin around the team. Fifteen minutes.

The Scrum Guide. Specifies a 15-minute event for the Developers to inspect progress toward the Sprint Goal and adapt the Sprint Backlog. The format is not prescribed. The audience is the developers, not stakeholders. The three-questions format is not in the Guide.

The origin. The three-questions format comes from XP-era practice and Mike Cohn-era coaching. It made sense in 2003 when the developers genuinely needed to coordinate verbally because tooling was thin. Today most of "what I did yesterday" is visible in pull requests, ticket history, and Slack threads. Speaking it aloud has become reporting, not coordinating.

Do this instead. The actual value of the Daily Scrum isn't the mechanical update — it's the unscheduled cross-pollination that happens when developers with different context are in the same room once a day. Someone mentions an escalation; someone else says wait, that sounds related to what I'm seeing in module X; a side-bar gets scheduled for later. New issues that nobody knew were issues get surfaced because somebody's experience caught a thread in somebody else's update. That's the meeting paying for itself, and it's especially valuable for unexpected work — escalations, support load, cross-cutting concerns — where the right person to talk to isn't obvious until somebody describes the problem out loud.

So keep the standup. Keep it fast. Lightweight visibility on what people are working on is real value as ambient awareness, not as a status report. Encourage tangents to become side-bars when they get long. And value the unexpected discussions over the predictable ones — that's where the meeting earns its keep.

The agreement this approach requires

Real-time-unit estimation, variable timeboxes, and burndown-as-variance-detection all rest on one cultural condition: estimates are honest probabilistic statements, variance gets surfaced early, and in return, leadership treats that variance as a planning input rather than a performance event.

Without that agreement, the failure mode is real and well-documented. Leadership treats every estimate as a contract. Developers learn to pad heavily or refuse to estimate at all. The estimate becomes either useless — too padded to plan around — or punitive, held against the team when reality diverges. At that point the rational defensive move is to retreat to story points, abstract velocity, and "we deliver value every sprint, ask no further questions" — abstraction layers that make the date conversation structurally impossible to have. That retreat is what a lot of enterprise Scrum is actually optimizing for. It is not a principled position. It is scar tissue from leadership cultures that punished honesty.

The alternative described above requires both sides to behave differently. Developers commit to estimating in real units, naming what the estimate assumes, and surfacing scope changes or unexpected complexity the day they discover them — not at sprint review. Leadership commits to treating those updates as the same kind of input as a market-data revision: re-plan around it, re-prioritize, decide what to cut. Not as a failure to manage.

If an organization can hold that agreement, it gets something the ceremony-heavy alternative cannot offer: a date to plan around, and a team trusted to tell you when the date moves and why. If it cannot — yet — that is a culture problem to address before it is a process problem to redesign. Naming the precondition honestly is the first step.

The Scrum Guide is fine. Enterprise Scrum is what's broken.

When this argument goes wrong, it goes wrong in one direction: people read it and conclude that Scrum is broken. That is the wrong conclusion.

The Scrum Guide is defensible. Its empirical philosophy — transparency, inspection, adaptation — is sound and stays sound. It is minimal by design. It accommodates the Timebox Method, Kanban, hybrid models, the workflow your team is about to invent. It has been getting less prescriptive with every revision, not more. The people who wrote it have spent twenty years quietly removing rules.

What broke under AI acceleration is not Scrum. It is enterprise Scrum — the folk overlay that most teams actually practice. The story-point estimation theater. The two-week cadence imposed by default. The velocity charts. The planning poker sessions. The "As a user…" ticket templates. The recurring refinement meetings nobody acts on. The retros that produce sticky notes nobody reads. The Jira workflows so complex they need a flowchart on the wiki.

That is the layer that gets in the way. That is the layer your team argues about. And almost none of it was ever Scrum.

A useful test, before defending any practice as "what Scrum requires": find it in the Guide. The Guide is 13 pages. It will take you ten minutes. If the practice is not there, it is a folk convention you have been told is mandatory. You can keep it if it is genuinely earning its keep — or you can replace it with something that fits how your team actually works.

Most teams already know enterprise Scrum is not serving them. The hard part has never been the diagnosis. The hard part is giving yourself permission to change it — and that starts with knowing which rules were never rules.

Handling errors in TypeScript the right way

Nicolas Bouvrette — Tue, 05 Sep 2023 14:00:57 +0000

Error handling is one of the key areas in software engineering. When done correctly, it can save you hours of debugging and troubleshooting. I’ve identified three main challenges related to error handling:

TypeScript’s error type
Variable scoping
Nesting

Let’s delve deeper into each of them to better understand the challenges they present.

Challenge 1: TypeScript’s error type

In JavaScript, the most common way to handle errors is similar to that in most programming languages:

try {
  throw new Error('oh no!')
} catch (error) {
  console.dir(error)
}

You’re going to end up seeing an object that looks like this:

{
  message: 'oh no!'
  stack: 'Error: oh no!\n at <anonymous>:2:8'
}

This seems straightforward, so what about TypeScript? One of the first things I noticed is that when you use a try/catch block and check the type of error, you’ll find that its type is unknown.

For those new to TypeScript, this can be perceived as an annoyance. A common workaround for this issue is to simply cast the error, as shown below:

try {
  throw new Error('oh no!')
} catch (error) {
  console.log((error as Error).message)
}

This approach likely works for 99.9% of caught errors. But why does TypeScript make error typing seemingly cumbersome? The reason is that it’s genuinely impossible to infer the type of “error” because a try/catch block doesn’t catch only errors; it catches anything that’s thrown. In JavaScript (and TypeScript), you can throw almost anything, as demonstrated below:

try {
  throw undefined
} catch (error) {
  console.log((error as Error).message)
}

Executing this code will result in a new error being thrown within the “catch” block, which negates the purpose of using a try/catch in the first place:

Uncaught TypeError: Cannot read properties of undefined (reading 'message') at <anonymous>:4:20

The issue arises because the message property doesn’t exist on undefined, leading to a TypeError within the catch block. In JavaScript, only two values can cause this issue: undefined and null.

In this specific scenario even using finally won't help much other than performing one last action before the the TypeError:

try {
  throw undefined
} catch (error) {
  console.log((error as Error).message)
} finally {
  console.log('this will log');
}
console.log('code here is unreachable because "catch" threw a TypeError')

Now, one might wonder about the likelihood of someone throwing undefined or null. While it’s probably rare, if it does occur, it can introduce unexpected behaviors in your code. Furthermore, considering the plethora of third-party packages typically used in a TypeScript project, it wouldn’t be surprising if one of them inadvertently throws an incorrect value.

Is this the only reason TypeScript sets the type of throwables to unknown? At first glance, it might seem like a rare edge case, and casting could appear as a reasonable solution. However, there’s more to it. While undefined and null are the most disruptive cases, as they can crash your application, other values can also be thrown. For example:

try {
  throw false
} catch (error) {
  console.log((error as Error).message)
}

The primary distinction here is that, rather than throwing a TypeError, this will simply return undefined. While this is less disruptive since it won’t directly crash your application, it can introduce other issues, such as displaying undefined in your logs. Moreover, depending on how you use the undefined value, it could indirectly lead to application crashes. Consider the following example:

try {
  throw false
} catch (error) {
  console.log((error as Error).message.trim())
}

Here, invoking .trim() on undefined will trigger a TypeError, potentially crashing your application.

In essence, TypeScript aims to safeguard us by designating the type of catchables as unknown. This approach places the onus on developers to determine the correct type of the thrown value, helping to prevent runtime issues.

You could always safeguard your code by using optional chaining operators (?.) as shown below:

try {
  throw undefined
} catch (error) {
  console.log((error as Error)?.message?.trim?.())
}

While this approach can shield your code, it employs two TypeScript features that can complicate code maintenance:

Type casting undermines TypeScript’s safeguards, ensuring that variables adhere to their specified types.
Utilizing optional chaining operators on a non-optional type won’t raise any errors if someone omits them, given the type mismatch.

A preferable approach would be to leverage TypeScript’s type guards. Type guards are essentially functions that ensure a specific value matches a given type, confirming it’s safe to use as intended. Here’s an example of a type guard to verify if the caught variable is of type Error:

/**
 * Type guard to check if an `unknown` value is an `Error` object.
 *
 * @param value - The value to check.
 *
 * @returns `true` if the value is an `Error` object, otherwise `false`.
 */
export const isError = (value: unknown): value is Error =>
  !!value &&
  typeof value === 'object' &&
  'message' in value &&
  typeof value.message === 'string' &&
  'stack' in value &&
  typeof value.stack === 'string'

This type guard is straightforward. It first ensures that the value is not falsy, which means it won’t be undefined or null. It then checks if it’s an object with the expected attributes.

This type guard can be reused anywhere in the code to verify if an object is an Error. Here’s an example of its application:

const logError = (message: string, error: unknown): void => {
  if (isError(error)) {
    console.log(message, error.stack)
  } else {
    try {
      console.log(
        new Error(
          `Unexpected value thrown: ${
            typeof error === 'object' ? JSON.stringify(error) : String(error)
          }`
        ).stack
      )
    } catch {
      console.log(
        message,
        new Error(`Unexpected value thrown: non-stringifiable object`).stack
      )
    }
  }
}

try {
  const circularObject = { self: {} }
  circularObject.self = circularObject
  throw circularObject
} catch (error) {
  logError('Error while throwing a circular object:', error)
}

By creating a logError function that leverages the isError type guard, we can safely log standard errors as well as any other thrown values. This can be particularly useful for troubleshooting unexpected issues. However, we need to be cautious, as JSON.stringify can also throw errors. By encapsulating it within its own try/catch block, we aim to provide more detailed information for objects, rather than just logging their string representation, [object Object].

Furthermore, we can retrieve the stack trace leading up to the point where the new Error object was instantiated. This will include the location where the original value was thrown. While this method doesn’t provide a direct stack trace from the thrown values, it offers a trace from the point immediately after the throw, which should be adequate for tracing back to the problem’s origin.

Challenge 2: Variable scoping

Scoping is likely one of the most common challenges in error handling, applicable to both JavaScript and TypeScript. Consider this example:

try {
  const fileContent = fs.readFileSync(filePath, 'utf8')
} catch {
  console.error(`Unable to load file`)
  return
}

console.log(fileContent)

In this case, because fileContent was defined inside the try block, it’s not accessible outside of it. To address this, you might be tempted to define the variable outside the try block:

let fileContent

try {
  fileContent = fs.readFileSync(filePath, 'utf8')
} catch {
  console.error(`Unable to load file`)
  return
}

console.log(fileContent)

This approach is less than ideal. By using let instead of const, you’re making the variable mutable, which can introduce potential bugs. Additionally, it makes the code harder to read.

One way to circumvent this issue is to wrap the try/catch block in a function:

const fileContent = (() => {
  try {
    return fs.readFileSync(filePath, 'utf8')
  } catch {
    console.error(`Unable to load file`)
    return
  }
})()

if (!fileContent) {
  return
}

console.log(fileContent)

While this approach addresses the mutability problem, it does make the code more complex. This issue could potentially be addressed by creating our own reusable wrapper function. However, before doing so, let’s review the last challenge to ensure we have a comprehensive understanding of all the problems.

Challenge 3: Nesting

Here’s an example demonstrating how we would use the new logError function in a scenario where multiple errors could be thrown:

export const doStuff = async (): Promise<void> => {
  try {
    const fetchDataResponse = await fetch('https://api.example.com/fetchData')
    const fetchDataText = await fetchDataResponse.text()

    if (!fetchDataResponse.ok) {
      throw new Error(
        `Unexpected response while fetching data. Status: ${fetchDataResponse.status} | Status text: ${fetchDataResponse.statusText} | Body: ${fetchDataText}`
      )
    }

    let fetchData
    try {
      fetchData = JSON.parse(fetchDataText) as unknown
    } catch {
      throw new Error(`Failed to parse fetched data response as JSON: ${fetchDataText}`)
    }

    if (
      !fetchData ||
      typeof fetchData !== 'object' ||
      !('data' in fetchData) ||
      !fetchData.data
    ) {
      throw new Error(
        `Fetched data is not in the expected format. Body: ${fetchDataText}`
      )
    }

    const storeDataResponse = await fetch('https://api.example.com/storeData', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(fetchData),
    })

    const storeDataText = await storeDataResponse.text()

    if (!storeDataResponse.ok) {
      throw new Error(
        `Unexpected response while storing data. Status: ${storeDataResponse.status} | Status text: ${storeDataResponse.statusText} | Body: ${storeDataText}`
      )
    }
  } catch (error) {
    logError('An error occurred:', error)
  }
}

You might observe that we’re invoking the .text() API instead of .json(). This choice stems from the behavior of fetch: you can only call one of these two methods. As we aim to display the body content if the JSON conversion fails, we first call .text() and then manually revert to JSON, ensuring we catch any errors in the process. To avoid having cryptic errors like:

Uncaught SyntaxError: Expected property name or '}' in JSON at position 42

While the details provided by the error will make this code easier to debug, its limited readability can make maintenance challenging. The nesting induced by the try/catch blocks increases the cognitive load when reading the function. However, there’s a way to simplify the code, as shown below:

export const doStuffV2 = async (): Promise<void> => {
  try {
    const fetchDataResponse = await fetch('https://api.example.com/fetchData')
    const fetchData = (await fetchDataResponse.json()) as unknown

    if (
      !fetchData ||
      typeof fetchData !== 'object' ||
      !('data' in fetchData) ||
      !fetchData.data
    ) {
      throw new Error('Fetched data is not in the expected format.')
    }

    const storeDataResponse = await fetch('https://api.example.com/storeData', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(fetchData),
    })

    if (!storeDataResponse.ok) {
      throw new Error(`Error storing data: ${storeDataResponse.statusText}`)
    }
  } catch (error) {
    logError('An error occurred:', error)
  }
}

This refactoring fixed the nesting problem but it introduced a new issue: a lack of granularity in error reporting. By removing checks, we become more reliant on the error message itself to understand issues. As we’ve seen from some of the JSON.parse errors, this might not always provide the best clarity.

Given all the challenges we’ve discussed, is there an optimal approach to handle errors effectively?

The right way

Ok, so now that we’ve highlighted some of the challenges surrounding typings and the use of traditional try/catch blocks, the benefits of adopting a different approach become clearer. This suggests that we should seek a superior method than the conventional try/catch blocks for error handling. By harnessing the capabilities of TypeScript, we can effortlessly craft a wrapper function for this purpose.

The initial step involves determining how we wish to normalize the errors. Here’s one approach:

/** An `Error` object to safely handle `unknown` values being thrown. */
export class NormalizedError extends Error {
  /** The error's stack or a fallback to the `message` if the stack is unavailable. */
  stack: string = ''
  /** The original value that was thrown. */
  originalValue: unknown

  /**
   * Initializes a new instance of the `NormalizedError` class.
   *
   * @param error - An `Error` object.
   * @param originalValue - The original value that was thrown.
   */
  constructor(error: Error, originalValue?: unknown) {
    super(error.message)
    this.stack = error.stack ?? this.message
    this.originalValue = originalValue ?? error

    // Set the prototype explicitly, for `instanceof` to work correctly when transpiled to ES5.
    Object.setPrototypeOf(this, NormalizedError.prototype)
  }
}

The primary advantage of extending the Error object is that it behaves like a standard error. Creating a custom error object from scratch might lead to complications, especially when using the instanceof operator to check its type. This is why we set the prototype explicitly, ensuring that instanceof works correctly, especially when the code is transpiled to ES5.

Additionally, all the prototype functions from Error are available on the NormalizedError objects. The constructor’s design also simplifies the creation of new NormalizedError objects by requiring the first argument to be an actual Error. Here are the benefits of NormalizedError:

It will always be a valid error since the constructor mandates an Error as its first argument.
A new property, originalValue, has been added. This allows us to retrieve the original value that was thrown, which can be useful for extracting additional information from the error or during debugging.
stack will never be undefined. In many cases, it’s more beneficial to log the stack property since it contains more information than the message property. However, TypeScript defines its type as string | undefined, primarily due to cross-environment compatibility (often observed in legacy environments). By overriding the type and guaranteeing that it will always be a string, its use is simplified.

Now that we’ve defined how we want to represent normalized errors, we need a function to easily convert unknown thrown values into a normalized error:

/**
 * Converts an `unknown` value that was thrown into a `NormalizedError` object.
 *
 * @param value - An `unknown` value.
 *
 * @returns A `NormalizedError` object.
 */
export const toNormalizedError = <E>(
  value: E extends NormalizedError ? never : E
): NormalizedError => {
  if (isError(value)) {
    return new NormalizedError(value)
  } else {
    try {
      return new NormalizedError(
        new Error(
          `Unexpected value thrown: ${
            typeof value === 'object' ? JSON.stringify(value) : String(value)
          }`
        ),
        value
      )
    } catch {
      return new NormalizedError(
        new Error(`Unexpected value thrown: non-stringifiable object`),
        value
      )
    }
  }
}

By using this approach, we no longer have to handle errors of type unknown. All errors will be proper Error objects, equipping us with as much information as possible and eliminating the risk of unexpected error values.

Note that E extends NormalizedError ? never is optional. However, it can help prevent mistakenly passing a NormalizedError object as an argument.

To safely use NormalizedError object, we also need to have a type guard function:

/**
 * Type guard to check if an `unknown` value is a `NormalizedError` object.
 *
 * @param value - The value to check.
 *
 * @returns `true` if the value is a `NormalizedError` object, otherwise `false`.
 */
export const isNormalizedError = (value: unknown): value is NormalizedError =>
  isError(value) && 'originalValue' in value && value.stack !== undefined

Now, we need to craft a function that will help us eliminate the use of try/catch blocks. Another crucial aspect to consider about errors is their occurrence, which can be either synchronous or asynchronous. Ideally, we’d want a single function capable of handling both scenarios. Let’s begin by creating a type guard to identify promises:

/**
 * Type guard to check if an `unknown` function call result is a `Promise`.
 *
 * @param result - The function call result to check.
 *
 * @returns `true` if the value is a `Promise`, otherwise `false`.
 */
export const isPromise = (result: unknown): result is Promise<unknown> =>
  !!result &&
  typeof result === 'object' &&
  'then' in result &&
  typeof result.then === 'function' &&
  'catch' in result &&
  typeof result.catch === 'function'

With the capability to safely identify promises in place, we can proceed to implement our new noThrow function:

type NoThrowResult<A> = A extends Promise<infer U>
  ? Promise<U | NormalizedError>
  : A | NormalizedError

/**
 * Perform an action without throwing errors.
 *
 * Try/catch blocks can be hard to read and can cause scoping issues. This wrapper
 * avoids those pitfalls by returning the appropriate result based on whether the function
 * executed successfully or not.
 *
 * @param action - The action to perform.
 *
 * @returns The result of the action when successful, or a `NormalizedError` object otherwise.
 */
export const noThrow = <A>(action: () => A): NoThrowResult<A> => {
  try {
    const result = action()
    if (isPromise(result)) {
      return result.catch(toNormalizedError) as NoThrowResult<A>
    }
    return result as NoThrowResult<A>
  } catch (error) {
    return toNormalizedError(error) as NoThrowResult<A>
  }
}

By harnessing the capabilities of TypeScript, we can dynamically support both asynchronous and synchronous function calls while maintaining accurate typing. This enables us to utilize a single utility function to manage all errors.

Also, as mentioned earlier, this can be especially useful to address scoping issues. Instead of wrapping a try/catch block in its own anonymous self-invoking function, we can simply use noThrow, making the code much more readable.

Let’s explore how we can use this approach to refactor the code we developed earlier:

export const doStuffV3 = async (): Promise<void> => {
  const fetchDataResponse = await fetch('https://api.example.com/fetchData').catch(toNormalizedError)

  if (isNormalizedError(fetchDataResponse)) {
    return console.log('Error fetching data:', fetchDataResponse.stack)
  }

  const fetchDataText = await fetchDataResponse.text()

  if (!fetchDataResponse.ok) {
    return console.log(
      `Unexpected response while fetching data. Status: ${fetchDataResponse.status} | Status text: ${fetchDataResponse.statusText} | Body: ${fetchDataText}`
    )
  }

  const fetchData = noThrow(() => JSON.parse(fetchDataText) as unknown)

  if (isNormalizedError(fetchData)) {
    return console.log(
      `Failed to parse fetched data response as JSON: ${fetchDataText}`,
      fetchData.stack
    )
  }

  if (
    !fetchData ||
    typeof fetchData !== 'object' ||
    !('data' in fetchData) ||
    !fetchData.data
  ) {
    return console.log(
      `Fetched data is not in the expected format. Body: ${fetchDataText}`,
      toNormalizedError(new Error('Invalid data format')).stack
    )
  }

  const storeDataResponse = await fetch('https://api.example.com/storeData', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(fetchData),
    }).catch(toNormalizedError)

  if (isNormalizedError(storeDataResponse)) {
    return console.log('Error storing data:', storeDataResponse.stack)
  }

  const storeDataText = await storeDataResponse.text()

  if (!storeDataResponse.ok) {
    return console.log(
      `Unexpected response while storing data. Status: ${storeDataResponse.status} | Status text: ${storeDataResponse.statusText} | Body: ${storeDataText}`
    )
  }
}

There we have it! We’ve addressed all the challenges:

Types are now safe to use, so we no longer need logError and can log errors directly using console.log.
Scoping is controlled by using noThrow, as demonstrated when defining the const fetchData which previously had to be a let fetchData.
Nesting has been reduced to a single level, making the code easier to maintain.

You might have also noticed that we didn’t use noThrow on fetch. Instead, we used toNormalizedError, which has more or less the same effect as noThrow but with less nesting. Because of how we built the noThrow function, you could use it on fetch the same way we used it for sync functions:

  const fetchDataResponse = await noThrow(() =>
    fetch('https://api.example.com/fetchData')
  )

I personally prefer the approach that we took in our example, and I would rather use noThrow in an async context when the code block contains more than a single function. toNormalizedError also doesn’t use a try/catch block under the hood which is better for performance.

Performance Considerations

While the noThrow utility function offers a streamlined approach to error handling, it’s essential to understand that it still leverages try/catch blocks under the hood. This means that any performance implications associated with try/catch will still be present when using noThrow.

In performance-critical sections of your code, or “hot code paths,” it’s always a good idea to be judicious about introducing any abstractions, including error handling utilities. While modern JavaScript engines have made significant strides in optimizing try/catch performance, there can still be overhead, especially when used excessively.

Recommendations:

Be Mindful in Hot Paths: If a particular section of your code is executed very frequently, consider the implications of any added abstractions, including error handling.
Profile When in Doubt: If you’re unsure about the performance impact of your error handling strategy, use profiling tools to measure and compare execution times in your specific environment.
Stay Informed: As always, keep abreast of the latest advancements in JavaScript engines and TypeScript. Performance characteristics can evolve, and what’s true today might change tomorrow.

In essence, while the noThrow function provides a more elegant way to handle errors in TypeScript, it’s essential to be aware of the underlying mechanisms and their potential implications.

A Shift in Error Handling

The combination of the noThrow utility function and the NormalizedError class presents a novel approach to error handling in TypeScript, diverging from the traditional try/catch mechanism native to JavaScript. While this duo offers a streamlined and type-safe error handling experience, developers should be aware of the implications of this paradigm shift:

Departure from the Standard: Using noThrow and NormalizedError is a significant departure from conventional JavaScript error handling. Those accustomed to the traditional try/catch might need to recalibrate their understanding when working within this new framework.
Consistency is Crucial: If you opt to adopt the noThrow and NormalizedError approach in your codebase, it’s essential to apply it consistently. Intermingling this method with traditional try/catch blocks can introduce confusion and inconsistency, potentially complicating maintenance and debugging.
Education and Onboarding: Given that neither noThrow nor NormalizedError are standard features in JavaScript or TypeScript, there’s a responsibility to ensure that all team members are well-versed in their usage and behavior. This might entail creating dedicated documentation, examples, or even training sessions to ensure everyone is on the same page.

Conclusion

In the ever-evolving landscape of software development, error handling remains a cornerstone of robust application design. As we’ve explored in this article, traditional methods like try/catch blocks, while effective, can sometimes lead to convoluted code structures, especially when combined with the dynamic nature of JavaScript and TypeScript. By embracing the capabilities of TypeScript, we’ve demonstrated a streamlined approach to error handling that not only simplifies our code but also enhances its readability and maintainability.

The introduction of the NormalizedError class and the noThrow utility function showcases the power of modern programming paradigms. These tools allow developers to handle both synchronous and asynchronous errors with grace, ensuring that applications remain resilient in the face of unexpected issues.

As developers, our primary goal is to create software that’s both functional and user-friendly. By adopting the techniques discussed in this article, we can ensure that our applications not only meet these criteria but also stand the test of time. Happy coding!

TypeScript Wrapper: Optional Inputs and Dynamic Output Types

Nicolas Bouvrette — Sat, 15 Jul 2023 17:43:07 +0000

While many articles explain how to write a wrapper, in this one we’ll show you how to fully control its type. But first, let’s define what a wrapper is:

A wrapper is a function that encapsulates another function. Its primary purpose is to execute additional logic that the original function wouldn't perform, typically to help reduce boilerplate code.

When done correctly, you can add options to your wrapper that will dynamically determine its output types. This means that you can construct a fully customizable, type-safe wrapper that will enhance your development experience.

Before we start

All the examples from this article are also provided TypeScript Playground. Given that this article is centered around a practical example, I’ve had to mock certain functions and types to demonstrate how they work. The code provided below will be used in most of the examples, but will not be repeatedly included in each individual example, to make the content easier to read:

// These should be Next.js types, typically imported from next.
type NextApiRequest = { body: any }
type NextApiResponse = { json: (arg: unknown) => void }

// Under normal circumstances, this function would return a unique ID for a logged-in user.
const getSessionUserId = (): number | null => {
  return Math.random() || null
}

// This function is utilized to parse the request body and perform basic validation.
const parseNextApiRequestBody = <B = object>(
  request: NextApiRequest
): Partial<B> | null => {
  try {
    const parsedBody = JSON.parse(request.body as string) as unknown
    return typeof parsedBody === 'object' ? parsedBody : null
  } catch {
    return null
  }
}

In addition to the main code, we’ll also be using two other tools. These won’t be included in the individual examples but will be available in the TypeScript Playground. The first is a type called Expand, which is based on the following code:

type Expand<T> = T extends ((...args: any[]) => any) | Date | RegExp
  ? T
  : T extends ReadonlyMap<infer K, infer V>
  ? Map<Expand<K>, Expand<V>>
  : T extends ReadonlySet<infer U>
  ? Set<Expand<U>>
  : T extends ReadonlyArray<unknown>
  ? `${bigint}` extends `${keyof T & any}`
    ? { [K in keyof T]: Expand<T[K]> }
    : Expand<T[number]>[]
  : T extends object
  ? { [K in keyof T]: Expand<T[K]> }
  : T

This utility type was contributed by kelsny in a Stack Overflow comment. As discussed in the thread, it’s not production-ready and serves purely as a utility function for easily expanding types. Without Expand, we wouldn’t be able to view the individual type’s properties directly within the TypeScript Playground examples.

The second tool is the // ^? syntax, which many people may be unfamiliar with. This is a unique TypeScript Playground feature that dynamically displays the type of the variable to which the ^ is pointing (above), making it easier to keep track of your types as you modify the code. When used with Expand, it can be extremely useful for troubleshooting your types.

⚠ Normally, we would place all wrappers in a helper file (e.g., /src/api.helper.ts) so they could be reused across all APIs. However, for the sake of this article, we’ll put all the code in the same file to easily demonstrate it in action.

Our practical example

We recently encountered a TypeScript challenge while trying to improve our Next.js API wrapper. Because it provides a good example, and is both practical and easy to understand, we’ll use it throughout this article. Don’t worry, you don’t need to know anything about Next.js; that’s not the focus of this article.

For those unfamiliar with Next.js, here’s how you define an API: create a file in /pages/api/hello.tsx, copy and paste the code below, and you’ll have a neat {"hello": "world"} API.

import { NextApiRequest, NextApiResponse } from 'next'

export default async (
  request: NextApiRequest,
  response: NextApiResponse
): Promise<void> => {
  return void response.json({ hello: 'world' })
}

This approach works perfectly fine for small applications. But what happens when your application grows and you start having numerous APIs that perform a lot of the same logic repeatedly? Typically, most developers write a wrapper on top to handle the repetitive logic.

The need for a wrapper

Let’s suppose, for instance, that we have some APIs that require authentication and others that don’t. We want a wrapper to handle this logic. Here’s one way we can accomplish this:

Complete example in TypeScript Playground

type Options = {
  requiresAuthentication?: boolean
}

type CallbackOptions<O extends Options = Options> = {
  request: NextApiRequest
  response: NextApiResponse
} & (O['requiresAuthentication'] extends true ? { userId: string } : object)

export const handleRequest =
  <O extends Options = Options>(
    options: O,
    callback: (options: CallbackOptions<O>) => Promise<void>
  ) =>
  async (request: NextApiRequest, response: NextApiResponse) => {
    // If the user is not found, we can return a response right away.
    const userId = getSessionUserId()
    if (options.requiresAuthentication && !userId) {
      return void response.json({ error: 'missing authentication' })
    }

    return callback({
      request,
      response,
      ...(options.requiresAuthentication ? { userId } : {}),
    } as CallbackOptions<O>)
  }

By introducing an options argument in the handler, we can specify which option we want to use, and the type of the callback will update dynamically. This feature is incredibly useful, as it prevents us from using an option that isn’t available in the callback.

For instance, if you utilize handleRequest with no options like this:

export default handleRequest({}, async (options) => {
  // some API code here...
})

Now, options only contains request and response, which is more or less equivalent to having no wrapper. However, when you use it with an option, it becomes significantly more useful:

export default handleRequest(
  { requiresAuthentication: true },
  async (options) => {
    // some API code here...
  }
)

options includes request, response, and userId. If the user is not logged in, the code inside the wrapper will not be executed.

This means that by setting different options, we can leverage TypeScript to identify any type issues with our code during development.

Taking it one step further

Let’s take this a step further. What if we wanted the wrapper to optionally parse the request’s body and return the correct type? We can accomplish this as follows:

Complete example in TypeScript Playground

type Options = {
  requiresAuthentication?: boolean
}

type CallbackOptions<B = never, O extends Options = Options> = {
  request: NextApiRequest
  response: NextApiResponse
  parsedRequestBody: B
} & (O['requiresAuthentication'] extends true ? { userId: string } : object)

export const handleRequest =
  <B = never, O extends Options = Options>(
    options: O,
    callback: (options: CallbackOptions<B, O>) => Promise<void>
  ) =>
  async (request: NextApiRequest, response: NextApiResponse) => {
    // If the user is not found, we can return a response right away.
    const userId = getSessionUserId()
    if (options.requiresAuthentication && !userId) {
      return void response.json({ error: 'missing authentication' })
    }

    return callback({
      request,
      response,
      parsedRequestBody: {} as B,
      ...(options.requiresAuthentication ? { userId } : {}),
    } as CallbackOptions<B, O>)
  }

By introducing a new generic B that we can pass to handleRequest, we can now specify the type of the payload that will be sent in the body when the API is called, and receive the corresponding type for it. For example:

export default handleRequest<{ hello: string }>({}, async (options) => {
  // some API code here...
})

In this case, options includes request, response, and parsedRequestBody. The parsedRequestBody is of type { hello: string }. However, the challenge now is that we’ve only implemented the generic type; we haven’t included the logic that will check whether this option is present or not. We need to add a new option to accomplish this, as shown below:

Complete example in TypeScript Playground

type Options = {
  requiresAuthentication?: boolean
  parseBody?: boolean
}

type CallbackOptions<B = never, O extends Options = Options> = {
  request: NextApiRequest
  response: NextApiResponse
} & (O['requiresAuthentication'] extends true ? { userId: string } : object) &
  (O['parseBody'] extends true ? { parsedRequestBody: B } : object)

export const handleRequest =
  <B = never, O extends Options = Options>(
    options: O,
    callback: (options: CallbackOptions<B, O>) => Promise<void>
  ) =>
  async (request: NextApiRequest, response: NextApiResponse) => {
    // If the user is not found, we can return a response right away.
    const userId = getSessionUserId()
    if (options.requiresAuthentication && !userId) {
      return void response.json({ error: 'missing authentication' })
    }

    // Check if the request's body is valid.
    const parsedRequestBody = options.parseBody
      ? parseNextApiRequestBody<O>(request)
      : undefined
    if (options.parseBody && !parsedRequestBody) {
      return void response.json({ error: 'invalid payload' })
    }

    return callback({
      request,
      response,
      ...(options.parseBody ? { parsedRequestBody } : {}),
      ...(options.requiresAuthentication ? { userId } : {}),
    } as CallbackOptions<B, O>)
  }

When we add this new callback option (O['parseBody'] extends true ? { parsedRequestBody: B } : object), if the parseBody option is set to true, we should obtain a new option named parsedRequestBody, which carries the type of the generic B. This follows the exact same logic as what we did for requiresAuthentication. However, the only difference is that it utilizes a generic. We can try to implement it like this:

export default handleRequest<{ hello: string }>(
  { parseBody: true },
  async (options) => {
    // some API code here...
  }
)

When inspecting options, we quickly find that parsedRequestBody is not available. But why? We are using exactly the same logic as the one used by requiresAuthentication, which still works when using the following code:

export default handleRequest(
  { requiresAuthentication: true },
  async (options) => {
    // some API code here...
  }
)

What is going on?

When you partially specify generic parameters in TypeScript, the remaining parameters will fall back to their default values rather than being inferred from usage. This happens with the handleRequest function. When we provide a type for the B parameter (body type) but not for the O parameter (options type), TypeScript falls back to the default Options type for O.

In the Options type, parseBody and requiresAuthentication are optional properties, with their types defaulting to boolean | undefined. When these properties aren’t explicitly specified, TypeScript assigns them their default type, boolean | undefined, which is a union type.

In the CallbackOptions type, the parsedRequestBody and userId fields are conditionally included based on whether O['parseBody'] and O['requiresAuthentication'] extend true.

As a result, these fields are not included in the type. This behavior is triggered only when generic parameters are partially specified. It isn’t because the types could be undefined, but because the entire union type doesn’t extend true.

Therefore, with TypeScript’s current behavior, making generic inference work is basically an “all or nothing” approach.

There is an old (2016) GitHub issue discussing this specific topic here: https://github.com/microsoft/TypeScript/issues/10571

How to tackle the partial generic parameter inference limitation in TypeScript?

The two main workarounds that come to mind are typically the following:

Specifying all generic parameters: When using handleRequest, you could define all your types explicitly, as shown: handleRequest<{ hello: string }, { requiresAuthentication: true }>({ requiresAuthentication: true }, async (options) => {. While this may work, it forces you to specify all parameters, even the ones you’re not currently using. This can lead to a less than optimal developer experience, as the code may become harder to read and maintain with the growth in the number of options. For a demonstration, have a look at this TypeScript Playground.
Creating dedicated functions: Instead of having a one-size-fits-all handleRequest, you could create bespoke functions like handleRequestWithAuthAndBody and handleRequestWithAuth, etc. The drawback here is the potential for significant code duplication. As your options expand, maintaining the code could become a daunting task. For a hands-on look, check out this example on TypeScript Playground.

So, is there an optimal solution to this problem? It seems that every approach comes with its own set of challenges, which is a bit surprising considering this is a common hurdle in larger projects.

This is where a technique called “currying” comes into play (and incidentally, it’s the main reason we wrote this article, as this solution isn’t widely known). Kudos to @Ryan Braun for devising this approach as we encountered the problem.

What is “currying”?

Currying is a technique in functional programming where a function with multiple arguments is transformed into a sequence of functions, each with a single argument. For instance, a function that takes three parameters, curriedFunction(x, y, z), becomes (x) => (y) => (z) => { /* function body */ }.

Using currying to fix the partial generic parameter inference limitation

Currying can be a solution to this problem. By splitting handleRequest into two parts, each accepting one argument, we allow TypeScript to infer the types in two stages. The first function takes the options argument, and return a function that takes the callback argument. This way, TypeScript has the necessary context to infer the correct type when you call the returned function.

Complete example in TypeScript Playground

type Options = {
  requiresAuthentication?: boolean
  parseBody?: boolean
}

type CallbackOptions<B = never, O extends Options = Options> = {
  request: NextApiRequest
  response: NextApiResponse
} & (O extends { requiresAuthentication: true } ? { userId: string } : object) &
  (O extends { parseBody: true } ? { parsedRequestBody: B } : object)

const handleRequest =
  <O extends Options>(options: O) =>
  <B = never>(callback: (options: CallbackOptions<B, O>) => Promise<void>) =>
  async (request: NextApiRequest, response: NextApiResponse) => {
    // If the user is not found, we can return a response right away.
    const userId = getSessionUserId()

    if (options.requiresAuthentication && !userId) {
      return void response.json({ error: 'missing authentication' })
    }

    // Check if the request's body is valid.
    const parsedRequestBody = options.parseBody
      ? parseNextApiRequestBody(request)
      : undefined

    if (options.parseBody && !parsedRequestBody) {
      return void response.json({ error: 'invalid payload' })
    }

    return callback({
      request,
      response,
      ...(options.parseBody ? { parsedRequestBody } : {}),
      ...(options.requiresAuthentication ? { userId } : {}),
    } as CallbackOptions<B, O>)
  }

In this manner, we adhere to the “all or nothing” principle (or is it a limitation?) of TypeScript. We can use the same wrapper to parse a request body:

export default handleRequest({ parseBody: true })<{
  hello: string
}>(async (options) => {
  // some API code here...
})

Or verify if a user is logged in:

export default handleRequest({ requiresAuthentication: true })(
  async (options) => {
    // some API code here...
  }
)

The main drawback of this approach is that the syntax might seem a bit odd, particularly for those not familiar with currying. If you plan to use this, consider adding a comment to explain the rationale behind the implementation. This can prevent someone from wasting hours trying to refactor the wrapper.

Conclusion

TypeScript has emerged as a rising star in programming language surveys, yet a considerable number of developers still prefer to use standard JavaScript. TypeScript can be quite powerful, but it can also prove frustrating when it doesn’t behave as expected. It’s easy to complain about the limitations of TypeScript, but as we’ve seen, there are often creative ways to solve problems and maximize the benefits of TypeScript. At the end of the day, TypeScript can help prevent bugs during development and can be easier to use when multiple developers are working on the same project. Knowing these kinds of tricks can significantly enhance the experience of working with TypeScript.

Dynamic SVG images using Next.js

Nicolas Bouvrette — Sat, 17 Jun 2023 23:59:15 +0000

SVG has emerged as a dominant image format, offering unparalleled flexibility and scalability for today’s web development landscape. From its humble beginnings to its widespread adoption, SVG has undergone significant evolution and now plays a pivotal role in shaping the modern web.

What are SVG files used for?

SVG, or Scalable Vector Graphics, was first introduced in 1999 as a web standard by the World Wide Web Consortium (W3C). Since then, it has experienced significant advancements and widespread adoption within the web development community.

Unlike raster images, which are composed of pixels and can lose quality when resized, SVG images are composed of scalable vector shapes defined by mathematical equations. This vector-based format ensures that SVG images retain their clarity and sharpness regardless of the display size, making them ideal for responsive and high-resolution interfaces.

In a nutshell, SVG images are ideal for:

Icons
Logos
Illustrations

Tools and Techniques

Before diving into the code example, it’s important to familiarize yourself with the available tools. Not all tools are created equal, and if you’re committed to standardizing your SVG files for dynamic manipulation, it’s crucial to be aware of the right tools for the job.

Vector Magic: Converting PNG to SVG

When it comes to converting PNG images to SVG, Vector Magic stands out as a reliable tool with a long-standing reputation. While Vector Magic is not free, its automatic vectorization capabilities have made it a go-to choice for many designers and developers. It’s worth noting that it also supports other raster image formats like JPG, BMP, and GIF. With a few simple steps, you can convert bitmap images to high-quality SVG vectors.

However, it’s important to consider certain factors when converting images to SVG. Highly detailed images may result in a larger file size in the SVG format compared to the raster image. Due to the nature of vector graphics, some complex images may not translate as effectively, potentially impacting the overall quality of the resulting SVG.

Inkscape: A Free SVG Editing Software

Inkscape is a versatile and powerful open-source vector graphics editor that excels at editing SVG images. It offers a comprehensive set of tools for creating and modifying SVGs, including drawing, text manipulation, and object transformations. Inkscape also allows for precise editing at the individual node level, making it an excellent choice when precision edits are necessary. While Inkscape provides a rich feature set, it’s important to note that working with complex operations or large files may require additional system resources. Additionally, keep in mind that Inkscape has certain limitations in terms of performance and file handling.

Figma: Smart Resizing Capabilities

Figma, primarily known as a collaborative design tool, also offers robust capabilities for working with SVG images. While not specifically marketed as an SVG editor, Figma provides an intuitive interface and powerful features that make it a viable option for manipulating SVGs. It’s worth mentioning that Figma’s SVG editing capabilities are not as extensive as dedicated tools like Inkscape. However, Figma excels in its ability to resize SVG images without having to rely heavily on the transform attribute. This makes Figma a valuable complement to Inkscape, particularly if you are looking to keep the size consistent across images of the same type (e.g., icons).

Free SVG Assets Online

In addition to creating and editing SVG images, it’s often beneficial to leverage existing SVG assets to enhance your designs. Fortunately, numerous sources offer free SVG assets online. Websites such as SVG Repo, Freepik, and Flaticon provide extensive collections of high-quality SVG icons, illustrations, and other graphical resources that can serve as a starting point or inspiration for your SVG creations.

Optimization Tools for SVG Images

In addition to the techniques we’ve discussed so far, there are optimization tools available that can further enhance SVG images. These tools, such as SVGO and ImageOptim, offer valuable features to reduce file size and clean up SVG markup, making it easier to standardize and optimize the overall performance of SVG assets.

SVGO (SVG Optimizer) is a popular tool known for its ability to optimize SVG files. It analyzes the markup and applies various techniques to reduce unnecessary code and optimize the structure of the SVG. By eliminating redundant elements, attributes, and whitespace, SVGO helps reduce file size without compromising the visual quality of the image. It’s like a magic wand that streamlines your SVGs and makes them lighter, ready to be delivered to your users at lightning speed.
ImageOptim, on the other hand, is a versatile optimization tool that supports a wide range of image formats, including SVG. It employs advanced compression algorithms to squeeze out every unnecessary byte from your SVG files, resulting in smaller file sizes. By reducing the file size, you not only enhance the loading speed of your web pages but also save precious bandwidth, making your website more efficient and eco-friendly. Plus, ImageOptim has a friendly interface that makes the optimization process enjoyable and effortless.
Vector Magic offers a lesser-known technique to further reduce the size of SVG images. SVG files can sometimes turn out larger than expected, even after applying other optimization methods. One clever “hack” involves converting the SVG image back to a PNG file and then re-processing it through Vector Magic with different settings. By selectively reducing the level of detail during the conversion, you can achieve remarkable size reductions. I’ve witnessed SVG images being compressed by up to 60% using this advanced technique.

Making SVG images Dynamic

Next.js comes with an image component that supports both traditional raster images like PNG and SVG files. It uses the <img> HTML tags and loads the images from the public directory, which works well for static images like illustrations. However, if you want to make SVG images dynamic, you have a few options to consider.

What are the options to make SVG images dynamic?
One popular approach is to create SVG components using JSX. Here’s an example:

const CheckMarkComponent: React.FC<{
  color?: string;
  strokeWidth?: string;
}> = ({ color, strokeWidth }) => {
  return (
    <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
      <g
        fill="none"
        stroke={color ?? "black"}
        strokeLinecap="round"
        strokeLinejoin="round"
        strokeWidth={strokeWidth ?? "1px"}
        transform="matrix(1,0,0,1,0,0)"
      >
        <path d="M23.25.749,8.158,22.308a2.2,2.2,0,0,1-3.569.059L.75,17.249" />
      </g>
    </svg>
  );
};

The benefit of this approach is that you have more flexibility to customize the SVG since it becomes a React component. However, there’s a drawback: it’s no longer a standalone SVG image. This means you won’t have the convenience of basic tools like SVG previews or thumbnail browsing in directories. It also makes editing the image a bit more cumbersome, as you’ll need to copy and paste between different tools.

As you may have noticed in this example, the attributes (e.g., strokeLinecap) are also converted to camelCase. This is because snake-case is not compatible with JSX format. Depending on the attributes you're using, converting between this format and the traditional SVG format can become quite complex.

Considering these limitations, I suggest using the SVGR Webpack loader, which allows you to import SVG images directly into your Node.js application.

⚠ It’s important to note that when using this solution, the SVG images will be imported directly into your JavaScript bundles. As a result, the overall page size will increase compared to the native Next.js version that loads images asynchronously. For this reason, I don’t recommend using this solution for large illustrations unless they require dynamic functionality. However, it’s an excellent solution for icons since they become part of the page, eliminating any flickering during image loading.

Getting started

As we delve into this discussion, it’s important to know that we’ve conveniently made the solutions discussed in this article accessible via our GitHub repository. This will allow you to engage more practically with the topics we explore.

Now, in order to transform SVG images within your Next.js application, our first step involves installing the SVGR Webpack loader. To do this, open your terminal and execute the following command:

npm i @svgr/webpack --save-dev

Next, we need to configure Next.js (next.config.js) to recognize the SVGR Webpack loader when importing SVG files. Add the following code to your next.config.js file:

/** @type {import('next').NextConfig} */
const nextConfig = {};

nextConfig.webpack = (config, context) => {
  config.module.rules.push({
    test: /\.svg$/,
    use: "@svgr/webpack",
  });
  return config;
};

module.exports = nextConfig;

Now, to ensure TypeScript recognizes the imported SVG files properly, we’ll create a global.d.ts file at the root of your project (if you don’t already have another type file you’re using). Add the following declaration to the global.d.ts file:

// Allow TypeScript to import SVG files using Webpack's `svgr` loader.
declare module "*.svg" {
  import React from "react";
  const content: React.FC<React.SVGProps<SVGSVGElement>>;
  export default content;
}

In order to eliminate the necessity of adding boilerplate code across our examples, we will be utilizing the following two files located under the /app directory of our Next.js project:

layout.tsx

import "./global.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body
        style={{
          position: "absolute",
          padding: 0,
          margin: 0,
          height: "100%",
          width: "100%",
        }}
      >
        <div
          style={{
            display: "flex",
            flexDirection: "row",
            justifyContent: "center",
            alignItems: "center",
            minHeight: "100%",
            height: "auto",
          }}
        >
          <div style={{ margin: "10%" }}>{children}</div>
        </div>
      </body>
    </html>
  );
}

global.css

svg {
  width: 100%;
}

Now that we have the basic setup ready, let’s test it out by creating a new page under the /app directory. Unlike the Next.js <Image> component, we don’t need to place the SVG file in the /public directory. Instead, we can import the SVG files directly into the pages.

To begin, let’s create a new directory named check-mark and add a new SVG image called CheckMark.svg with the following markup:

<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <g
    fill="none"
    stroke="currentColor"
    stroke-linecap="round"
    stroke-linejoin="round"
    stroke-width="currentStrokeWidth"
    transform="matrix(1,0,0,1,0,0)"
  >
    <path d="M23.25.749,8.158,22.308a2.2,2.2,0,0,1-3.569.059L.75,17.249" />
  </g>
</svg>

Next, we can create a new file named page.tsx to display the SVG file:

import CheckMark from "./CheckMark.svg";

export default function CheckMarkPage() {
  return <CheckMark />;
}

Now, if we start Next.js and load the page, we should see a black check mark in the center.

Adding dynamism

If you’ve been paying attention to the SVG images, you might have noticed a special value used for the stroke attribute: currentColor. This value is not exclusive to SVG images but is a CSS value that can be utilized in various contexts, including SVG. It refers to the value of the color property of the element that is currently being styled.

In the case of SVG, the stroke property determines the color of the outline or stroke of a shape or path. When you set stroke="currentColor", you’re instructing the SVG element to use the same color as its parent element.

This means that if you set the color of the parent <div> to red, the <CheckMark> element, the SVG image, will also become red. This is particularly handy when using SVG images as icons embedded within text. In most designs, icons share the same color as the text. However, if you ever need to use a different color, you can specify it directly on the SVG component like this:

<CheckMark color={"green"} />

This feature is incredibly powerful because it allows you to dynamically select the exact color you need from the same SVG file without duplicating it. You can also apply this technique to almost every supported property.

Another common use case is modifying the stroke width. By default, you can have a small stroke width that works well for icons, but you might need to adjust it if you want to reuse the same image in a larger format.

Let’s try modifying the stroke width of the image:

<CheckMark strokeWidth={"5px"} color={"blue"} />

As expected, this changes the stroke width. However, now we encounter a new problem—the SVG image is larger than its viewbox, and it appears truncated.

Fixing truncated images

Unfortunately, there is no concept of margin for SVG viewboxes. However, there is a way to fix this issue by resizing the viewbox and using negative values to center the image. Luckily, we have already created a component to handle this. You can create the helper function under the /src directory and name it SvgMargin.ts:

import React from "react";

/**
 * Type guard to check if a React node is a functional component.
 *
 * @param node - A React node to check.
 *
 * @returns True if it's a functional component, otherwise false.
 */
const isFunctionalComponent = (
  node: React.ReactNode
): node is React.FunctionComponentElement<React.SVGProps<SVGSVGElement>> => {
  return (
    node !== null &&
    typeof node === "object" &&
    "type" in node &&
    typeof node.type === "function"
  );
};

/**
 * Get the name of a component.
 *
 * @param component - A component.
 *
 * @returns The component name.
 */
const getComponentName = (component: React.ReactElement) =>
  typeof component.type === "string"
    ? component.type
    : (component?.type as React.FunctionComponent)?.displayName ||
      component?.type?.name ||
      "Unknown";

/**
 * Component to add margin around an SVG image.
 */
export const SvgMargin: React.FC<{
  children: React.ReactElement<React.SVGProps<SVGSVGElement>>;
  /** The size of the margin to apply to the SVG image (e.g., 5 will be 5% of the image height/width). */
  size: number;
}> = ({ children, size: marginRatio }) => {
  if (!isFunctionalComponent(children)) {
    return children;
  }

  const SvgComponent = children.type({});

  if (!React.isValidElement<React.SVGProps<SVGSVGElement>>(SvgComponent)) {
    return children;
  }

  const viewBox =
    children?.props?.viewBox ?? SvgComponent?.props?.viewBox ?? "";

  const [x, y, width, height] = viewBox
    .split(" ")
    .map((value) => parseFloat(value));

  if ([x, y, width, height].some((val) => val == null || isNaN(val))) {
    console.error(
      `missing viewBox property for svg ${getComponentName(SvgComponent)}`
    );
    return children;
  }

  const margin = marginRatio / 100;

  // Calculate new x and width values.
  const widthMargin = width * margin;
  const newX = x - widthMargin;
  const newWidth = width + 2 * widthMargin;

  // Calculate new y and height values.
  const heightMargin = height * margin;
  const newY = y - heightMargin;
  const newHeight = height + 2 * heightMargin;

  return React.cloneElement(
    SvgComponent,
    {
      ...children.props,
      viewBox: `${newX} ${newY} ${newWidth} ${newHeight}`,
    },
    SvgComponent.props.children
  );
};

We can use it like this:

import CheckMark from "./CheckMark.svg";
import { SvgMargin } from "@/src/SvgMargin";

export default function CheckMarkPage() {
  return (
    <SvgMargin size={10}>
      <CheckMark strokeWidth={"5px"} color={"blue"} />
    </SvgMargin>
  );
}

And the output:

Controlling shapes and paths independently

The current solution we just demonstrated works for the most common use case. It allows you to change properties for the entire SVG image. However, it has a limitation: you can only change each property to a single value. This means that if you change the color property, it will apply to all shapes and paths that use the currentColor. So, how can we achieve more control?

There are three primary solutions to gaining more control:

Use inline (in the SVG file) <style>
Use Next.js’ built-in CSS modules
Use another helper function

1) Using inline style

Using inline styles is a straightforward option that allows you to leverage the SVG’s inline style capabilities, similar to HTML CSS. The main difference is that the SVGR loader, by default, renames both the class names and id properties to avoid collisions with HTML styles. However, this renaming process occurs behind the scenes, and you’ll only see the end result when inspecting the SVG within your browser. To understand how this works, let’s create a new directory called circles-inline-style and add a new SVG file called CirclesInlineStyle.svg:

<svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
  <style>
    /** Ocean breeze */
    svg[data-color-mode="oceanBreeze"] #top-right-circle {
      fill: DeepSkyBlue;
    }

    svg[data-color-mode="oceanBreeze"] #top-left-circle {
      fill: MediumAquaMarine;
    }

    svg[data-color-mode="oceanBreeze"] #bottom-right-circle {
      fill: CornflowerBlue;
    }

    /** Sunset glow */
    svg[data-color-mode="sunsetGlow"] #top-right-circle {
      fill: Coral;
    }

    svg[data-color-mode="sunsetGlow"] #top-left-circle {
      fill: Gold;
    }

    svg[data-color-mode="sunsetGlow"] #bottom-right-circle {
      fill: DarkOrange;
    }
  </style>
  <g transform="matrix(1,0,0,1,0,0)">
    <!-- Top-left circle -->
    <circle id="top-left-circle" fill="black" cx="50" cy="50" r="40" />
    <!-- Top-right circle -->
    <circle id="top-right-circle" fill="black" cx="150" cy="40" r="30" />
    <!-- Bottom-right circle -->
    <circle id="bottom-right-circle" fill="black" cx="150" cy="150" r="20" />
  </g>
</svg>

In this example, we’ve added id properties to all circles, allowing us to target them individually within the <style> tag. I’ve defined two “color modes” called oceanBreeze and sunsetGlow. You can set the color mode by adding a data-color-mode property to the <svg> element. To preview the SVG and see the live result, you can install an SVG preview plugin for VSCode or use other similar tools. For example, to view the SVG with the oceanBreeze color mode, modify the code as follows:

<svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg" data-color-mode="oceanBreeze">
    <!-- Rest of the SVG file... -->
</svg>

To control the color mode using React, let’s create a new page.tsx in a directory named circles-inline-style:

import CirclesInlineStyle from "./CirclesInlineStyle.svg";

export default function CirclesInlineStylePage() {
  return <CirclesInlineStyle data-color-mode="sunsetGlow" />;
}

The resulting SVG will display the circles with the expected colors:

⚠ Be cautious when using inline styles, as different browsers may produce varying results. Make sure to test carefully. Additionally, setting styles on elements like <mask> or using advanced CSS may lead to cross-browser issues. Sticking to basic styles will help avoid these problems.

2) Using Next.js’ built-in CSS modules

To implement this approach, let’s create a new page in a directory called circles-css-module. Within this directory, we’ll create a new CSS module file named circles.module.css:

/** Ocean breeze */
.oceanBreeze [data-node-id="top-right-circle"] {
  fill: DeepSkyBlue;
}

.oceanBreeze [data-node-id="top-left-circle"] {
  fill: MediumAquaMarine;
}

.oceanBreeze [data-node-id="bottom-right-circle"] {
  fill: CornflowerBlue;
}

/** Sunset glow */
.sunsetGlow [data-node-id="top-right-circle"] {
  fill: Coral;
}

.sunsetGlow [data-node-id="top-left-circle"] {
  fill: Gold;
}

.sunsetGlow [data-node-id="bottom-right-circle"] {
  fill: DarkOrange;
}

In this CSS module file, we define different selectors for the color modes “oceanBreeze” and “sunsetGlow”. Instead of using the id selector, we use attribute selectors with data-node-id. This is because the SVGR loader removes any id attributes from elements when inline styles are not used, to avoid collisions with the parent HTML document.

Next, let’s create a new SVG file named CirclesCssModule.svg in the same directory. This SVG file will be identical to the one used in the inline style approach but without the <style> tag. Also, we’ll use data-node-id attributes instead of id to identify the circles:

<svg viewBox="0 0 200 200" xmlns="http://www.w3.org/2000/svg">
  <g transform="matrix(1,0,0,1,0,0)">
    <!-- Top-left circle -->
    <circle data-node-id="top-left-circle" fill="black" cx="50" cy="50" r="40" />
    <!-- Top-right circle -->
    <circle data-node-id="top-right-circle" fill="black" cx="150" cy="40" r="30" />
    <!-- Bottom-right circle -->
    <circle data-node-id="bottom-right-circle" fill="black" cx="150" cy="150" r="20" />
  </g>
</svg>

Now, let’s create a new page.tsx file where we can import the SVG component and apply the CSS module:

import CirclesCssModule from "./CirclesCssModule.svg";
import styles from "./circles.module.css";

export default function CirclesCssModulePage() {
  return <CirclesCssModule className={styles.sunsetGlow} />;
}

In this example, we import the CirclesCssModule component from the CirclesCssModule.svg file. We also import the generated CSS module file styles that contain the class names for the color modes.

By applying the styles.sunsetGlow class name as a prop to the CirclesCssModule component, we can dynamically set the color mode.

The resulting SVG will appear the same as the inline style approach but with the advantage of being able to separate the CSS into a style sheet. This means you can utilize additional features like Sass, which is not natively supported within SVG files.

However, one drawback of this approach is that you can no longer preview the styles using standard preview tools since React is required to apply the styles dynamically.

3) Using a helper function

If predefining styles isn’t an option for you and you’re seeking greater flexibility, using a wrapping component may be your only remaining option. We’ve already created such a component to demonstrate how this can be achieved. However, please note that due to the nature of SVGR imports, this is not entry-level code. You can create the helper function under the /src directory and name it SvgController.ts:

import React from "react";

type ExtendedSVGProps = React.SVGProps<SVGSVGElement> & {
  [attr: string]: string;
};

type ControlRule = {
  selector: {
    attributeName: string;
    attributeValue: string;
  };
  props: React.SVGProps<SVGSVGElement>;
};

type ControlRules = ControlRule[];

/**
 * Get an object that indexes control rules.
 *
 * @param rules - The control rules.
 *
 * @returns An object that indexes control rules.
 */
const getPropsSelectorIndex = (
  rules: ControlRules
): { [key: string]: React.SVGProps<SVGSVGElement> } => {
  return rules.reduce((acc, config) => {
    const { attributeName, attributeValue } = config.selector;
    acc[attributeName + ":" + attributeValue] = config.props;
    return acc;
  }, {} as { [key: string]: React.SVGProps<SVGSVGElement> });
};

/**
 * Clone a React node and its children while trying to inject new props.
 *
 * @param node - The node to clone.
 * @param propsSelectorIndex - An object that indexes control rules.
 *
 * @returns The cloned node with new props when applicable.
 */
const cloneNode = (
  node: React.ReactElement<ExtendedSVGProps>,
  propsSelectorIndex: { [key: string]: React.SVGProps<SVGSVGElement> }
): React.ReactElement<ExtendedSVGProps> => {
  const { children, ...restProps } = node.props;
  let nodeProps: Partial<ExtendedSVGProps> & React.Attributes = {
    ...restProps,
  };

  const matchingProps =
    propsSelectorIndex[
      Object.entries(nodeProps).find(
        ([key, value]) => propsSelectorIndex[key + ":" + value]
      )?.[0] +
        ":" +
        Object.entries(nodeProps).find(
          ([key, value]) => propsSelectorIndex[key + ":" + value]
        )?.[1]
    ];

  if (matchingProps) {
    const compatibleProps = Object.entries(matchingProps).reduce(
      (acc, [propKey, propValue]) => {
        if (typeof propValue === "string") {
          acc[propKey] = propValue;
        }
        return acc;
      },
      {} as ExtendedSVGProps
    );
    nodeProps = { ...nodeProps, ...compatibleProps };
  }

  const clonedChildren = React.Children.map(children, (child) =>
    React.isValidElement<ExtendedSVGProps>(child)
      ? cloneNode(child, propsSelectorIndex)
      : child
  );

  return React.cloneElement(node, nodeProps, clonedChildren);
};

/**
 * Type guard to check if a React node is a functional component.
 *
 * @param node - A React node to check.
 *
 * @returns True if it's a functional component, otherwise false.
 */
const isFunctionalComponent = (
  node: React.ReactNode
): node is React.FunctionComponentElement<React.SVGProps<SVGSVGElement>> => {
  return (
    node !== null &&
    typeof node === "object" &&
    "type" in node &&
    typeof node.type === "function"
  );
};

/**
 * Component to control the internal nodes of an SVG image.
 */
export const SvgController: React.FC<{
  rules: ControlRules;
  children: React.ReactElement<ExtendedSVGProps>;
}> = ({ rules, children }) => {
  if (!isFunctionalComponent(children)) {
    return children;
  }

  const SvgComponent = children.type({});
  const propsSelectorIndex = getPropsSelectorIndex(rules);

  return React.isValidElement<ExtendedSVGProps>(SvgComponent)
    ? cloneNode(SvgComponent, propsSelectorIndex)
    : children;
};

What this component does is that it deconstructs the child React element provided by SVGR Webpack and then scans for any matching rules to inject the desired props. The main benefit of this approach is the ability to dynamically specify the injected color instead of predefining them in a style sheet. However, there may be a drawback in terms of performance. Although I haven’t benchmarked this function, it is possible that heavy usage could lead to performance issues.

Now, let’s see it in action! First, create a new directory called circles-helper-function where we can add a new SVG image named CirclesHelperFunction.svg. Use the same SVG markup as the one used by the CSS module (CirclesCssModule.svg).

Next, let’s create a new page.tsx file to demonstrate how the helper function can be utilized:

"use client";

import { useEffect, useState } from "react";
import CirclesHelperFunction from "./CirclesHelperFunction.svg";
import { SvgController } from "@/src/SvgController";

const getRandomColor = () =>
  "#" + Math.floor(Math.random() * 16777215).toString(16);

export default function CirclesHelperFunctionPage() {
  const [topLeftCircleColor, setTopLeftCircleColor] = useState("none");
  const [topRightCircleColor, setTopRightCircleColor] = useState("none");
  const [bottomLeftCircleColor, setBottomLeftCircleColor] = useState("none");

  useEffect(() => {
    const interval = setInterval(() => {
      setTopLeftCircleColor(getRandomColor());
      setTopRightCircleColor(getRandomColor());
      setBottomLeftCircleColor(getRandomColor());
    }, 100);

    return () => clearInterval(interval);
  }, []);

  return (
    <>
      <SvgController
        rules={[
          {
            selector: {
              attributeName: "data-node-id",
              attributeValue: "top-left-circle",
            },
            props: { fill: topLeftCircleColor },
          },
          {
            selector: {
              attributeName: "data-node-id",
              attributeValue: "top-right-circle",
            },
            props: { fill: topRightCircleColor },
          },
          {
            selector: {
              attributeName: "data-node-id",
              attributeValue: "bottom-left-circle",
            },
            props: { fill: bottomLeftCircleColor },
          },
        ]}
      >
        <CirclesHelperFunction />
      </SvgController>
    </>
  );
}

Because the color of each circle is tracked as a state, every time useEffect changes the color, the SvgController component is updated, which then propagates those changes to the CirclesHelperFunction component.

This approach allows you to use a standard SVG file and control all of its nodes using standard React code.

Using the components provided in this article

While we’ve provided useful components in this article, it’s important to understand that they should be used with caution.

The main challenge I faced when creating these components was due to the SVGR Webpack loader returning a functional component that doesn’t offer the same extended capabilities as the original component. This means that, to add these capabilities, we have to use APIs like React.cloneElement, which is not recommended by React. I even had to go a step further and invoke the functional component using .type(), an internal React API not documented in the official React resources.

The “proper” approach to creating these components would likely involve writing a wrapper for the SVGR webpack loader, enabling the same manipulations directly from the imported component.

That being said, while generally it is advised against using cloneElement or internal APIs, the risk is relatively low in this specific use case given the widespread usage of React.

If you prefer to err on the side of caution, all the other examples presented without using these components are safe to use and already offer sufficient flexibility for most common use cases.

Conclusion

In conclusion, the information shared in this article aims to empower you to fully utilize the potential of SVG images. SVGs are incredibly useful for design purposes, especially when combined with popular UI frameworks and tools. This combination allows you to create visually appealing and interactive web experiences. While the focus of this article is mainly on Next.js and React, you can achieve similar results using other technologies by following similar approaches. Ultimately, these techniques work within HTML documents and web browsers, making them universally applicable. So go ahead and dive into using SVGs in your projects using these new tricks, and experience the incredible results they can offer.