Skip to main content

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 a trust value that cannot be parsed statically are treated as sandboxed.