DEV Community: Mattia Pispisa

Workspaces, react and vite. A real-world case study for managing duplicate libraries.

Mattia Pispisa — Thu, 04 Dec 2025 19:03:14 +0000

Introduction

When organizing a project using npm workspaces, the typical structure consists of a single root package that orchestrates multiple local packages and applications:

my-workspace
  | apps
  |-- client
  |-- server
  | packages
  |-- package-a
     |-- src
     |__ package.json
  |-- package-b
     |-- src
     |__ package.json
  |__ package.json

This architecture promotes modularity and code reuse. However, managing shared dependencies can introduce complexity in module resolution, leading to unexpected behaviors - even at runtime - that can be difficult to diagnose.

To fully understand dependency resolution mechanics and the deduplication strategies we use, we analyze a practical scenario. We use as a case study a frontend application built with react that uses react-router and react-router-dom for routing. These libraries, heavily relying on context, with their specific dependencies will immediately highlight the "structural problems" arising from the presence of multiple versions.

The starting point of our analysis is a blocking runtime error you might have encountered:

"Cannot destructure property 'basename' of 'w.useContext(...)' as it is null"

This error indicates that the component cannot access the router context, despite the presence of a Provider in the component tree (we're not dealing with the issue where we use useLocation before defining the router). The root cause lies in the dependency duplication problem.

In this article we analyze:

how npm handles version resolution;
how vite handles dependency resolution;
how to implement a targeted deduplication strategy (dedupe) using vite.

Analysis: Module resolution in npm

An npm workspace links local packages through symbolic links. The challenge arises when different internal libraries depend on the same external library, but with different version constraints (even compatible ones as we'll see later).

Let's consider the following real-world scenario with two local packages, package-a and package-b that both depend, in different ways, on react-router and react-router-dom.

Dependency configuration:

package-a uses a version range (caret):

// package-a/package.json
{
  "dependencies": {
    "react-router-dom": "^6.21.1"
  }
}

While package-b requires exact versions ("pinned"):

// package-b/package.json
{
  "dependencies": {
    "react-router": "6.30.1",
    "react-router-dom": "6.30.1"
  }
}

In turn, react-router-dom depends on react-router.

// react-router-dom/package.json version 6.30.1
{
  "name": "react-router-dom",
  "version": "6.30.1",
  "dependencies": {
    "react-router": "6.30.1"
  }
}

When npm runs the installation, it attempts in order to resolve dependencies to optimize space (hoisting). However, it must respect semantic constraints:

For package-a, analyzed first, the version ^6.21.1 is resolved to the latest compatible version available, in our case 6.30.2 (as of December 2025). This is installed in the workspace root. react-router-dom at version 6.30.2 depends on react-router at version 6.30.2, so it will also be installed in the workspace root.
For package-b, analyzed second, version 6.30.1 is specifically required. Since it differs from the version in root, npm installs a local copy in packages/package-b/node_modules. Consequently, react-router will also be installed locally in package-b's node_modules at version 6.30.1.

The resulting on-disk structure will be as follows:

The result we get is that, even though we pinned the version of react-router and react-router-dom in package-b's package.json and the versions in package-a are compatible with package-b's versions, we have two different versions of both libraries on disk.

The bundling problem

Before addressing the solution, it's useful to contextualize the role of the bundler. In a modern frontend architecture, the bundler (such as webpack, rollup, or vite) has the task of traversing the application's dependency graph, resolving each import statement, to combine modules and assets into static files optimized for browser execution.

For this analysis, we examine vite, currently a de facto standard for developing react applications, to see how it handles these collisions. By default, if two packages import two different physical sources (lib@1 and lib@2), the bundler will include both versions in the bundle (with increased size).

In our case, the final bundle will include both versions of react-router and react-router-dom with:

increased size;
imports of code at different versions depending on where the code is defined (package-a, package-b).

While this results in an increase in bundle size, the critical problem is functional: react-router cannot function correctly if different versions are used at different points in the code. This will lead to the runtime problem shown in the introduction:

"Cannot destructure property 'basename' of 'w.useContext(...)' as it is null"

Resolution strategies with vite

To solve the problem, it's necessary to force the bundler to use a single instance of the library (deduplication).

One possible solution to resolve the problem is to use overrides in the root project's package.json, specifying the exact versions of dependencies you want to use.

// package.json
{
  "overrides": {
    "react-router": "6.30.1",
    "react-router-dom": "6.30.1"
  }
}

But is this the only way to solve the problem?
No, there are other strategies for deduplication resolution. In our case, we leverage a setting that vite provides for deduplication resolution.

vite resolve.dedupe

vite offers the native resolve.dedupe option to indicate the dependencies you want to deduplicate.

// vite.config.ts
export default {
  resolve: {
    dedupe: ['react-router', 'react-router-dom']
  }
}

However, this option doesn't always produce the desired or expected result.
As indicated in the official documentation, this option forces vite to resolve the listed dependencies always toward the copy present in the project root.

Problem: In our scenario, the root contains version 6.30.2 (resolved from package-a which required version ^6.21.1). While the version we pinned in package-b (which was compatible with package-a's requirement) is present inside package-b's node_modules (packages/package-b/node_modules).
So in our case, the result would be that, even though we've pinned the version of react-router and react-router-dom in package.json to version 6.30.1, the bundler will resolve dependencies toward version 6.30.2 present in the root.

Custom Plugin for Targeted Resolution

To achieve granular control, we can implement a vite plugin that forces resolution toward a specific installation (for example, the local one in package-a), ignoring the standard Node/npm resolution.

Here's an implementation of a plugin that intercepts module resolution and redirects the specified packages:

import fs from 'fs';
import path from 'path';
import { PluginOption } from 'vite';

/**
 * Plugin to force deduplication of specific packages toward
 * a version contained in a defined relative path.
 *
 * @param dedupe - Array of package names to deduplicate (e.g. ['react-router'])
 * @param packagePath - Relative path to the package to use as "source of truth"
 */
const enhancedDedupePlugin = ({
  dedupe,
  packagePath,
}: {
  dedupe: string[]
  packagePath: string
}): PluginOption => {
  return {
    name: 'vite-plugin-enhanced-dedupe',
    enforce: 'pre', // Priority execution over the standard resolver
    resolveId(source, _importer) {
      // Process only packages in whitelist
      if (!dedupe.includes(source)) {
        return null;
      }

      // Build the absolute path toward the target node_modules
      const targetBase = path.resolve(__dirname, packagePath, 'node_modules', source);

      // Verify physical existence of the package in the target path
      if (!fs.existsSync(targetBase)) {
        return null; // Fallback to standard resolution if not found
      }

      // Identify the entry point via package.json
      const packageJsonPath = path.join(targetBase, 'package.json');
      if (!fs.existsSync(packageJsonPath)) {
        return null;
      }

      try {
        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));

        // Priority to ESM ('module'), fallback to 'main' or 'index.js'
        const entryPoint = packageJson.module || packageJson.main || 'index.js';
        const resolvedPath = path.join(targetBase, entryPoint);

        // Return the absolute path to force the use of this specific instance
        return resolvedPath;
      } catch (error) {
        console.warn(`[enhanced-dedupe] Error reading package.json for ${source}:`, error);
        return null;
      }
    },
  }
}

export default enhancedDedupePlugin;

Integration in vite.config.ts:

We can now configure vite to use the versions present in package-b as the single source of truth for react-router:

import { defineConfig } from 'vite'
import enhancedDedupePlugin from './vite-plugin-enhanced-dedupe'

export default defineConfig({
  plugins: [
    enhancedDedupePlugin({ 
      dedupe: ['react-router', 'react-router-dom'], 
      packagePath: '../../packages/package-b' 
    })
  ],
})

With this configuration, the final bundle will include exclusively version 6.30.1 (the one from package-b), ensuring react context consistency and resolving the runtime error.

This solution proves particularly effective in asymmetric scenarios: cases where a local package imposes strict constraints (dependencies "pinned" to exact versions for legacy or stability reasons), while the rest of the workspace adopts more flexible constraints (e.g. with ^ or ~). In such a context, the plugin acts by normalizing the entire project to the most restrictive version, ensuring the constrained package works without requiring manual refactoring of dependencies in other "free" modules.

Note on the official react plugin

It's interesting to note that the official @vitejs/plugin-react plugin has removed automatic deduplication in recent versions. As reported in the official changelog, the automation often caused side effects that were difficult to track in complex monorepo architectures. This confirms the need for a manual and conscious approach to managing critical dependencies.

Conclusion

Managing dependencies in npm workspaces environments requires attention, especially with libraries that "orchestrate" the entire application. While npm tends to preserve semantic correctness by installing multiple versions, this behavior is incompatible with the runtime operation of some libraries. Through the use of custom plugins in vite, it's possible to achieve the necessary determinism, forcing resolution toward specific versions and ensuring application stability.

Go router navigation observer

Mattia Pispisa — Sat, 17 May 2025 18:09:36 +0000

go_router is one of the most popular package for managing navigation in a Flutter application, and since it became part of the Flutter team, it has become the main recommended solution.

It's very easy to use, yet feature-rich.

However, with the introduction of ShellRoute, observing the navigation flow in your app and having routes that are "aware" of navigation changes has become more difficult. As highlighted in this issue, when you add a ShellRoute, the app loses reactivity to route changes: the NavigationObserver is no longer triggered.

While waiting for an official fix or built-in solution from the Flutter team, we can still implement route-aware behavior by listening to the GoRouterDelegate.

The following code listens to the GoRouterDelegate throughout the widget's lifecycle and uses internal state along with top-route comparison to expose callbacks in response to navigation events. Of course, this can be extended to fit your needs—for example, reacting to query parameter changes and more.

import 'package:flutter/material.dart';
import 'package:go_router/go_router.dart';

/// A mixin that allows a widget to be aware of the current route.
mixin GoRouterAware<T extends StatefulWidget> on State<T> {
  /// The route to be aware of.
  late final Uri _observerLocation;

  /// The current state of the [_observerLocation].
  late _GoRouterAwareState _state;

  /// go router delegate.
  late GoRouterDelegate _delegate;

  /// The context of the widget.
  late BuildContext _context;

  /// The location of the top route
  Uri? _currentLocation;

  @override
  void initState() {
    _context = context;

    final router = GoRouter.of(_context);

    _state = _GoRouterAwareState.topRoute;
    _observerLocation = router.state.uri;
    _delegate = router.routerDelegate;

    _onChange();
    _delegate.addListener(_onChange);
    super.initState();
  }

  @override
  void didChangeDependencies() {
    _context = context;
    super.didChangeDependencies();
  }

  void _onChange() {
    _currentLocation = GoRouter.of(_context).state.uri;

    if (_currentLocation == null) {
      return;
    }

    /// If the current route is the top route and the current location is the same as the observer location then [_observerLocation] is the top route.
    if (_state.isTopRoute &&
        _sameLocation(_currentLocation!, _observerLocation)) {
      didPush();
      return;
    }

    /// If the current route is pushed next and the current location is the same as the observer location then [_observerLocation] is returned to the top route.
    if (_state.isPushedNext &&
        _sameLocation(_currentLocation!, _observerLocation)) {
      didPopNext();
      _state = _GoRouterAwareState.topRoute;
      return;
    }

    /// If the current route is not the top route and the current location contains the observer location then [_observerLocation] is no longer the top route.
    if (!_sameLocation(_currentLocation!, _observerLocation) &&
        _currentLocation!.path.toString().contains(_observerLocation.path)) {
      _state = _GoRouterAwareState.pushedNext;
      didPushNext();
      return;
    }

    /// If the current route is the top route and the current location does not contain the observer location then [_observerLocation] is popped off.
    if (_state.isTopRoute &&
        !_currentLocation!.path.toString().contains(_observerLocation.path)) {
      didPop();
      _state = _GoRouterAwareState.poppedOff;
      return;
    }
  }

  /// Check if two locations have the same path.
  bool _sameLocation(Uri a, Uri b) {
    return a.path.toString() == b.path.toString();
  }

  /// Called when the top route has been popped off, and the current route
  /// shows up.
  void didPopNext() {}

  /// Called when the current route has been pushed.
  void didPush() {}

  /// Called when the current route has been popped off.
  void didPop() {}

  /// Called when a new route has been pushed, and the current route is no
  /// longer visible.
  void didPushNext() {}

  @override
  void dispose() {
    _delegate.removeListener(_onChange);
    super.dispose();
  }
}

enum _GoRouterAwareState {
  pushedNext,
  topRoute,
  poppedOff;

  bool get isTopRoute => this == topRoute;
  bool get isPushedNext => this == pushedNext;
  bool get isPoppedOff => this == poppedOff;
}

github gist link.

Efficient logging in applications

Mattia Pispisa — Sat, 07 Sep 2024 09:20:04 +0000

Introduction

In this post, we'll explore an approach to logging messages of your applications. I'll also conclude with my own package solution for logging messages in dart/flutter applications.

But first of all, what does logging mean?

In the state of art logging is

the act of keeping a log of events that occur in a computer system, such as problems, errors or just information on current operations ...

So it's a crucial activity in computing for monitoring and understanding how a system operates.

But how can we do it?

We can answer this question by answering the following points:

"What should we log?";
"When should we log?";
"Where should we log?".

What should we log?

Even just from the previous explanation, we can find multiple information we should log:

Messages useful for debugging our application;
Error messages to alert us in case of abnormal behavior in our application;
Information about the normal use of the app. This approach is very effective for system verification, especially when providing support to customers where the application isn't showing errors but is still not functioning correctly due to behavioral bugs.

We have seen various purposes for which logging information is essential, which suggests the need for severity levels. These could be, in a simple way: debug, info, and error.

when should we log

We have seen various reasons for logging messages. However, writing them down every time might not always be useful; in fact, it could create noise that would make (for example) error analysis more difficult.
At first, by generalizing the use cases, we might assume that debug messages might only be logged during development (obviously, the other types of errors are also useful during development). Errors should always be logged but in production they take a greater importance. Info messages are useful for system checks or customer support. There will likely be many informational messages in the life of an application, so logging them all the time in production could be counterproductive (due to noise and storage costs). Therefore, it would be better to have flags to enable or disable them as needed (like for the customer support).

Where should we log

The final question is where. During development, it is very convenient to write any type of message to the debug console. However, in production or staging environments, it is very useful to have online systems to send messages, such as Sentry or Grafana, or, where that's not possible, a mechanism for saving them to the file system (or both and other options!).

Combining the "when" with the "where" gives us a matrix of scenarios. Obviously, this matrix doesn’t cover all the real-world cases of an actual application, but it can be a good initial approximation from which to develop a solution. It’s also useful as an intermediate step before analyzing my dart package proposal.

	Development	Production
Debug	Console	X (Enabled with a flag?)
Info	Console	X (Enabled with a flag?)
Error	Console	Online tools, File system, ...

However, only the where and when change; the logs themselves remain the same!

Let's dive into the analysis of my proposal.

It is important to differentiate between the system used to add a new message and the management of where and when these messages are handled (and any additional information).

where the log method of the Logger class will be:

class Logger {
  void log(Severity severity, String message) {
    // iterate through each handler that will manage the log. 
    for (final handler in handlers) {
      handler.log(severity, message);
    }
  }
  ...
}

This approach allows us to have a Logger instance that can be passed throughout the system, while we set up different handlers (implementation of Handler) in a single location, such as during the application's bootstrap phase.

For example, referring to the class diagram, we can add a ConsoleHandler only if we're in development mode, a SentryHandler only in production (and in its log method, we decide to log only if the severity is error) and or a FileSystemHandler that is activated only in production for applications that cannot communicate with external systems like Sentry.

class ConsoleHandler implements Handler {
  void log(Severity severity, String message) {
    developer.log(message)
  }
}

class SentryHandler implements Handler {
  void log(Severity severity, String message) {
    if (severity != Severity.error) {
      return 
    }
    // log message
  }
}

void bootstrap() {
  ...
  final logger = Logger();

  if (isDev()) {
    logger.add(ConsoleHandler());
  }

  if (isProd()) {
    logger.add(SentryHandler());
  }
}

A system like this, which differentiates between loggers and handlers, makes the entire setup highly flexible. Another example, though perhaps less common but still effective, is having a handler within a UI component (AppPageViewHandler) to listen to messages and transform them into interactive widgets. This approach allows for filtering, categorization, and other functionalities.

In Dart, I developed the library en_logger. This library applies the concepts mentioned above, with an extended severity level adhering to syslog levels and many additional features such as: instances, attachments and prefix.

Here’s a practical example (included in the library's example):

void main(List<String> args) async {
  // a custom handler that under the hood use sentry
  final sentry = await SentryHandler.init();

  // default printer configured
  final printer = PrinterHandler()
    ..configure({Severity.notice: PrinterColor.green()});

  // an enLogger with a default prefix format
  final logger = EnLogger(
      defaultPrefixFormat: PrefixFormat(
    startFormat: '[',
    endFormat: ']',
    style: PrefixStyle.uppercaseSnakeCase,
  ))
    ..addHandlers([
      sentry,
      printer,
    ]);

  // debug log
  logger.debug('a debug message');

  // error with data
  logger.error(
    "error",
    data: [
      EnLoggerData(
        name: "response",
        content: jsonEncode("BE data"),
        description: "serialized BE response",
      ),
    ],
  );

  // logger instance with prefix
  final instLogger = logger.getConfiguredInstance(prefix: 'API Repository');
  instLogger.debug('a debug message'); // [API Repository] a debug message
  instLogger.error(
    'error',
    prefix: 'Custom prefix',
  ); // [Custom prefix] a debug message
}

class SentryHandler extends EnLoggerHandler {
  SentryHandler._();

  static Future<SentryHandler> init() async {
    await Sentry.init(
      (options) {
        options.dsn = 'https://example@sentry.io/example';
      },
    );
    return SentryHandler._();
  }

  @override
  void write(
    String message, {
    required Severity severity,
    String? prefix,
    StackTrace? stackTrace,
    List<EnLoggerData>? data,
  }) {
    // just a simple example
    // fine tune your implementation...
    if (severity.atLeastError) {
      Sentry.captureException(message, stackTrace: stackTrace);
      return;
    }
    Sentry.captureMessage(message);
  }
}

Initially, we configure two handlers: PrinterHandler and SentryHandler. After setup, the only reference needed is the logger, which allows us to write new messages. This decouples message handling from the actual logging operations.

With this system, we can decouple our application from external systems by wrapping them within handlers. This way, the application is not tied to external packages and can easily swap them out over time if needed.

Conclusion

I hope this post has been helpful to you. Leave a feedback, and if you're interested, give en_logger a try!

P.S. How to pass the logger instance throughout the system? Check out the post about dependency injection.

Expand your Future, extensions in Dart

Mattia Pispisa — Fri, 12 Apr 2024 21:02:34 +0000

Extend a class

In Dart, you can extend a class to add new class or instance methods.

extension FutureDelayed on Future {
 Future<T> delayed(int milliseconds) {
    return this.then((value) => Future.delayed(Duration(milliseconds: milliseconds), () => value));
  }}

void main() {
  Future<int> futureValue = Future.value(42).delayed(2000);

  futureValue.then((value) {
    print("here after 2 sec!");
  });
}

Extend an async function

In Dart, you can do something even more special!

You can extend functions, and if these functions are asynchronous, you can create something truly remarkable.

Let's dive into some practical and simple demonstrative examples.

retry future

/// This extension enables us to create new methods 
/// for a function that takes a "remainingTimes" parameter 
/// as input and returns a Future with a generic T.
extension Retry<T> on Future<T> Function(int remainingTimes) {
  Future<T> retry(int count) async {
    while (true) {
      try {
        final result = await this(count);
        return result;
      } catch (e) {
        if (count > 0) {
          count--;
        } else {
          rethrow;
        }
      }
    }
  }
}

void main() {
 // wrap "asyncFunc" in an anonymous function 
 // that receive an input "remain" (this(count) written above in "retry")

 // asyncFunc will be retried up to a maximum of 3 times 
 // in case of an error. 
 ((remain) => asyncFunc()).retry(3)
}

count elapsed time

/// This extension enables us to create new methods 
/// for a function without parameters 
/// and returns a Future with a generic T.
extension FutureMeasure<T> on Future<T> Function() {

  Future<T> measure() async {
    Stopwatch stopwatch = Stopwatch()..start();
    try {
      final result = await this();
      return result;
    } catch (e) {
      rethrow;
    } finally {
      stopwatch.stop();
      print(stopwatch.elapsedMilliseconds);
    }
  }
}

void main() {
 // wrap "asyncFunc" in an anonymous function 
 // without parameter

 // will print the elapsed asyncFunc time
 (() => asyncFunc()).measure()
}

This way, it's easy to understand how to create your own extensions that enhance asynchronous functions with specific capabilities tailored for your app.

Flutter, not yet ready for web

Mattia Pispisa — Mon, 11 Dec 2023 23:15:26 +0000

Introduction

I've been developing with Dart/Flutter since its initial stable version. It's my go-to language/framework for mobile app development at work. I've also been working on web applications for years, experimenting with web apps using Dart/Flutter on side projects.

I'm a staunch supporter of Flutter. This post isn't against Flutter but rather an analysis of its current limitations, with hopes to write a post next year titled "Flutter, the primary tool for the web".

Limitations

The context was building a web app for a business (no B2C), so I won't delve into indexing issues or initial load speed. The concern is the performance. The problem arises when you have to write specific code for the platform, in the web case, in javascript.

Interoperability

Unless the project is very straightforward (but then, why use something complex like Flutter? A microframework like might be better, KISS), native code calls will be necessary. Dart offers relatively recent tools like js. In my case, I needed to display high-weight PDFs, even up to 40MB per page. Here, unfortunately, Dart hits its limit.

A PDF viewing engine is intricate, and reinventing the wheel is unnecessary. pdfJs is widely used and well supported for the web. It's apparent that other companies/devs have created packages to display PDFs in Flutter and essentially are native calls to pdfJs. In this case I took syncfusion as an example, syncfusion_pdfviewer_web.

Using this library (like others, as they'll essentially be bindings to pdfJs) is impossible for PDFs that weigh more than a total of 1MB, and even in this case, they don't perform well. The performance isn't even comparable to native. Even with a dedicated worker, the main thread freezes processing (even for a single page) of a PDF, locking the UI not for seconds, but minutes! The same PDF, in a ReactJS app using the same pdfJs library, loads almost instantly without UI freezes.

The tests were conducted on a MacBook Pro 2019 with the following specifications: 2.3 GHz Intel Core i9 8-core processor, graphics card: Intel UHD Graphics 630 1536 MB, and memory: 16 GB 2400 MHz DDR4. With Flutter, it was also impossible to conduct speed benchmarks (obviously in release mode); the only option was to open the activity monitor to forcibly terminate the web page. In any case, to easily test the performance difference, running a Flutter example and a JavaScript example with a heavy PDF is sufficient.

Conclusion

How can we predict what our app will need in the future? Can we be certain we'll never need to communicate with JS to execute computationally heavy code? As of now, I wouldn't suggest initiating a Flutter project for web development unless the previous questions received a fully positive response.

Hopefully, in the future, we can write an article titled 'Flutter, the primary tool for the web.'

Info

Post written in December 2023 using:

Flutter 3.16;
JS version 0.6.7.

React Hooks and Fiber deep diving

Mattia Pispisa — Sat, 28 Oct 2023 12:59:14 +0000

Starting from a code example that had a particular bug will be explored the source code of react focusing especially on hooks and fiber nodes.

Introduction

The idea of this article is to navigate the source code of React to understand the logic behind the “magic” of hooks and fibers. The goal is to ( begin to) understand “where is what” in order to understand what React looks like especially in functionality related to hooks and virtual dom.

When i started to explore the source code, I gave myself a goal.

The goal

One of the hooks I created was the useEnhancedReducer. In a nutshell, a starting point to enhance the React useReducer. Since useReducer is available in React from version 16 I built it using this version (Why limit a functionality only in newer version when older are also compatible?).

If you are interested in what the useEnhancedReducer is I, together with the company where I work: MVLabs, made a talk on it on ReactJs Day 2023.

In one of its early versions this hook had a bug. The bug was that every time an action is dispatched the reducer code were called twice (React 16 has no Strict Mode). The fix was fairly immediate but why there was this problem?

So a great prompt for exploring React’s code is to find the lines that led to this problem.

If you have any doubts about how to test the code in, please see Appendix A.

Let’s begin!

Looking the react source code we can see that the repository is diveded into countless packages. The most interesting ones are: react, react-reconciler, react-dom, shared.

To begin with, I have taken the simplest hook: the useState (but you will see we are not far from the useReducer and hence the useEnhancedReducer) with the simplest possible code:

    function MyReactComponentExample() {
      const [state, setState] = useState(0)

      const increment = () => {
        setState((prev) => prev + 1)
      }

      return ...
    }

Before executing the code, let us first look statically at the react code. Searching “hooks” inside react package we find the ReactHooks.js file and the following code.

    export function useState<S>(initialState: (() => S) | S,): [S, Dispatch<BasicStateAction<S>>] {
      const dispatcher = resolveDispatcher();
      return dispatcher.useState(initialState);
    }

The other hooks are very similar, all call resolveDispatcher and resolveDispatcher return ReactCurrentDispatcher.current.

    export function useReducer<S, I, A>(
      reducer: (S, A) => S,
      initialArg: I,
      init?: I => S,
    ): [S, Dispatch<A>] {
      const dispatcher = resolveDispatcher();
      return dispatcher.useReducer(reducer, initialArg, init);
    }

    function resolveDispatcher() {
      const dispatcher = ReactCurrentDispatcher.current;
      invariant(...);
      return dispatcher;
    }

But where is assigned ReactCurrentDispatcher?

This can be discovered “easly” setting a breakpoint in

    setState((prev) => prev + 1)

and navigating the source code. At the first “step into”, the code will immediately enter inside the react-dom.development.js file. Looking for the same lines of code in the source code, however, we will see that this is written inside the react-reconciler package. Looking on react package there isn’t a reference on react-dom or react-reconciler (excluding tests). How can this be possible?

Here is where shared comes into plays. There is (almost) no coupling between packages. A package share an object with the shared package and other package can use (fill) objects taking them from shared so we know how react can deal with those two. On the other hand for the link between react-dom and rect-reconciler a good article that explain that is: custom react render (In short, react-dom “implements” a react-reconciler configuration but also take a look at the article!).

react-reconciler

Exploring the file ReactFiberHooks.js inside react-reconciler we might notice the Dispatcher definition (the same type of ReactCurrentDispatcher.current we just encountered) and the objects that implement it. There are many of them, at least one for each state in the lifecycle of a React component!

    export type Dispatcher = {
      ...
      useState<S>(initialState: (() => S) | S): [S, Dispatch<BasicStateAction<S>>],
      ...
    };

    ...

    const HooksDispatcherOnMount: Dispatcher = {
      readContext,
      ...
      useState: mountState,
      ...
    };

    const HooksDispatcherOnUpdate: Dispatcher = {
      readContext,
      ...
      useState: updateState,
      ...
    };

To recap: React uses ReactCurrentDispatcher.current which is shared with react-reconciler using shared package. ReactCurrentDispatcher.current is assigned with a different object based on the state of the react component.

Why inside react-reconciler?

React kept in memory a representation of a UI: The virtual Dom. From React docs:

The virtual DOM (VDOM) is a programming concept where an ideal, or “virtual”, representation of a UI is kept in memory and synced with the “real” DOM by a library such as ReactDOM. This process is called reconciliation.
…
React, however, also uses internal objects called “fibers” to hold additional information about the component tree. They may also be considered a part of “virtual DOM” implementation in React.

What are the additional information about the component? Hooks (and more)!

Back to code

Back to code, the first “step into” of the breakpoint put on the line

    setState((prev) => prev + 1)

had stopped the code within the function dispatchAction.

    function dispatchAction(fiber /* MyReactComponentExample */, queue /* [] */, action /* prev => prev + 1*/) {
      ...
    }

Let us analyse the dispatchAction code on the simplest case, thus with queue parameter empty.

An update is defined and action ((prev) => prev + 1) is inserted inside.

    const update: Update<S, A> = {
        ...,
        action, // (prev) => prev + 1
        eagerReducer: null,
        eagerState: null,
        next: (null: any),
      };

A few lines below, since queue is empty, the next state is computed eagerly.

The previous state is taken and the action is called:

    const currentState: S = (queue.lastRenderedState: any); // 0
    const eagerState = lastRenderedReducer(currentState, action); // ((0) => 0 +1 )

    // updating references
    update.eagerReducer = lastRenderedReducer;
    update.eagerState = eagerState;

If the new status is the same as the previous one there is no need to scheduling an update. Else, is necessary to schedule an update which can lead to a re-render and commit phase (this process is not covered in this article).

    if (is(eagerState /* 1 */, currentState /* 0 */)) {
      ...
      return;
    }
    ...

    scheduleUpdateOnFiber(root, fiber, lane);

Ps. guess where is function is defined? shared of course!

How is an hook hooked to a fiber?

Or “How is setState(0) hooked to MyReactComponentExample?”

We have seen how a setState is executed but how is the useState connected to a fiber?

Put a breakpoint on the instruction

    const [state,setState] = useState(0)

On the first “step into” the code will reach the mountState function.*

    function mountState<S>(
      initialState: (() => S) | S,
    ): [S, Dispatch<BasicStateAction<S>>] {
      const hook = mountStateImpl(initialState); // see below impl.
      const queue = hook.queue;
      const dispatch: Dispatch<BasicStateAction<S>> = (dispatchSetState.bind(
        null,
        currentlyRenderingFiber,
        queue,
      ): any);
      queue.dispatch = dispatch;
      return [hook.memoizedState, dispatch];
    }

    // React 18, in React 16 was a single function
    function mountStateImpl<S>(initialState: (() => S) | S): Hook {
      const hook = mountWorkInProgressHook(); // see below impl.
      ...
      hook.memoizedState = hook.baseState = initialState;
      const queue: UpdateQueue<S, BasicStateAction<S>> = {
        pending: null,
        lanes: NoLanes,
        dispatch: null,
        lastRenderedReducer: basicStateReducer,
        lastRenderedState: (initialState: any),
      };
      hook.queue = queue;
      return hook;
    }

    function mountWorkInProgressHook(): Hook {
      const hook: Hook = {
        memoizedState: null,

        baseState: null,
        baseQueue: null,
        queue: null,

        next: null,
      };

      if (workInProgressHook === null) {
        // This is the first hook in the list
        currentlyRenderingFiber.memoizedState = workInProgressHook = hook;
      } else {
        // Append to the end of the list
        workInProgressHook = workInProgressHook.next = hook;
      }
      return workInProgressHook;
    }

Thus:

A fiber stores an hook within the memoizedState key.
An hook has a reference to the next hook (next key).

    if (workInProgressHook === null) {
        currentlyRenderingFiber.memoizedState = workInProgressHook = hook;
    } else {
        workInProgressHook = workInProgressHook.next = hook;
    }

Each hook has a queue where it contains the pending action (pending), the currently rendered state (lastRenderedState) and more data.

    const queue: UpdateQueue<S, BasicStateAction<S>> = {
      pending: null,
      lastRenderedState: (initialState: any),
      ...
    };

Back to setState

Now that we have seen how an hook is initialized and hooked to a fiber, we can return to the execution of the instruction increment.

    const increment = () => {
        setState((prev) => prev + 1)
    }

The fiber will look like:

    fiber: FiberNode {
      child: ...
      memoizedState: {
        ...
        next: null,
        queue: {
          ...
          lastRenderedState: 0,
          pending: {
            action: prev => prev + 1,
            ...
          }
        }
      }
    }

What if the code was this instead

    ...
    const [state,setState] = useState(0)
    const [secondState,setSecondState] = useState("0")

    const increment = () => {
        setState((prev) => prev + 1)
        setSecondState((prev) => prev + "2")
    }

Inside the dispatchAction of setState((prev) => prev + 1):

    fiber: FiberNode {
      child: ...
      memoizedState: { // "A fiber stores an hook within the memoizedState key"
        ...
        next: { // "An hook has a reference to the next hook (next key)"
          ...,
          lastRenderedState: "0",
          pending: null,
        },
        queue: { // now the queue is no more empty
          ...
          lastRenderedState: 0,
          pending: {
            action: prev => prev + 1,
            ...
          }
        }
      }
    }

Inside the dispatchAction of setSecondState ((prev) => prev + “2”):

    fiber: FiberNode {
      child: ...
      memoizedState: {
        ...
        next: {
          ...,
          lastRenderedState: "0",
          pending: { // setSecondState((prev) => prev + "2") in pending
            action: prev => prev + "2",
            ...
          }
        },
        queue: {
          ...
          lastRenderedState: 0,
          pending: {
            action: prev => prev + 1,
            eagerState: 1, // first hook eager calculatio 
            ...
          }
        }
      }
    }

The fiber contains the list of all hooks in order of definition and inside dispatchAction of setSecondState we have the eagerState of the first setState and the action of setSecondState in pending.

As we can see this function is not only called by the useState but also by the useReducer. In fact, the useState is nothing more than a simplified useReducer!
Ps. As of React 18 the function “dispatchAction” is no longer shared between useState and useReducer but they also remain very similar in creation and update as we will see later on this article.

Where is the status actually calculated?

Early we saw just the eager computation it is now time to see how the actual computation works.

On the next render, re-executing the function const [state,setState] = useState(0) the function that will be called is updateState ( updateState calls updateReducer so useState is just a simplified useReducer). In this function all updates are calculated and the newState is determined. In this way after a setState the state have the value updated.

    function updateReducer<S, I, A>(
      reducer: (S, A) => S,
      initialArg: I,
      init?: I => S,
    ): [S, Dispatch<A>] {
      const hook = updateWorkInProgressHook();
      ...

      if (baseQueue !== null) {
        const first = baseQueue.next;
        let newState = current.baseState;

        let newBaseState = null;
        let newBaseQueueFirst = null;
        let newBaseQueueLast = null;
        let update = first;
        do { // for every update
          const updateLane = update.lane;
          if (!isSubsetOfLanes(renderLanes, updateLane)) {
           ...
          } else {
            ...
            // ---> Process this update <---
            if (update.eagerReducer === reducer) {
              newState = ((update.eagerState: any): S);
            } else {
              const action = update.action;
              newState = reducer(newState, action); // (prev) => prev + 1
            }
            // -----------------------------
          }
          update = update.next;
        } while (update !== null && update !== first);


        if (!is(newState, hook.memoizedState)) {
          markWorkInProgressReceivedUpdate();
        }

        ...
      }

      const dispatch: Dispatch<A> = (queue.dispatch: any);
      return [hook.memoizedState, dispatch];
    }

Now we have all the elements to understand why the dispatched action call the reducer function twice. The useReducer inside dispatchAction immediately calculates the next value (executing the reducer function) and updates update.eagerReducer and update.eagerState with the new values. In the first version of the useEnhancedReducer at the re-render the reducer function was not cached (for example with a useCallback ) so is always recreated at every re-render and even if the function is the same the pointer differs from the previous.

So inside the updateReducer function the reducer will be called a second time.

    if (update.eagerReducer === reducer) { // --> false 
        newState = ((update.eagerState: any): S);
    } else {
        const action = update.action;
        newState = reducer(newState, action); // --> executing for the second time
        // the first time was inside dispatchAction on eager computation
    }

Ps. in React 18 this behavior has changed, the useReducer no longer pre-computes the new state (no more eagerReducer). Moreover bugs due to non-pure functions like this will be highlighted by strict mode.

(The pull request that removes the new state pre-computation, together with an explanation, can be found here: 22445)

Conclusion

In conclusion, starting with the goal of understanding why the useEnhancedReducer was called twice we discovered:

How react, shared, react-dom, and react-reconciler communicate;
How hooks are defined, hooked to fibers, and what the useState and useReducer looks like;
How hooks execute actions and update their state.

A schematic of the analyzed code is shown next

I hope this article has shown something new, maybe replacing what seem like “the magic of react” with real code and that will make it easier for you to understand and explore react.

If you enjoyed this article and want more content on React, you might be interested in the useEnhancedReducer, shown with MVLabs at ReactJs Day 2023.

Appendix A

How the source code can be debugged?

A method that i used to quickly write code, test it and debug source code is to:

Create a CodeSandbox;
Open the developer console onto the source tab (left circle in the image);
Discover the source code (if you will use CodeSandbox the source code path will be similar to the one in the picture), add a breakpoint on code and step into the source.

Flutter Monorepo & Dependency Injection

Mattia Pispisa — Sun, 01 Oct 2023 16:47:42 +0000

I described dependency inversion and a way to use in dart/flutter in this article. In this post I will use the same concepts and libraries.

Monorepo

Monorepo refers to the practice of software development in which all components of an application or system are maintained within a single repository. A good article that describes well what it is, pros and cons is the following: monorepo.tools.
In the case of a flutter application an excellent monorepo manager is Melos, here a tutorial on how to create and manage it.

A concrete use case

Suppose our application is a social app and we need to manage posts and users. The application is divided into packages where each package contains views and logics to manage a specific section of the application (users, posts, ...). Route is defined within the core package. At this point each package defines its routes which will then be displayed in the sidebar (see uml). The result is as follows:

The abstract class Route is in core;
Its implementations are in different packages (PostRoute, UserRoute, ...).

Implementation

This can be the folder structure,

app
  - lib
    ...
  - pubspec.yaml

modules
  - core
      - pubspec.yaml
      ...
  - user
      - pubspec.yaml
      ...
  - post
      - pubspec.yaml
      ...

where the various pubspec.yaml will look like:

## app
dependencies:
  core: 
    path: ../modules/core
  user:
    path: ../modules/user
  post:
    path: ../modules/post

## user
dependencies:
  core: 
    path: ../core

// app code
@Injectable(as: Navigation)
class AppNavigation implements Navigation {
  @override
  List<Route> routes = [UsersRoute()];
}

// core code
@injectable  
class SideBarMenu extends StatelessWidget {
  const SideBarMenu(this.navigation);

  final Navigation navigation;

  @override
  Widget build(BuildContext context) {
    return Column(
      children: navigation.routes
          .map(
            (r) => Link(
              url: r.url,
              child: Text(r.name),
            ),
          )
          .toList(),
    );
  }
}

abstract class Navigation {
  List<Route> get routes;
}

abstract class Route {
  String get url;
  String get name;
  Widget view();
}

// post package
class PostsRoute implements Route {
  String url => "posts";
  String name => "Posts";
  Widget view => Container();
}

Each package defines a micropackage (core, user, posts). Additionally in core we define getIt and export it for the other modules.

// only in core
GetIt getIt = GetIt.instance;

// every package
@InjectableInit.microPackage()
initMicroPackage() {}

In app we init the injection and register the various micro packages.

@InjectableInit(
    initializerName: 'init',
    preferRelativeImports: true,
    asExtension: false, 
    // packages
    externalPackageModulesBefore: [
      ExternalModule(CorePackageModule),
      ExternalModule(UserPackageModule),
      ExternalModule(PostPackageModule),
    ])
FutureOr<void> configureInjection() => init();

In this case all packages were registered (in order) with the method externalPackageModulesBefore but there are three properties that can be used (in order of registration): 1. externalPackageModulesBefore, 2. externalPackageModules, 3. externalPackageModulesAfter.

Conclusion

This concludes the article on Monorepo & Dependency Injection.

For more information on micropackage I recommend reading injectable package.

Mastering dependency injection in Flutter

Mattia Pispisa — Thu, 10 Aug 2023 09:58:47 +0000

Depend on the abstract class and not the concrete class

One of the 5 SOLI D principles capitulates that a high-level module should depend only on abstract class not on the implementation. This leads to less coupling between modules (more here).

In this article we will focus on how to apply this pattern in flutter.

What are we going to use

get_it is a service locator used to get at run-time the concrete class of the abstract class we are requesting.
injectable and injectable_generator will be used to annotate and generate the get_it's code (an official example of code generation).

Why injectable?

When the service locator pattern is used throughout the whole application and each abstract class can have several concrete classes it is very useful not to have to think about the implementation of get_it but to let the code generation take care of it.

By importing the libraries the pubspec.yaml will look like the following:

dependencies:
  injectable:
  get_it:
  ...

dev_dependencies:
  injectable_generator:
  ...

A concrete use case

Naive

An application needs to display a list of users and the user 's detail.
An idea might be to create a UserRepository.

// foo.dart

/// business logic module
class HighLevelModule {
  void foo() {
    final users = UserRepository().getUsers();
  }
}

// user.dart

/// user model
class User {
  const User({required this.id, required this.displayName});

  factory User.fromJson(Map<String, dynamic> json) {
    return User(
      id: json['id'],
      displayName: json['displayName'],
    );
  }

  final String id;
  final String displayName;
}

// user_repository.dart
class UserRepository {

  Future<List<User>> getUsers() async {
    // Don't take this as an example of how to make an http call
    final response = await http.get(Uri.parse('https://example.com/api/users'));
    final List<dynamic> usersData = json.decode(response.body);

    return usersData.map((userData) => User.fromJson(userData)).toList();
  }

  Future<User> getUser({required String id}) async {
    // Don't take this as an example of how to make an http call
    final response = await http.get(Uri.parse('https://example.com/api/users/$id'));
    return User.fromJson(json.decode(response.body));  
  }
}

In this way the caller (high-level module) will depend on the low-level UserRepository module.

A better approach

Applying dependency inversion to decouple the two modules we can create:

class HighLevelModule {
  void foo(UserRepository repository) {
    // doesn't know the repository implementation
    final users = repository.getUsers();
  }
}

abstract class UserRepository {
    Future<List<User>> getUsers(); 
    Future<User> getUser({required String id});
}

class ConcreteUserRepository implements UserRepository {
  // previous UserRepository code
}

Now magic comes into play

Create a injection.dart file like:

import 'injection.config.dart';

@InjectableInit(
    initializerName: 'init',
    preferRelativeImports: true,
    asExtension: false, 
)
FutureOr<void> configureInjection() => init(getIt);

Annotate ConcreteUserRepository

@LazySingleton(
  as: UserRepository,
)
class ConcreteUserRepository implements UserRepository {
  ...
}

(singleton, lazy)

The code generation command (flutter pub run build_runner watch --delete-conflicting-outputs) will create an injection.config.dart file with the get_it code needed to get the concrete class from the abstract one.

getIt<UserRepository>() will return the most suitable concrete class among those registered.

Multiple implementation

Now that the high-level module no longer depend on implementation, we can use different implementations of UserRepository based on environment variables (Configuring apps with environment).

@LazySingleton(
  as: UserRepository,
  env: ["prod"]
)
class ConcreteUserRepository implements UserRepository {
  ...
}

@LazySingleton(
  as: UserRepository,
  env: ["dev"]
)
class DemoUserRepository implements UserRepository {
   @override
  Future<List<User>> getUsers() async {
    return [User(id: "1",displayName: "A"),User(id: "2",displayName: "B")];
   }

    @override
  Future<User> getUser({required String id}) async {
    return User(id: "1",displayName: "A");
  }
}

// file injection.dart
@InjectableInit(...)
FutureOr<void> configureInjection(String env) => init(
      getIt,
      //will be taken the concrete class that contains the env `env`. 
      environmentFilter: NoEnvOrContains(env),
    );

Now we can test our high-level module by ignoring the user repository implementation.

Conclusion

This concludes the article on dependency inversion.

For more information on dependency inversion in flutter I recommend reading get_it and injectable documentation.