Composite

Electrode Native Composite

The Composite is a JavaScript project that is used by Electrode Native to combine all MiniApps (and optional JS API Implementations) in a single JS bundle.

A Composite project is created behind the scene, in a temporary directory, every time a Container is generated, and Electrode Native will run react-native bundle on this Composite project to create the JS bundle and assets to store in the Container.

Electrode Native will also create a Composite when using ern start command, to assemble all MiniApps together and launch the react native local packager (react-native start on this Composite).

You can also manually generate a Composite project, with the [ern create-composite] command.

Using a custom Composite

In the majority of cases, there is no need to create a custom composite, as Electrode Native comes with a built-in one. However in some specific cases, having more control on the Composite project is needed. For example, you might want to add some custom initialization code for the whole bundle, or you might want more control on some configuration files (rn-cli.config.js/ metro.config.js/babel.config.js).

Setting up a custom Composite project (also known as a base Composite) for Electrode Native is relatively straightforward.

This can be achived in two steps: 1. Create the Composite git repository 2. Configure Electrode Native to use custom Composite rather than the one built-in

Create the custom Composite git repository

This git repository should just contain a basic React Native project structure. You can create your own, or copy our starter custom composite.

For example this is the basic file structure of our sample bare custom Composite:

.
├── babel.config.js
├── composite-imports.js  [GENERATED/OVERWRITTEN]
├── index.android.js      [REQUIRED]
├── index.ios.js          [REQUIRED]
├── metro.config.js
├── package.json
└── rn-cli.config.js

There are two important things -as of now- to be aware of, when creating a custom Composite project : 1. index.android.js and index.ios.js are required. When running react-native bundle command, Electrode Native will pass these files as entry points for each platform.

1. composite-imports.js will be generated by Electrode Native. It will contain all of the MiniApps / JS API Impls imports. You have to import this file in index.android.js/index.ios.js at some point, otherwise your MiniApps won't be packaged in the bundle. Keep in mind that this file, if present in the repo, will be overwitten by Electrode Native during composite generation, so don't put custom imports or code in this one.

Also, the name/version in the package.json and other fields that only matter for NPM publication can be left to dumnmy values. This Composite project is not meant to be published to NPM but solely used to create the Composite JS bundle.

Configure Electrode Native to use custom Composite

Once the custom Composite project is created, and published to a git repository, the next step is to configure Electrode Native so that it relies on this custom Composite project rather than its own.

Through Cauldron

If you want to use a custom Composite repository foo stored in GitHub under user user, your compositeGenerator configuration should be as follow :

"config": {
  ...
  "compositeGenerator": {
    "baseComposite": "git+ssh://github.com/user/foo.git"
  }
}

It is also possible to specify a specific branch/tag or SHA. For example, using the same repository, but pulling from mybranch, the configuration will be the following :

"config": {
  ...
  "compositeGenerator": {
    "baseComposite": "git+ssh://github.com/user/foo.git#mybranch"
  }
}

As for all configuration stored in the Cauldron, there is no way yet to add or edit the configuration using ern commands. You should manually edit your Cauldron. Also, as a reminder, config objects can be stored at different levels in the Cauldron, respectively :

. Root
|_ Native Application
  |_ Native Application Platform
    |_ Native Application Version

depending on the level of granularity you desire. For exmaple, when looking for configuration for MyApp:android:1.0.0, Electrode Native will first look for a config object at the native application version level, and if not found will bubble up the levels until it finds it (or doesn't).

Through Commands

Electrode Native contains a few commands that are generating a Composite as part of their execution, and that can be used without relying on a Cauldron.

• [ern create-composite]

• ern create-container

• ern run-ios

• ern run-android

• ern start

These commands are exposing a baseComposite option being either a valid git repository path or a local path on the workstation to a custom composite project. Please note that using this option will take precedence over any baseComposite configuration stored in Cauldron. If you are using a Cauldron, there is very limited use to explicitely providing the baseComposite to these command.

This option can however be very useful for experimentation or to test a custom Composite project before committing it to git / using it in Cauldron. For example, if your custom Composite project is stored in /Users/foo/custom-composite you can easily try it out with some of the commands above, before committing it to git / setting it up in Cauldron.

Electrode Native internal flow with custom Composite

When detecting a custom Composite project, Electrode Native will do the following when generating the Composite :

• Clone the Composite repository to a temporary directory

• Checkout specific branch/tag/sha (if any specified)

• Run yarn add for all MiniApps / JS API Implementations part of the Composite (this will update the package.json of the Composite)

• Create the composite-imports.js file, containing all MiniApps/JS API Implementations imports.

This completes the Composite project generation. Optionally, based on the command used, react-native bundle or react-native start will be invoked with index.android.js or index.ios.js as entry-file based on the platform being targeted.

[ern create-composite]: ../../cli/create-composite.md