embarklabs
/
embark
mirror of https://github.com/embarklabs/embark.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs(@embark/site): add migration guide to Embark v5

This commit is contained in:
Jonathan Rainville 2019-11-13 15:48:22 -05:00 committed by Pascal Precht
parent 013599859e
commit 9711790f92
1 changed files with 196 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

221
site/source/docs/migrating_from_3.x.md
View File

@ -2,10 +2,10 @@ title: Migrating from Embark 3.x
layout: docs layout: docs
--- ---
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 this guide we'll discuss the few steps to take a project from Embark 3.2.x to 4.x.
If you already have 4.x, you can then upgrade to Embark 5 by continuing [below](/docs/migrating_from_3.x.html#Updating-to-v5).
## Upgrading to v4 ## Upgrading to v4
In order to take an existing Embark 3.2.x project to version 4.x, the following steps are required: In order to take an existing Embark 3.2.x project to version 4.x, the following steps are required:
@ -71,7 +71,7 @@ Remove the following import from your application:
import web3 from 'Embark/web3'; import web3 from 'Embark/web3';
``` ```
### Updating blockchain configurations ### Updating Blockchain configurations
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](/docs/blockchain_accounts_configuration.html) in our docs. 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](/docs/blockchain_accounts_configuration.html) in our docs.
@ -83,25 +83,196 @@ However, we did introduce some small breaking changes. We removed:
## Updating to v5 ## Updating to v5
Summary: Embark's 5th version is full of improvements, especially in the configurations, all to make your life easier.
- Contract config
- Removed the deployment section (now all part of blockchain config) In this guide, we'll go through the different breaking changes introduced in Embark 5, that will let you upgrade from Embark 4.0.
- `contracts` renamed `deploy` to match `beforeDeploy` and `afterDeploy` and for tests
- Blockchain config ### Better Smart Contract configuration
- A lot of new defaults, so less that you need to configure [Source](/docs/blockchain_configuration.html#Common-Parameters)
- A lot of renamed parameters One of the two configurations that changed the most is the Smart Contract configuration. The goal of this change is to make this file **only** about Smart Contracts. That way, no more confusing connection values and accounts. Those were moved to the blockchain config and will be discussed [just below](/docs/migrating_from_3.x.html#Blockchain-config).
- isDev: `miningMode: 'dev'`
- mineWhenNeeded: `miningMode: 'auto'` 1. The `deployment` section was removed
- ethereumClientName: `client` - It was moved to the Blockchain configuration as `endpoint`, which is way simpler than before
- New `endpoint` parameter that let's you connect to an external endpoint or configure more easily which local endpoint to start [Source](/docs/blockchain_configuration.html#Parameter-descriptions) - The accounts were also moved to the Blockchain configuration
- Now is the only source for accounts [Source](/docs/blockchain_accounts_configuration.html) 2. `contracts` has been renamed to `deploy`
- Tests - The goal is to match the rest of the properties, i.e. `afterDeploy` and `beforeDeploy`
- Can now configure module configuration - And also enables us to add new features for `embark test`, whereby you can modify the Blockchain and module configs in each test. Read more [here](/docs/migrating_from_3.x.html#Tests)
- Storage, namesystem (ENS) and communication modules can now be configured 3. New `dappConnection` variable: `$EMBARK`
- Configure them just like in the configuration files - This tells the Dapp to connect to Embark's proxy and node
- Tests default to the `test` environment - Doing so let's you use the same accounts for deployment **and** in the Dapp
- Modules are turned off by default - Plus, it let's you benefit from a couple of other features inside your Dapp
- Config merges with `test` and `default` so no need to rewrite all the provider configs - We recommend putting `$EMBARK` first in the `dappConnection` array in development, as it's the easiest way to develop your Dapp
- `deployement` section removed
- You can now configure the accounts and the endpoint in the `blockchain` section
- `contracts` renamed `deploy` and put inside the `contracts` section ### Simplified Blockchain configuration
The Blockchain configuration changed a lot, but in a good way, as it's **way** simpler now. Hopefully, with all those changes, you'll have an easier time understanding how the different configurations work.
1. Defaults everywhere!
- Most of the configs you were used to seeing in Embark 4 are simply defaults in Embark 5
- That means you don't have to specify them
- You can find the basic configurations [here](/docs/blockchain_configuration.html#Common-Parameters)
- If you want to modify some of the advanced parameters, you always can. Just put them in the `clientConfig` object. You can see all the options [here](/docs/blockchain_configuration.html#Advanced-parameters)
2. There were a couple of renamed parameters:
- `isDev` => `miningMode: 'dev'`
- This enables you to control the node's mining mode with only one option, instead of two (`isDev` and `mineWhenNeeded` were both removed)
- `mineWhenNeeded` => `miningMode: 'auto'`
- As said above, we combined the two options into `miningMode`
- `auto` is the same as `mineWhenNeeded: true`
- `ethereumClientName` => `client`
- Just a basic rename, because it's shorter and is more agnostic
3. New `endpoint` parameter
- This new parameter is the replacement for the Smart Contract configuration's `deployment` section
- Before, you had to set `host`, `port` and `type` in the `deployement` section of the Smart Contracts configuration
- Now, all the options are in `endpoint`
- For example, you can just put `ws://localhost:1234` and Embark will connect to it
- If the connection doesn't work, Embark will start the node using the endpoint
- This makes it easier to connect to external nodes or change the local node configurations
4. The Blockchain configuration is now the **only** source of accounts
- In Embark 4, there were `account` arrays in both the Smart Contract and Blockchain configs
- In Embark 5, there is only a blockchain `accounts` array
- The accounts there will be used for Smart Contract deployment, node creation **and** in the Dapp
- Before you could see the accounts in your Dapp, but couldn't use them
- Now, you can fund them, use them and debug with them
- This is thanks to our new proxy
- All you have to do is set `$EMBARK` as the `dappConnection` in Smart Contracts configuration to connect to Embark's proxy in your Dapp
Here is an example of how simple your Blockchain configuration can look now:
```javascript
module.exports = {
default: {
enabled: true,
client: "geth"
},
development: {
endpoint: 'ws://locahost:1234',
clientConfig: {
miningMode: 'dev'
},
accounts: [
{
mnemonic: "12 word mnemonic",
balance: "5ether",
numAddresses: 10
}
]
}
}
```
This will connect to a node started on you machine on the port `1234`, using a Websocket provider. If the node is not started, Embark will start it for you using Geth.
The accounts used for deployment will be the ones coming from a mnemonic, all funded with 5 ETH.
You can even use those accounts in your Dapp to test Smart Contract interactions, if `$EMBARK` is set in `dappConnection` in your Smart Contracts configuration.
You could remove the `endpoint` and `accounts` and Embark would still work with its defaults.
### Communication configuration
This is a very simple change, but in Embark 5, a specific node is started when using a Communication service like Whisper.
That means that if in your Communication configuration, you still point to the original port, it will conflict.
All you have to do is change that port (usually `8546`) to something else, say `8557`.
Here's what an updated Communication configuration would look like:
```javascript
module.exports = {
default: {
enabled: false,
provider: "whisper",
available_providers: ["whisper"],
connection: {
host: "localhost",
port: 8557,
type: "ws"
}
}
}
```
### Tests
There were few breaking changes related to `embark test`, mostly new features.
1. The `deployment` section was removed
- Much like the changes above, the `deployment` section has been deprecated
- You can still connect to an extenral node in tests and use custom accounts, it's just simpler
- You can now add a `blockchain` section in the `config` function's object and use the `endpoint` and `accounts` options
2. `contracts` was renamed `deploy`
- Again, the test configs match the actual configs
- You now have the `contracts` section which represents the Smart Contract configuration, so you need the `deploy` parameter for the Smart Contract list
- See the example below
3. New module configs
- You can now configure the namesystem on a per test basis
- Storage, Namesystem and Communication modules are disabled by default to speed up the test
- You can enable them in your normal configuration files by adding the `test` environment and putting `enabled: true`
- Just like normal environments, the `test` environment merges with the `default` section
- All tests now default to the `test` environment, but you can still change this with `--environment`
Example of a test with the new configs:
```javascript
config({
blockchain: {
accounts: [
{
mnemonic: "12 word mnemonic",
balance: "5ether",
numAddresses: 10
}
]
},
contracts: {
deploy: {
"SimpleStorage": {
args: [100]
}
}
},
namesystem: {
enabled: true,
register: {
"rootDomain": "test.eth"
}
}
});
describe(() => {
// Tests here
});
```
This example deploys one Smart Contract, SimpleStorage, using the first of 10 accounts, generated from the mnemonic, which will be funded to 5 ETH.
The Namesystem will also be enabled, with a root domain of `test.eth`, meaning you will be able, in your tests, to do `EmbarkJS.Names.resolve('test.eth')` and it will resolve to the owner of the name (the default account).
Like before, those configs are all optional; but they allow you more flexibility, with simpler configuration objects that are easier to understand.
### Library and Version updates
#### NodeJS
To upgrade to Embark 5, you will first need to install Node.js version 10.17 or above, but not beyond 10.x for now.
The reason for that limit is because 12.x cause issues with some of the underlying Embark dependencies, which do not support Node 12.x yet.
#### Version manager
In Embark 4, you could select the version of a couple of libraries in `embark.json`'s `versions` object. As of Embark 5, only `solc` is available to modify.
We deprecated the other libraries because they were rarely changed and most importantly, because their different versions had breaking changes that were annoying to support at the same time. With those deprecations, we ensure you the best experience possible when using the libraries offered.
#### ipfs-api
We upgraded from the old `ipfs-api` to `ipfs-http-client`, because the former was deprecated.
For most of you, no change is required, since EmbarkJS handles the API changes.
However, if you did import `ipfs-api` yourself in your front-end Dapp, you'll need to change it to `ipfs-http-client`, because `ipfs-api` is no longer installed as part of Embark 5.
Also, if you'll be using it directly, be sure to review the [docs for `ipfs-http-client`](https://github.com/ipfs/js-ipfs-http-client#usage) as there have been some API changes relative to `ipfs-api`.