Migrating from Embark 3.x
With the release of version 4, Embark has introduced a few breaking changes that require developers to take action, if they plan to upgrade.
In this guide we’ll discuss the few steps to take a project from Embark 3.2.x to 4.x.
In order to take an existing Embark 3.2.x project to version 4.x, the following steps are required:
- Adding a
generationDirto the project’s
- Updating “magic” EmbarkJS imports
- Installing a blockchain connector
- Updating blockchain account configurations
Let’s walk through them step by step!
Since version 4, Embark generates project specific artifacts. We need to tell Embark where to generate those artifacts. For new projects, this is not a problem as Embark will create the necessary configuration. However, for existing projects, we’ll have to add a
generationDir property to our project’s
The value of
generationDir is the name of the folder in which we want Embark to generate artifacts. For new projects,
artifacts is the default.
Before version 4, EmbarkJS provided a couple of “magic” imports for applications that made it very convenient to get access to EmbarkJS itself, as well as Smart Contract instances.
The EmbarkJS library as well as Smart Contract instances will now be generated artifacts, meaning we’ll have to update our imports to point to the right location.
For EmbarkJS, replace this import:
import EmbarkJS from 'Embark/EmbarkJS';
import EmbarkJS from './artifacts/embarkjs';
Notice that the import path has to match the path we’ve specified in
For Smart Contract instances, replace:
import CONTRACT_NAME from 'Embark/contracts/CONTRACT_NAME';
import CONTRACT_NAME from './artifacts/contracts/CONTRACT_NAME';
Prior to version 4, EmbarkJS exported a Web3 instance as well. This is no longer the case as it caused a lot of compatibility issues with different Web3 versions. Please rely on the globally available Web3 instance instead.
Remove the following import from your application:
import web3 from 'Embark/web3';
As discussed in our guide on using EmbarkJS, EmbarkJS no longer has an opinion about which library to use to connect to a blockchain. You can use any library of your choice, whether it’s
ethers.js or anything else.
All you have to do is installing the library and a dedicated connector plugin. The Embark project already comes with a connector plugin for
web3 and can be installed using either yarn or npm, or Embark’s very own
plugin install command:
$ npm install embarkjs-connector-web3
$ yarn add embarkjs-connector-web3
Embark (development) > plugin install embarkjs-web3-connector<ENTER>
Once installed we need to tell Embark to load the plugin. This is done by adding it to the
embark.json plugins section:
Embark 4 adds some new blockchain account configurations. To try to keep things as simple as possible, these additions are really similar to the ones in the Smart Contract configuration. For more information, please read the Accounts Blockchain configuration guide in our docs.
However, we did introduce some small breaking changes. We removed:
- account: This is completely replaced by the new accounts property (notice the s at the end of accounts). It gives the developer more flexibility. To have exactly the same behavior as before, just use the
nodeAccountsaccount type as described in the docs
- simulatorMnemonic: Removed in favor of Ganache’s default mnemonic. If this functionality is still needed, please specify the desired mnemonic in the blockchain config’s mnemonic account type.