@vcmap/plugin-cli

@vcmap/plugin-cli

Part of the VC Map Project

Note: This documentation is for version 2, compatible with the VC Map v5. For documentation on version 1 compatible with VC Map v4, see this tag and be sure to install using npm i -g @vcmap/plugin-cli@^1.1.0

The vcmplugin cli helps develop and build plugins for the VC Map.

Features

• Creating basic plugin structure
• Providing plugin development server
• Building plugins for production

Prerequisite

You need nodejs 16 and npm installed on your system to use this tool.

Installation

To install in your project:

npm i -D @vcmap/plugin-cli

To install globally:

npm i -g @vcmap/plugin-cli

Usage

You can use the following workflow to quickly develop plugins. Note, that the @vcmap/plugin-cli does not directly depend on @vcmap/ui to avoid version conflicts in the used API within a plugin. This means, that all commands (except for the create command) must be executed from within an installed plugin cli within the plugin itself using npx. When using the create command, the @vcmap/plugin-cli will automatically be installed as a devDependency in its current major version. You can then use either the scripts defined by the template in your package.json npm start, npm run pack etc. or npx to execute CLI commands.

1. Creating a new plugin

To create a new plugin template, run the following within your projects root:

vcmplugin create

This will open a command prompt helping you to create the basic structure of a plugin. Be sure to check out the peer dependecy section as well.

2. Serving a plugin for development

To serve your plugin in dev mode, run the following within your projects root:

npx vcmplugin serve

The dev mode gives you complete debug information on all integrated libraries (@vcmap/core, ol etc.) By default this command will launch a dev server at localhost:8008 using the @vcmap/ui peer dependency package of your plugin as its base. You can provide an alternate map config if you wish.

This is the dev mode, only your plugin will be served. Any other plugins in the config will be stripped. To view how your plugin integrates with others, use the preview command.

3. Serving a plugin for integration

To serve your plugin in preview mode, run the following within your projects root:

npx vcmplugin preview

The preview mode allows you to view your plugin in its destined environment. You can see how it interacts with other plugins & other customizations applied to a map. Preview will build your plugin continuously and serve the production ready code using a base application. By default, this will launch a dev server at localhost:5005 using the @vcmap/ui package as its base. Alternatively you can provide a URL to a hosted VC Map application and use said application as its base instead.

4. Building a plugin staging application

A staging application creates a full deployable VC Map in the dist folder with the following components.

• compiled @vcmap/ui library and all dependencies
• default @vcmap/ui configurations
• default @vcmap/ui plugins
• compiled plugin which is in development.

Building the staging application will collect all parts and will inject the plugin in development in the default map configuration. The staging application can for example be used to deploy the App in an Apache in a postCommit Pipeline. (See .gitlab-ci.yml for an example).

npx vcmplugin buildStagingApp

To start a webserver to serve the content of the dist folder call npx vite preview; This will start a static webserver on the port 4173.

The Dockerfile in build/staging/Dockerfile can be used to create a Docker Container which serves the content of the dist folder.

npx vcmplugin buildStagingApp
cd dist
docker build -f ../build/staging/Dockerfile -t vcmap:staging .
docker run --rm -p 5000:80 vcmap:staging

5. Building a plugin

To build your project, run the following from within your projects root:

npx vcmplugin build

This will build your application and place it in the dist directory.

6. Integrating a plugin in a productive VC MAP

To pack your project for productive use, run the following from within your projects root:

npx vcmplugin pack

This will create a folder dist with a zip file containing your bundled code and assets. To use the plugin productively in a hosted map, unzip this file on your server to {vcm-root}/plugins and add an entry to your VC MAP config plugins section. This zip file can also be unzipped in the VC Publishers plugins public directory.

About Peer Dependencies

The @vcmap/ui uses some very large libraries, notably CesiumJS. To reduce the amount of traffic generated for loading plugins, all large libraries (see the list below), are provided in production (instead of bundling them into every plugin). This a) guarantees a certain amount of type safety (using the @vcsuite/check parameter assertation library for instance), b) reduces the amount of traffic required to load an application and c) leverages browser caching more readily.

The following libraries are provided by the @vcmap/ui in a deployed application. You should define these as peer dependencies if you use them in your plugin:

• @vcmap/core
• @vcmap/cesium
• ol
• vue
• vuetify

During the build step, these libraries are automatically externalized by the vcmplugin-cli and in production all plugins & the map core share the same cesium library.

But, to make this work, it is important to define these dependencies as peer dependencies of a plugin and that the provided index files are used (over directly importing from the source file).

For instance:

import Cartesian3 from '@vcmap/cesium/Source/Core/Cartesian3.js';

should be rewritten to:

import { Cartesian3 } from '@vcmap/cesium';

What about openlayers?

openlayers provides a special case, since its modules do not provide a flat namespace. To circumvent this limitation, the @vcmap/ui provides a flat namespaced ol.js and a mechanic to rewrite openlayers imports. This is automatically applied by the @vcmap/rollup-plugin-vcs-ol used by the vcmplugin-cli build step. So openlayers imports can be written as:

import Feature from 'ol/Feature.js';

or

import { Feature } from 'ol';

VC Map Plugins

The following defines a plugin in its rough structure. If you use the @vcmap/plugin-cli to create your project, a template already adhering to these specs will be created for you.

• All plugins must provide the following:
  • package.json with name, description, version, author and dependencies.
  • config.json with default parameters for the plugins' configuration.
  • README.md describing the plugins' capabilities and usage.
  • src/index.js JS entry point.
• Plugin names are defined by the plugins' package name and therefore must obey npm package name guidelines:
  • choose a name that
    • is unique
    • is descriptive
    • is lowercase
    • is uri encode-able
    • doesn't start with ., _ or a digit
    • doesn't contain white spaces or any special characters like ~\'!()*"
  • do not use scope @vcmap, since it is only to be used by official plugins provided by virtual city systems. But you are encouraged to use your own scope.
• Plugin dependencies have to be defined in the package.json.
  • dependency: all plugin specific dependencies NOT provided by the @vcmap/ui.
  • peerDependency: dependencies provided by the @vcmap/ui,
  • e.g. @vcmap/core or @vcmap/ui (see About Peer Dependencies for more details)
  • devDependency: all dependencies only required for development, e.g. eslint.
• Plugins can be published to NPM, but should contain both source and minified code to allow seamless integration into the VC Map UI environment. For this reason the package.json of a plugin defines two exports:

{
  ".": "./src/index.js",
  "./dist": "./dist/index.js"
}

Plugin Interface:

Plugins must provide a function default export which returns an Object complying with the VC Map Plugin Interface describe below:

declare interface VcsPlugin<T extends Object, S extends Object> {
    readonly name: string;
    readonly version: string;
    initialize(app: VcsUiApp, state?: S):Promise<void>;
    onVcsAppMounted(app: VcsUiApp):Promise<void>;
    getState():Promise<S>;
    toJSON():Promise<T>;
    destroy():void;
}

declare function defaultExport<T extends Object, S extends Object>(config: T):VcsPlugin<T, S>;

A Simple JavaScript implementation of this interface can be seen below::

// index.js
/**
 * @param {PluginExampleConfig} config
 * @returns {VcsPlugin}
 */
export default function defaultExport(config) {
  return {
    get name() {
      return packageJSON.name;
    },
    get version() {
      return packageJSON.version;
    }, 
    async initialize (app, state) {},
    async onVcsAppMounted(app) {}, 
    async getState() { return {}; },
    async toJSON() { return {}; },
    destroy() {},
  }
}

Notes on Developing

To develop the plugin-cli, be sure to not npm link into plugins, since this will throw the resolver in resolving the @vcmap/ui peer dependency from the current plugin. Instead run npm pack in the plugin cli and install the tarball in the plugin directly.