Forem: Nicolas Bouvrette

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.