Begin Plugin Develop

This doc is about how to create a maptalks plugin project, and publish it on github and npm to share with community.

The project structure is based on the plugin scaffold project maptalks-plugin, you can also use your own structure you familiar with.

Index

1. Preparation
2. Create project
3. Install dependencies
4. Write code
   • Lint
5. Transpile-and-package
6. Test
7. Publish to github
8. Publish to npm
9. Continuous Integration
10. Share your plugin
11. Demo Plugin Project

Preparation

• Install node.js (>= 6.x)
• Install Browser (Recommend Google Chrome)

Create project

• Name convention. Plugins are usually named in lower case with prefix maptalks., for example, maptalks.myplugin

• Download plugin scaffold project and unzip it, the folder structure is as below:

    |-- .babelrc            # babel config    
    |-- .gitignore
    |-- gulpfile.js         # gulp scripts
    |-- index.js            # main entry of source
    |-- package.json        # package.json
    |-- README.md       
    |-- dist                # distribution folder

• Rename the folder to your plugin's name maptalks.myplugin
• Edit package.json, update the following (you can refer to npm doc for detailed meaning)
  • name
  • version
  • description
  • license
  • repository
  • main
  • author
  • contributors

Install dependencies

Install the project dependencies, in shell:

npm install

Write code

index.js file in root folder is required, which is the main entry of source files.

If your plugin is a simple one, you can write all your code in the index.js, like:

// index.js
import * as maptalks from 'maptalks';

export class HelloLayer extends maptalks.Layer {
    //...
}

If your plugin is complicated, you can organize the source files in "./src" folder, and export API in index.js, e.g.

// index.js
export { default as MyLayer } from './src/MyLayer';
export { default as MyGeometry } from './src/MyGeometry';

Lint

We recommend to use ESLint to check your code style. Most of the popular editors like VSCode have perfect support of ESLint.

You can use maptalks's eslint rules.

Transpile and package

After finishing your code writing, you can use gulp script to build your source files and package them for distribution.

maptalks-plugin provides a gulpfile.js to automate these tasks.

The predefined tasks in gulpfile for building are:

• Transpile to ES5 and build

gulp build

maptalks-plugin uses babel for ES5 transpiling and rollup for packaging, sources files will be transpiled and packaged to maptalks.myplugin.js in "./dist" folder.

• Compress and gzip

gulp minify

This task will compress maptalks.myplugin.js using uglify to maptalks.myplugin.min.js, and generate a gzip file maptalks.myplugin.min.js.gz

• Watch change of sources and rebuild

gulp watch

Test

Test is required for a high-quality project.

You can choose any testing framework to write your tests. maptalks.js and some plugins use mocha and karma. You can take a look if interested.

maptalks-build-helpers in maptalks-plugin's devDependencies adds karma in default as a devDependency, and provides a utility class TestHelper to run karma.

In gulpfile.js, there are 2 commented tasks for testing:

• Start karma and run the tests

$ gulp test

• Start karma, watch change of sources and re-run the tests, really useful for TDD.

$ gulp tdd

Publish to github

At first, git init:

git init
git add .
git commit

Then create a repository on github, name it to maptalks.myplugin, and push your works to the remote:

git remote add origin [email protected]:{USERNAME}/maptalks.myplugin.git
git push -u origin master

Bingo! Share your github link with us.

Publish to npm

When you think your work is ready for the first official publish, you can publish it to npm as the following:

• Set a version

npm version 0.1.0

Usually, version is set according to semantic version.

• Push to github

git push origin master v0.1.0

• Zip and upload to github releases Zip files in "./dist" with file name maptalks.myplugin-0.1.0.zip, and upload it to your github releases and write a release note.

• Publish to npm

npm publish

Publish it to npm, then others can install your plugin by npm install maptalks.myplugin.

Continuous integration

Successful open source projects all use CI services for continuous integration, e.g. travis-ci, CircleCI, appveyor. They are all free to open source projects. You can read related articles if you want to know more about how to use CI services.

Share your plugin

You can submit an issue to us about your plugin, we will proudly publish it to our web sites.

Demo plugin project

Remember the maptalks.isects plugin in Basics? It's a good demo of plugin project, you can clone it and try by yourself.