Optimization
The options presented here can lead to decreased security and should only be used with clear understanding of the implications.
Trust Mode
The default trust model of BWE is to encourage risk-free composability by sandboxing all embedded BWE components by default. There are cases where this might not be necessary, such as:
- embedding your own components
- embedding components from other developers you trust
- embedding components you have audited for malicious behavior and are locked to a specific version
If a component does not need to be sandboxed, you can change the trust
mode on the embed and the component will be directly executed in the same container instead of having a separate sandboxed iframe created for it. This can yield significant performance improvements for pages which render many components (e.g. social feeds).
There are two modes for loading a Component: sandboxed (default) and trusted. These modes make it possible to define the boundaries within Component trees, granting developers more control over the balance of performance and security in their applications.
Sandboxed
Sandboxed Components are run in a dedicated container, independent of their parent Component's context. All communication
between parent and child (e.g. re-rendering, props
method invocation) is handled via postMessage
communication through
the outer application.
If no trust modes are specified, every Component is sandboxed in a separate container.
Trusted
When a Component is loaded as trusted, the parent Component inlines the child Component definition into its own container and renders it as a child DOM subtree.
In short, embedding a component as trusted removes some application overhead but gives the embedded component the ability to read or manipulate the parent component's state and DOM.
Usage
By default, Components are loaded in sandboxed mode. To change the loading policy, configure the trust
prop with a desired mode
property
The following modes are supported:
- sandboxed (default): load this Component in its own container
- trusted: load this Component within the parent Component
- trusted-author: extends the trusted mode by inlining this Component and all descendant Components from the same author
Sandboxed
import Foo from 'near://bwe-demos.near/Foo'
// ...
{/* omitting the `trust` prop would have the same behavior */}
<Foo trust={{ mode: "sandboxed" }} src="ex.near/Parent" />
Trusted
import Foo from 'near://bwe-demos.near/Foo'
// ...
<Foo trust={{ mode: "trusted" }} src="ex.near/Parent" />
Trusted Author
import Foo from 'near://bwe-demos.near/Foo'
// ...
{/* Root Component */}
<Foo trust={{ mode: "trusted-author" }} src="ex.near/Parent" />
{/* Parent Component */}
<>
{/* trusted: same author */}
<Foo src="ex.near/X" id="x-implicit" />
{/* trusted: same author, explicitly trusted; note that descendants of Y authored by ex.near will still be trusted */}
<Foo src="ex.near/Y" trust={{ mode: "trusted" }} id="y" />
{/* sandboxed: explicitly sandboxed, same author behavior is overridden */}
<Foo src="ex.near/X" trust={{ mode: "sandboxed" }} id="x-sandboxed" />
{/* sandboxed: different author, no trust specified */}
<Foo src="mal.near/X" id="x-mal" />
</>
Notes
- The root Component is always loaded as sandboxed.
- The
trust
prop must be specified as an object literal with literal values; i.e. the value may not contain any variables or be returned from a function. Loading happens prior to rendering, so the trust must be statically parseable. Any Component renders with atrust
value that cannot be parsed statically are treated as sandboxed.