🛠 Let's implement the Incremental/Affected pattern, the killer feature used by Turborepo, Nx, Rush and many more popular tools

project-folder/
│
└───design-system/
|   |   dist/
│   │   component1.jsx

│
└───temporal/
│   |   dist/
│   │   dateFormat.js
|
|   dist/
|   app.jsx
|   package.json

import Component1 from "./design-system/component1.jsx";
import { hoursToMilliseconds } from "./temporal/dateFormat.js";

function myApp() {
  return <Component1> {hoursToMilliseconds(2)} </Component1>;
}

# Bundle the whole app including `design-system` and `temporal` libs
$ npm run build

project-folder/
│
└───design-system/ # 100+ components
│
└───temporal/ # 50+ files
|
└───lib3/ # library using node-sass (nearly 5 MB)
|
└───lib4/ # library using heavy npm modules

const component1 = styled.div`
  color: red;
`;

/**
 * lib1 depends on lib3 (via the use of lib3.MyLib3Component)
 * while library 2 is independent.
 */
const lib1Metadata = {
  id: "lib1",
  adjacentTo: [],
  payload: {
    component: `<lib3.MyLib3Component/ >`,
  },
};

const lib2Metadata = {
  id: "lib2",
  adjacentTo: [],
  payload: { component: `<div>hello from lib2</div>` },
};

const lib3Metadata = {
  id: "lib3",
  adjacentTo: [],
  payload: { component: `<MyLib3Component>hello lib3</MyLib3Component>` },
};

import { DiGraph } from "digraph-js";
const projectGraph = new DiGraph();

// Each project is represented with a vertex (node)
projectGraph.addVertices(lib1Metadata, lib2Metadata, lib3Metadata);

/**
 * lib1 depends on lib3, we must represent this relationship
 * by adding an edge from lib1 to lib3.
 */
projectGraph.addEdge({ from: lib1Metadata, to: lib3Metadata });

/**
 * Simulating a simple cache, persisting an hashed
 * value of the component.
 * In a real world project, you would use something
 * like the "folder-hash" library to generate hashes
 * for a given folder containing sub directories and files.
 */

const cache = {
  lib1: {},
  lib2: {},
  lib3: {},
};

import crypto from "node:crypto";

function buildLibrary(library) {
  // Create a SHA1 using the library content
  const libraryHashedContent = crypto
    .createHash("sha1")
    .update(library.payload.component)
    .digest("hex");

  console.log(`Building library: '${library.id}'`);
  // Webpack, Rollup or any other bundler can be processed here

  // Store the hashed content in cache
  cache[library.id].component = libraryHashedContent;
}

function isLibraryAffected(library) {
  const libraryHashedContent = crypto
    .createHash("sha1")
    .update(library.payload.component)
    .digest("hex");

  return libraryHashedContent !== cache[library.id].component;
}

function buildAffected(library) {
  /**
   * If the component is still the same (i.e: hash data hasnt changed), we
   * don't want to rebuild it. If its "Affected", we must invalidate it
   */
  if (isLibraryAffected(library)) {
    // Component's hash changed, meaning we must build the library
    buildLibrary(library);

    return { hasLibraryBeenRebuilt: true };
  }

  // The lib has not changed so does not require a new build
  console.log(`Using cached version of '${library.id}'`);

  return { hasLibraryBeenRebuilt: false };
}

// build lib1 using Affected detection
buildAffected(lib1Metadata);
// => prints out:  "Building library: 'lib1'";

// re-run a build without any changes multiple times
buildAffected(lib1Metadata);
buildAffected(lib1Metadata);
buildAffected(lib1Metadata);
// => prints out each time: "Using cached version of 'lib1'";

// change lib1's content
lib1Metadata.payload.component = "<div> Hello lib1 </div>";

// re-run a build
buildAffected(lib1Metadata);
// => prints out:  "Building library: 'lib1'";

const lib1Metadata = {
  id: "lib1",
  adjacentTo: [],
  payload: {
    component: `<lib3.MyLib3Component />`,
  },
};

const lib2Metadata = {
  id: "lib2",
  adjacentTo: [],
  payload: { component: `<div>hello lib2</div>` },
};

const lib3Metadata = {
  id: "lib3",
  adjacentTo: [],
  payload: { component: `<MyLib3Component>hello lib3</MyLib3Component>` },
};

// Given a root node, we traverse the graph looking for dependencies
function* buildAllRootLibraryDependencies(rootLibrary) {
  // Traverse all rootLibrary's dependencies
  for (const rootLibraryDependency of projectGraph.getAdjacentVerticesTo(
    rootLibrary
  )) {
    /**
     * Recursively build affected libraries starting from the deepest dependencies
     * of the root library.
     */
    yield* buildAllLibraryDependencies(rootLibraryDependency);
  }

  /**
   * When we reach a dependency with no other dependencies, we
   * now that we're done going deep into the dependency tree.
   * If the library has been rebuilt, we must inform the
   * parent in order to recursively invalidate nodes in the
   * traversed path.
   */
  const { hasLibraryBeenRebuilt } = buildAffected(rootLibrary);

  yield hasLibraryBeenRebuilt;
}

/**
 * Build everything with affected strategy including root
 * library itself
 */
function buildEverythingAffectedIncludingRootLibrary(rootLibrary) {
  const rootLibraryDependencies =
    projectGraph.getAdjacentVerticesTo(rootLibrary);
  const allRebuiltLibraries = [];

  for (const dependencyLibrary of rootLibraryDependencies) {
    /**
     * Keep track of all the children builds to know if some
     * were rebuilt. If there is no affected dependency, the
     * array would remain empty
     */
    allRebuiltLibraries.push([
      ...buildAllRootLibraryDependencies(dependencyLibrary),
    ]);
  }

  /**
   * All root library's dependencies were rebuilt if necessary (i.e: affected).
   * However, we now need to determine if the root library has to also be
   * rebuilt. There are 2 conditions requiring the root library to be rebuilt:
   * - The root library itself changed
   * - Atleast one of the dependencies of the library changed
   */
  const HAS_LIBRARY_BEEN_REBUILT = true;
  const atleastOneLibraryChanged = allRebuiltLibraries
    .flat()
    .includes(HAS_LIBRARY_BEEN_REBUILT);

  if (atleastOneLibraryChanged) {
    buildLibrary(rootLibrary);
  } else {
    // Check if library itself changed by running affected detection on the root library
    buildAffected(rootLibrary);
  }
}

function buildProjectUsingAffectedStrategy() {
  console.log("\n----STEP 1-----");
  // Building for the first time
  buildEverythingAffectedIncludingRootLibrary(lib1Metadata);

  console.log("\n----STEP 2-----");
  /**
   * Building for the second time but no dependencies of lib1 changed (neither
   * lib3 or lib4) so it remains UNAFFECTED (i.e: using cache)
   */
  buildEverythingAffectedIncludingRootLibrary(lib1Metadata);

  console.log("\n----STEP 3-----");
  /**
   * Let's now change the content of lib3's component.
   * Remember, lib1 depends on lib3 via the use of lib3.MyLib3Component so
   * this change should trigger an affected build.
   */
  console.log("Changing lib3's content...");
  // addMutation is a function which update the value of a given vertex in the graph
  projectGraph.addMutation(lib3Metadata, {
    // new lib3 component
    component: `<MyLib3Component>Hello affected lib3!</MyLib3Component>`,
  });

  console.log("\n----STEP 4-----");
  /**
   * Now that lib3 (dependency of lib1) changed, both lib3 and lib1 are considered
   * affected. It means that we must rebuild both, starting with lib3 (lib1 must be built
   * with the latest version of lib3).
   */
  buildEverythingAffectedIncludingRootLibrary(lib1Metadata);
}

----STEP 1-----
Building library: 'lib3' // building for the first time
Building library: 'lib1' // building for the first time

----STEP 2-----
Using cached version of 'lib3' // building for the second time but nothing changed so we can use a cached version of lib3
Using cached version of 'lib1' // building for the second time but nothing changed neither from lib3 nor from lib1 itself so we can use a cached version of lib1

----STEP 3-----
Changing lib3's content... // updating lib3 content

----STEP 4-----
Building library: 'lib3' // lib3 changed so must be rebuilt
Building library: 'lib1' // lib1 did not change but its direct dependency "lib3" changed so it must be rebuilt