Bundle bloat: importing from @finos/fdc3 pulls the entire @finos/fdc3-schema runtime (~240 KB)

[enewsome]

Minor Issue

Upgrading @finos/fdc3 from 2.1.x to 2.2.3 grew our minified ESM bundle by 181 KB.
Marking @finos/* as sideEffects: false at resolve time in our bundler narrowed the
regression to 158 KB but didn't fix it — the remainder is structural (see details below).

Area of Issue

• App Directory
• API
• Context Data
• Intents
• Desktop Agent Bridging
• Use Cases
• Other

Issue Description

Importing only getAgent / fdc3Ready from @finos/fdc3 pulls in the entire
@finos/fdc3-schema runtime (~240 KB), even when the consumer never references
BrowserTypes or BridgingTypes.

Root cause

@finos/fdc3-schema/dist/src/index.js:

import * as BrowserTypes from '../generated/api/BrowserTypes.js';
import * as BridgingTypes from '../generated/bridging/BridgingTypes.js';
export { BrowserTypes, BridgingTypes };

The import * as namespace binding is opaque to bundlers — any reachability of
BrowserTypes retains the whole module. The two generated modules are ~146 KB and
~94 KB of quicktype output (Convert classes plus type-guard helpers).

The umbrella @finos/fdc3 then re-exports both namespaces, so any consumer that imports
from it makes the schema reachable:

// @finos/fdc3/dist/src/index.js
import { BrowserTypes, BridgingTypes } from '@finos/fdc3-schema';
export { BridgingTypes, BrowserTypes };

Within @finos/fdc3-get-agent, the modules that introduce a runtime import of
fdc3-schema (and therefore force it into any reachable graph) are:

• strategies/HelloHandler
• strategies/IdentityValidationHandler
• ui/AbstractUIComponent
• ui/DefaultDesktopAgentChannelSelector
• ui/DefaultDesktopAgentIntentResolver

(@finos/fdc3-agent-proxy/listeners/PrivateChannelEventListener is in the same
position.)

Options for cutting it down

1. Add "sideEffects": false to every @finos/* package. None of the six 2.2.3
   packages declare it today.

2. Replace import * as with named re-exports in
   @finos/fdc3-schema/dist/src/index.js so bundlers can drop symbols at export-name
   granularity instead of keeping the entire 146 KB / 94 KB namespaces because
   anything in them was reached.

3. Add an exports map with sub-paths to @finos/fdc3-schema so consumers can
   opt in to the narrowest slice (e.g. types vs. validators) without bundlers having
   to prove the rest is unused.

4. Split the generated Convert class out of the type-only exports. Most of the
   240 KB is the Convert runtime (162 static methods on BrowserTypes alone) plus
   its type-guard helpers. Consumers wanting only TypeScript types pay the full
   runtime cost. A separate entry point for validators would let consumers that don't
   need runtime schema validation skip it entirely.

Additional Context

[kriswest]

Hi @enewsome, we discussed this issue today at #1904. A couple of thoughts:

• If you're using getAgent then BrowserTypes from fdc3-schema is definitely necessary as it's used to implement the connection flow and agent-proxy used to communicate with web-based FDC3 DesktopAgents.
• We could try to eliminate the Convert class (by passing the -just-types flag when calling quicktype here) - we don't directly reference the Convert class in fdc3-get-agent / fdc3-agent-proxy / fdc3-web-impl - however, it appears to be used in the implementation of the type guard functions (predicates) at the bottom of the file.
  • The typeguard functions (predicates) are generated via post processing with ts-morph here:

    FDC3/packages/fdc3-schema/code-generation/generate-type-predicates.ts

    Lines 65 to 109 in fe01d1d

    	function writeTypePredicates() {
    	let awaitMessage = print(`Writing Type Predicates (finding convert functions)`, { spinner: true });
    	// get a list of all conversion functions in the Convert class that return a string
    	const convert = sourceFile.getClass('Convert');
    	const convertFunctions = (convert?.getChildrenOfKind(SyntaxKind.MethodDeclaration) ?? []).filter(
    	func => func.getReturnType().getText() === 'string'
    	);
    	awaitMessage.updateMessage(`Writing Type Predicates (finding message interfaces)`, true);
    	//get a list of all interfaces in the file
    	let messageInterfaces = sourceFile.getChildrenOfKind(SyntaxKind.InterfaceDeclaration);
    	// generate a list of Interfaces that have an associated conversion function
    	const matchedInterfaces = convertFunctions
    	.map(func => {
    	const valueParameter = func.getParameter('value');
    	const matchingInterface = messageInterfaces.find(interfaceNode => {
    	/// Find an interface who's name matches the type passed into the value parameter of the convert function
    	return valueParameter?.getType().getText(valueParameter) === interfaceNode.getName();
    	});
    	if (matchingInterface != null) {
    	return { func, matchingInterface };
    	}
    	return undefined;
    	})
    	.filter(isDefined);
    	const allFunctionDeclarations = sourceFile.getChildrenOfKind(SyntaxKind.FunctionDeclaration);
    	// write a type predicate for each matched interface
    	matchedInterfaces.forEach((matched, index) => {
    	awaitMessage.updateMessage(`Writing Type Predicates (${index}/${matchedInterfaces.length})`, true);
    	writeFastPredicate(matched.matchingInterface, allFunctionDeclarations);
    	writeValidPredicate(matched.matchingInterface, matched.func, allFunctionDeclarations);
    	writeTypeConstant(matched.matchingInterface);
    	});
    	awaitMessage.complete(true, `Writing Type Predicates`);
    	}

  • There are two types generated, a 'fast' predicate (is<MessageName>) and a validation version (isValid<MessageName>) - only the latter (validation) version references the Convert class.
    • We use the 'fast' predicates extensively in the implementation for message type checking. You probably can't tree-shake these out if using getAgent.
    • We don't (AFAIK) use the validation versions (isValid<MessageName>) - however at least one other participant in FDC3 definitely does (@Roaders).

Hence, to solve this issue for you we may need some combination of your proposed solutions.
Perhaps we could separate out the validation predicates (and Convert class?) into a separate file?

@hughtroeger and @Roaders put their hands up to work on this and see if we can slim things down. @Roaders what do you think about the validation functions and Convert class? Can ts-morph split them out? Or can we tweak the exports to allow them to be shaken out? What would constitute a breaking change for adopters?

[enewsome]

@kriswest sorry for the late reply.

FYI, when I first upgraded I hadn't switched over to getAgent yet and still saw the bundle size increase. This is due to the fdc3Ready event that I was already using changing internally to call getAgent. Understood though about the BrowserTypes info that code path needs.

Thanks for taking a look, happy to test out some changes if/when there is a canary