Keep server credentials out of browser integrations
A provider can contribute server behavior and browser behavior without putting them in the same module. The server side owns credential-aware execution; the browser side carries its public configuration and supported browser code.
Shared provider identity connects the parts. Their package and runtime boundaries keep their different responsibilities explicit.
Example — The public and private sides of billing
The browser knows which billing provider the application uses. Server-side billing operations use their credential-aware module. The browser declaration does not need to carry the server key to identify the provider.
For engineers
Give each runtime its own module
The Stripe frontend module records identity, capabilities and public configuration. This selected portion is browser-facing:
providerCapabilities: [BUILTIN_PROVIDER_CAPABILITY.BILLING],
protocols: [BUILTIN_PROVIDER_PROTOCOL.BILLING_PROVIDER],
publicConfig: {
billingProviderRef: 'stripe',
},
The backend module belongs to @wildo-ai/external-connectors-private/backend and exposes server runtime contracts and a secrets contract. Secret declarations name the required values; the application supplies those values through the server’s supported credential path. Do not copy secret values into publicConfig or a frontend contribution.
Separate browser data from executable code
Browser integration has two inputs. The application configuration or generated JSON supplies enabled provider data for the service and environment. An explicitly supplied frontend module map supplies executable code from the provider package’s browser facet.
| Channel | Carries | Why it is separate |
|---|---|---|
| Data | Identity, public configuration, SDK/component descriptors and CSP footprint | Can be serialized for the selected environment. |
| Code | SDK activation, public-config validation and component loaders where supported | Functions cannot survive JSON serialization. |
hydrateFrontendProviderModules joins those inputs by provider reference. Enabled data without a matching module retains its identity and public configuration, but has no executable SDK and raises a missing-code diagnostic. Bundled code without enabled data remains inactive. Descriptor checks identify stale generated declarations rather than silently treating mismatched data as the current module.
Preserve the boundary in application code
Supply the module map through the host’s frontend registration option and import each module from its deliberate browser entrypoint. For the SaaS application host, startApplicationService.initializeApplication accepts frontendProviderModules; startup passes that map into registry hydration alongside the enabled provider data. Configuration synchronization supplies provider data and backend runtime artifacts, but currently does not emit the frontend code map. Wire that map explicitly for browser behavior; rerunning synchronization alone does not supply an SDK loader. Do not import the server package into a React component to obtain metadata. Shared browser-safe metadata exists for that purpose.
Package separation and the public package’s bundle-isolation tests establish an intended boundary, not a magic guarantee that an application can never write an unsafe import. Review custom provider dependencies and the actual browser artifact. Public configuration must remain public, and the server must still enforce access to every credential-backed operation.
See browser activation for the connected contribution and startup example: public settings enter through the companion contribution, while the browser imports its module through a public frontend entrypoint and passes it to its host.