Remix plugin helps you extends the Remix IDE. The goal is to give access of all the features inside Remix and make them available for Ethereum Developers.
Remix Plugin can be use (but not only) for :
- Educational Purpose.
- Smart-Contract library managment.
- Language Service.
- Smart-Contract language compiler.
- Static Analysis.
- Other services...
ALPHA
Use Remix alpha version to test your plugin : http://remix-alpha.ethereum.org/
This version is still a work in progress and some breaks may be expected (especially names). But the overall stucture should remain unchanged.
Installation :
npm install remix-plugin
or with a unpkg :
<script src="https://unpkg.com/remix-plugin"></script>
The plugin client is how you connect your plug to remix.
To import ( the ES6 way) with NPM use:
import { createIframeClient } from 'remix-plugin'
const client = createIframeClient()
Or if you are using unpkg use:
const { createIframeClient } = remixPlugin
const client = createIframeClient()
To leverage Typescript types, you can define some custom apis.
import { remixApi } from 'remix-plugin'
const client = createIframeClient({ customApi: remixApi })
This will provide you all the types of the plugin exposed by the Remix IDE. For example :
client.fileManager.setFile(path, content) // With customApi
client.call('fileManager', 'setFile', path, content) // Without customApi
You'll need Typescript > 3.4 to leverage those types.
Plugins communicate with the IDE through the postMessage
API. It means that PluginClient
needs to know the origin of your IDE.
If you're developping a plugin with your IDE running on localhost
you'll need to specify the port on which your IDE runs :
const devMode = { port: 8000 }
const client = createIframeClient({ devMode })
You can find examples of plugins here :
To test your plugin with remix:
- Go to http://remix-alpha.ethereum.org. (if your localhost is over HTTP, you need to use http for Remix IDE).
- Click on the plugin manager (Plug icon on the left).
- Click on "Connect to a Local Plugin".
- Fill the profile info of you plugin ().
- Click on "ok".
- A new icon should appear on the left, this is where you can find you plugin.
PluginClient
listen on a first handshake from the IDE before beeing able to communicate back. For that you need to wait for the Promise / callback onload
to be called.
client.onload(() => /* Do something */)
client.onload().then(_ => /* Do Something now */)
await client.onload()
To listen to an event you need to provide the name of the plugin your listening on, and the name of the event :
client.on(/* pluginName */, /* eventName */, ...arguments)
For exemple if you want to listen to Solidity compilation :
client.on('solidity', 'compilationFinished', (target, source, version, data) => {
/* Do Something on Compilation */
}
)
See all available event below.
You can call some methods exposed by the IDE with with the method call
. You need to provide the name of the plugin, the name of the method, and the arguments of the methods :
await client.call(/* pluginName */, /* methodName */, ...arguments)
Note:
call
is alway Promise
For example if you want to upsert the current file :
async function upsertCurrentFile(content: string) {
const path = await client.call('fileManager', 'getCurrentFile')
await client.call('fileManager', 'setFile', path, content)
}
Your plugin can emit events that other plugins can listen on.
client.emit(/* eventName */, ...arguments)
Let's say your plugin build a deploy a Readme for your contract on IPFS :
async function deployReadme(content) {
const [ result ] = await ipfs.files.add(content);
client.emit('readmeDeployed', result.hash)
}
Note: Be sure that your plugin is loaded before making any call.
You can test your plugin direcly on the alpha version of Remix-IDE. Go to the pluginManager
(plug icon in the sidebar), and click "Connect to a Local Plugin".
Here you can add :
- A name : this is the name used by other plugin to listen to your events.
- A displayName : Used by the IDE.
- The url : May be a localhost for testing.
Note: No need to do anything if you localhost auto-reload, a new
handshake
will be send by the IDE.
This is not available now.
Your plugin can interact with other plugins through the API. remix-plugin
provide a set of default plugins integrated inside the Remix IDE. Some of the APIs have to be used with caution. So they might ask the permission of the user.
Click on the name of the api to get the full documentation.
API | Name | Permission | Description |
---|---|---|---|
File System | fileManager | ✅ | Manages the File System |
Compiler | solidity | ✅ | The solidity Compiler |
Editor | editor | Enables highlighting in the code Editor | |
Network | network | Defines the network (mainnet, ropsten, ...) and provider (web3, vm, injected) used | |
Udapp | udapp | ✅ | Transaction listener |
This API is a Work In Progress and will be extended in the future.
Every plugin has a status object that can display notifications on the IDE. You can listen on a change of status from any plugin using statusChanged
event :
client.listen('fileManager', 'statusChanged', (status: Status) => {
// Do Something
})
The status object is used for displaying a notification. It looks like that :
interface Status {
key: number | 'edited' | 'succeed' | 'loading' | 'failed' | 'none' // Display an icon or number
type?: 'success' | 'info' | 'warning' | 'error' // Bootstrap css color
title?: string // Describe the status on mouseover
}
- If you want to remove a status use the
'none'
value forkey
. - If you don't define type, it would be the default value ('info' for Remix IDE).
You can also change the status of your own plugin by emitting the same event :
client.emit('statusChanged', { key: 'succeed', type: 'success', title: 'Documentation ready !' })
The IDE can use this status to display a notification to the user.
Remix is using Bootstrap. For better User Experience it's highly recommanded to use the same theme as Remix in your plugin. For that you just have to use standard bootstrap classes.
Remix will automatically create a <link/>
tag in the header of your plugin with the current theme used. And it'll update the link each time the user change the theme.
If you really want to use your own theme, you can use the customTheme
flag in the option :
const client = createIframeClient({ customTheme: true })