mirror of https://github.com/embarklabs/embark.git
docs(@embark/site): add migration guide to Embark v5
This commit is contained in:
Jonathan Rainville
Pascal Precht
parent
013599859e
commit
9711790f92
|
|
@ -2,10 +2,10 @@ title: Migrating from Embark 3.x
|
|||
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.
|
||||
|
||||
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
|
||||
|
||||
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';
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
|
|
@ -83,25 +83,196 @@ However, we did introduce some small breaking changes. We removed:
|
|||
|
||||
## Updating to v5
|
||||
|
||||
Summary:
|
||||
- Contract config
|
||||
- Removed the deployment section (now all part of blockchain config)
|
||||
- `contracts` renamed `deploy` to match `beforeDeploy` and `afterDeploy` and for tests
|
||||
- Blockchain config
|
||||
- A lot of new defaults, so less that you need to configure [Source](/docs/blockchain_configuration.html#Common-Parameters)
|
||||
- A lot of renamed parameters
|
||||
- isDev: `miningMode: 'dev'`
|
||||
- mineWhenNeeded: `miningMode: 'auto'`
|
||||
- ethereumClientName: `client`
|
||||
- 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)
|
||||
- Now is the only source for accounts [Source](/docs/blockchain_accounts_configuration.html)
|
||||
- Tests
|
||||
- Can now configure module configuration
|
||||
- Storage, namesystem (ENS) and communication modules can now be configured
|
||||
- Configure them just like in the configuration files
|
||||
- Tests default to the `test` environment
|
||||
- Modules are turned off by default
|
||||
- Config merges with `test` and `default` so no need to rewrite all the provider configs
|
||||
- `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
|
||||
Embark's 5th version is full of improvements, especially in the configurations, all to make your life easier.
|
||||
|
||||
In this guide, we'll go through the different breaking changes introduced in Embark 5, that will let you upgrade from Embark 4.0.
|
||||
|
||||
### Better Smart Contract configuration
|
||||
|
||||
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).
|
||||
|
||||
1. The `deployment` section was removed
|
||||
- It was moved to the Blockchain configuration as `endpoint`, which is way simpler than before
|
||||
- The accounts were also moved to the Blockchain configuration
|
||||
2. `contracts` has been renamed to `deploy`
|
||||
- The goal is to match the rest of the properties, i.e. `afterDeploy` and `beforeDeploy`
|
||||
- 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)
|
||||
3. New `dappConnection` variable: `$EMBARK`
|
||||
- This tells the Dapp to connect to Embark's proxy and node
|
||||
- Doing so let's you use the same accounts for deployment **and** in the Dapp
|
||||
- Plus, it let's you benefit from a couple of other features inside your Dapp
|
||||
- We recommend putting `$EMBARK` first in the `dappConnection` array in development, as it's the easiest way to develop your Dapp
|
||||
|
||||
|
||||
### 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`.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue