Skip to main content
Network access is an advanced capability for reviewed packages that need a public HTTP API. Prefer props, data sources, or typed portal functions when the host can supply the data.

Decide whether network access is appropriate

Do not use worker network access for:
  • secrets or credentials;
  • OAuth flows;
  • private endpoints;
  • private API tokens;
  • webhooks or background work.
Use a typed portal function or server application for those requirements.

Declare the capability

Import networkAccess from the public worker facade and add it to the widget’s uses array.

Understand approval

A portal author must approve the exact package ID, package version, and capability version. Changing any of those values makes the prior grant stale. Interactive portal push requests approval. For a reviewed non-interactive push, use --allow-network-widgets. The general --yes flag does not grant network access.

Understand the request boundary

Granted fetch uses the worker’s native origin. Fluid does not add credentials, cookies, tokens, or headers. Your RequestInit, including credential mode, remains in effect. Some destinations are always blocked, granted or not: the portal’s own address, fluid.app and its subdomains, localhost, and private IP addresses. To reach your own server on a Fluid address, such as a Mist app, use a portal function. The grant doesn’t get around the browser’s CORS rules or the page’s Content Security Policy. Local preview and a deployed portal can apply different policies, so test every destination on the deployed portal before release. A widget can send portal data it receives to an external service. Review both the package and its destinations before approval.

Test failure states

Render a useful state for timeouts, unavailable destinations, malformed responses, rate limits, and offline use. Network failure must not crash the widget.