BWE Module Imports

[andy-haynes]

With the nascent implementation of Component imports (import Post from 'near://ex.near/Post), we have some decisions to make around what kind of usage we want to support.

Exports

The current rules regarding exports are a constraint imposed by the need for <Component />'s src string prop to map to a React Component in the source. However, by supporting a real import syntax, developers now have flexibility in how Components reference one another.

In practice this means developers can break the implicit 1:1 mapping of BWE Module to React Component, i.e. export two Components from the same source file. Is there any reason to prevent this? The only downside for the current implementation would be excess bundle size from a lack of tree shaking when only importing a subset of Components from a BWE Module.

This also means that any exportable data can be exported from a BWE Module. This is not an issue in many scenarios but you don't have to go far before straying into undefined behavior territory. For example, exporting a function from a BWE Module would work fine in trusted contexts but may not work in sandboxed containers. These are the kinds of things that can be explored further as we work towards #191, but in the interim I don't see a compelling reason to prevent this.

Since <Component /> is not being deprecated, we do still need a way to map src to an exported reference. My preference would be to keep it simple and require that src-referenced Components must have a default export. All named exports would only be applicable with the new Component import syntax; BWEComponent would no longer be used as a fallback when a module has no default export.

Imports

We have settled on using a prefix of near:// on absolute Component imports as a natural way to convey analogous URL semantics supported by import. This prefix precludes package collision with other NPM imports.

The same does not apply to relative imports, meaning relative imports within a BWE Module are implicitly treated as BWE Components. Overall I think this is a fairly innocuous assumption to make, given the understanding the developer would have of the production environment. Even if we implement something like CSS module import support later on, I think the expectation that your local imported source is on chain is entirely valid.

Trust

One thing that's been somewhat awkward to reconcile is the divergence in behavior between trusted and sandboxed imported Components. Trusted Components are fairly simple because the definition is being inlined, just as a conventional bundler would behave. Sandboxed Components on the other hand are inherently dynamic, rendering a placeholder Component to be initialized post-render. So while the import syntax makes BWE Modules statically analyzable, the build-time behavior for these imports is still entirely influenced by the individual call to createElement.

This doesn't cause any issues now but I could see it arising from more advanced trust scenarios and overall it seems unintuitive. One way to address this would be through the use of pragma comments to specify import behavior, e.g.

// @bwe-trusted
import Message from 'near://ex.near/Message';

This is just interesting to consider for the future, not something that needs to be addressed as part of initial import support.

Currently Supported import Syntax

blog.near/Blog.Root

// imports a default-exported Component
import Post from 'near://blog.near/Blog.Post';

// imports the default-exported Component for blog.near/Blog.Body
import Body from './Body';

Proposed import Updates

blog.near/Blog.Root

// imports Component at the given block height
import Header from 'near://blog.near/Blog.Header@118999';

// imports Component for blog.near/Blog.Title at the given block height
import Title from './Title@11235813';

// imports the default-exported Component for blog.near/Blog.Date and a named export
// importing functions should work as expected, even when passed as props to sandboxed Components
import Date, { formatDate } from './Date';

// imports the named Component export exported from blog.near/Blog.Footer and assigns it an alias
import { Icon as FooterIcon } from './Footer';

// imports all exports from Blog.utils, adding them to a sealed, null-prototyped object called Utils
import * as Utils from './utils';

// executes the module
// the code in the imported module would be executed once at container
// initialization time regardless of how many trusted descendants import it
import './module-scoped';

[calebjacob]

In practice this means developers can break the implicit 1:1 mapping of BWE Module to React Component, i.e. export two Components from the same source file.

It would be really nice if we can support multiple, named exports. It would be one step closer to a regular React development environment.

This also means that any exportable data can be exported from a BWE Module.

If we can allow any type of named exports, that would certainly reduce the brain strain of remembering what can or can't be exported where.

One thing that will be really common in a TS environment is the need for exporting/importing types (from both internal and external sources) - which almost always rely on named exports/imports. Would that alter our approach at all?

[andy-haynes]

If we can allow any type of named exports, that would certainly reduce the brain strain of remembering what can or can't be exported where.

Agreed. The reality is without a more heavy handed approach, we can't really strip things out of the exported code. What we can do is identify boundaries of undefined behavior and offer guidance to developers.

Mostly though I am concerned with edge cases, like how arbitrarily-exported references could be affected by trust. Exporting a number? Sure, no problem. Executing a Promise from a side effect import? This might not go the way you think 🙂

One thing that will be really common in a TS environment is the need for exporting/importing types (from both internal and external sources) - which almost always rely on named exports/imports. Would that alter our approach at all?

That will only be relevant for local development/sandbox, which will need to parse the type annotations to interpret them in their respective contexts. What I'm outlining is only the import semantics for runtime code, and those imports are only parsed after transpilation strips types.

[calebjacob]

Thanks for clarifying regarding import for runtime. You're right, types would have already been stripped out.