Sockets and contributions

A module does not edit files. It returns contributions, plain data that says what it adds, and the pipeline puts them together. Shared files, such as bootstrap.dart, have sockets: named places where modules put code without knowing who else does.

Contributions

Contribution	What it adds
BrickContribution	Template files, as a mason bundle, with the variables that the templates read. Every generated file has exactly one owner.
SocketContribution	Code or a value for a socket.
RoleData	Data for a role in the role's own language, such as the routes of a feature for the router.
PubspecContribution	A dependency, an SDK constraint, or a setting of the flutter: section of pubspec.yaml.
CodegenRequest	A request to run build_runner in the new app.
Preflight	Checks of the machine before generation, which can offer to set up what is missing.
PostGenStep	A command to run in the new app, such as flutterfire configure.

Every contribution can have a when, a set of roles that must all be present for the contribution to apply. A module lists there the roles it only uses, so code that refers to them is generated only in apps that have them. firebase_analytics gives the router its listener of the screen with when: {routerRole}.

Sockets

A socket belongs to a role, to a module or to the pipeline. Its template marks it with a tag in three braces that joins smf_, the owner and the name of the socket, such as {{{smf_app_entry__bootstrap_platform}}}. The pipeline replaces the tag with the rendered contributions. Modules refer to sockets only through typed constants, such as AppEntryRole.bootstrapPlatform, so a misspelled socket does not compile.

This is lib/bootstrap.dart as flutter_core writes it, with the tags of the start-up phases:

{{{smf_app_entry__top_level}}}

Future<void> bootstrap() async {
{{{smf_app_entry__bootstrap_early}}}
{{{smf_app_entry__bootstrap_platform}}}
{{{smf_app_entry__bootstrap_di}}}
{{{smf_app_entry__bootstrap_late}}}
}

The kind of a socket decides what it takes and how its contributions are rendered:

Kind	Takes	Rendered as	Example
CodeSocket	Fragments of code, with the imports they need	One after another	The start-up phases
ArgsSocket	Named arguments of a call	name: value, lines. A list argument unites the items of its contributors, or takes the items of one contributor only. Two values of a single argument conflict.	theme and supportedLocales of MaterialApp
WrapperSocket	A widget around a piece of code, as an opening and a closing part	The first contribution outermost	ProviderScope(child: …) around the root widget
FactoryListSocket	Functions that the socket's owner calls	List items	Navigator observers and listeners of the screen of the router, restorers of the preferences
KeyedSocket	Entries with a key	Merged by key with a policy	Android permissions, Info.plist keys, Gradle plugins, README sections, sections of the guide for coding agents
ValueSocket	One value	Merged with a policy	The minimum iOS version, the highest any module needs

A fragment of code never imports anything itself. It lists its imports, such as ImportRef('package:firebase_core/firebase_core.dart'), and the pipeline adds them to the file that holds the socket's tag, merged and sorted. ImportRef.app('firebase_options.dart') imports a file of the app without knowing the app's package name.

The sockets of the app entry

The app entry role is open to every module, so any module can use these sockets:

Socket	Where	What goes in
bootstrapEarly, bootstrapPlatform, bootstrapDi, bootstrapLate	bootstrap()	Start-up code, by phase
topLevel	lib/bootstrap.dart	Top-level declarations, such as a handler of background messages
rootWrappers	main()	Widgets around the root widget
appArgs	the root MaterialApp	theme, darkTheme, themeMode and locale, which take one value, localizationsDelegates, which takes the list items of every contributor, and supportedLocales, which takes the list items of one contributor
appBuilder	the builder of the root MaterialApp	Widgets around the content of every route
iosDeploymentTarget	project.pbxproj	The minimum iOS version, where the highest wins
androidManifestPermissions	AndroidManifest.xml	<uses-permission> by name
androidManifestApplicationMeta	AndroidManifest.xml	<meta-data> of the application
mainActivityIntentFilters	AndroidManifest.xml	<intent-filter>s of the main activity, such as deep links
infoPlist	Info.plist	Keys with a string, a boolean, an integer or an array of strings, where arrays are united
gradleSettingsPlugins, gradleAppPlugins, gradleAppDependencies	Gradle files	Plugins with their versions, the plugins the app applies, and dependencies, where the highest version wins
readmeSections	README.md	Sections by heading, such as the setup of Firebase
agentSections	AGENTS.md	Sections of the guide for coding agents by heading, each with a note

The provider of the app entry creates the root MaterialApp in the build of a widget, below the root wrappers, and evaluates the arguments of appArgs there. So the expression of an argument may read context: it can take its value from an inherited widget that a module put among the rootWrappers, and the root rebuilds when that widget notifies. The theme role gives the root its themeMode this way, and the localization role its locale. That context is above the MaterialApp, so it has neither the theme nor the localizations of the app.

The wrappers of appBuilder are below the MaterialApp, so a widget among them finds the theme and the localizations of the app above it. The app entry role puts one there itself, in every app: a widget that tells the system which icons of the status bar suit the theme.

The router role adds observers and screenListeners, and two families of sockets for the annotations of screens and of their parameters, which a router that needs annotations fills. The preferences role adds restorers, for the functions that restore what the modules keep in the preferences when the app starts.

Who may contribute where

• A socket of a role takes contributions from the modules that provide, require or use the role, and from the templates of the role and of the roles that require or use it. The sockets of the app entry are open to every module.
• A socket of a module takes contributions from the modules that depend on it directly.
• The sockets of the pipeline, which are the sections of pubspec.yaml, take no contributions. Modules contribute PubspecContributions instead, and the pipeline merges them.

A module may contribute data only to its own roles, and only a role's providers contribute its implementations. The pipeline checks all of it before it renders anything.

Order

When several modules put code into one socket, or several steps run after generation, they come in an order that the pipeline derives from the modules alone:

1. A module comes after the modules it depends on.
2. A module that requires a role, or names it in when, comes after the role's providers and its template.
3. A role's template comes after the role's providers, and after the providers and templates of the roles that its role requires or that its contributions name in when.

A contributor comes after every contributor it reaches through these edges, even through modules that add nothing to the socket. Otherwise contributors are ordered by id. A cycle is an error. smf create --explain prints the order of every socket with more than one contributor, and the edges that decide it. A step that continues another step runs right after that step instead of in its own place; see Continuing a step.

That is why installCrashReporting() of the crash reporting role runs after Firebase.initializeApp of firebase_core: the role's template comes after its provider, firebase_crashlytics, which depends on firebase_core.

A keyed socket can put its entries in an order of its own instead. The sections of the guide for coding agents do: the section of the app entry comes first, and the others follow in the order of their headings. The pipeline takes the notes of such a socket by the ids of their contributors alone, so a when of a note adds no edge, and no note can make an app impossible to generate. --explain does not list such a socket, which has no order of contributors to explain.

Merging

Keyed and value sockets merge the contributions of several modules with a policy of the socket:

Policy	How values merge	Used for
conflict	Equal values agree, and different values are an error that names both modules.	Android permissions, README sections
max	The highest version wins.	The minimum iOS version, Gradle plugins
Info.plist	Arrays of strings are united, and every other value must agree.	Info.plist keys
notes	The notes under one heading are united, each once: those of roles first, then those of modules.	Sections of the guide for coding agents

The pipeline merges pubspec.yaml itself. It intersects the constraints of a package that several modules add, and an empty intersection is an error. A package that is both a dependency and a dev dependency becomes a dependency.