Forem: Nicolas Bouvrette

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.