@vcmap/plugin-cli 2.0.9 → 2.0.10

package/README.md

@@ -178,6 +178,7 @@ to create your project, a template already adhering to these specs will be creat
     - `config.json` with default parameters for the plugins' configuration.
     - `README.md` describing the plugins' capabilities and usage.
     - `src/index.js` JS entry point.
+- A plugin _may_ provide static plugin assets in a `plugin-assets` directory. (See [About Plugin Assets](#About-Plugin-Assets)
 - Plugin names are defined by the plugins' package name and therefore must obey npm [package name guidelines](https://docs.npmjs.com/package-name-guidelines):
     - choose a name that
         - is unique
@@ -191,7 +192,7 @@ to create your project, a template already adhering to these specs will be creat
 - 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](#About_Peer_Dependencies) for more details)
+    - e.g. `@vcmap/core` or `@vcmap/ui` (see [About Peer Dependencies](#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](https://github.com/virtualcitySYSTEMS/map-ui) environment.
@@ -203,10 +204,11 @@ For this reason the package.json of a plugin defines two exports:
 }
 ```
 
-
 ### Plugin Interface:
 Plugins must provide a function default export which returns an Object complying
-with the VC Map Plugin Interface describe below:
+with the VC Map Plugin Interface describe below. This function is passed the current
+configuration of the plugin as its first argument and the base URL (without the filename)
+from which the plugin was loaded as its second argument.
 
 ```typescript
 declare interface VcsPlugin<T extends Object, S extends Object> {
@@ -219,7 +221,7 @@ declare interface VcsPlugin<T extends Object, S extends Object> {
     destroy():void;
 }
 
-declare function defaultExport<T extends Object, S extends Object>(config: T):VcsPlugin<T, S>;
+declare function defaultExport<T extends Object, S extends Object>(config: T, baseUrl: string):VcsPlugin<T, S>;
 ```
 
 A Simple JavaScript implementation of this interface can be seen below::
@@ -229,7 +231,7 @@ A Simple JavaScript implementation of this interface can be seen below::
  * @param {PluginExampleConfig} config
  * @returns {VcsPlugin}
  */
-export default function defaultExport(config) {
+export default function defaultExport(config, baseUrl) {
   return {
     get name() {
       return packageJSON.name;
@@ -237,7 +239,9 @@ export default function defaultExport(config) {
     get version() {
       return packageJSON.version;
     }, 
-    async initialize (app, state) {},
+    async initialize (app, state) {
+      console.log('I was loaded from ', baseUrl);
+    },
     async onVcsAppMounted(app) {}, 
     async getState() { return {}; },
     async toJSON() { return {}; },
@@ -246,6 +250,60 @@ export default function defaultExport(config) {
 }
 ```
 
+### About Plugin Assets
+Plugin assets are considered to be static files, such as images, fonts etc. which shall be
+access from within the plugin. Since plugins have no knowledge of _where_ they will 
+be deployed, the `@vcmap/ui` provides the `getPluginAssetUrl` helper function
+which allows you to generate an asset URL at runtime.
+
+Place all your assets into the `plugin-assets` directory in your plugin (top level). Your
+plugin structure should look something like this:
+```
+-| my-plugin/
+---| src/
+-----| index.js
+---| plugin-assets/
+-----| icon.png
+---| package.json
+```
+
+To access the `icon.png` from within your code, you would do the following:
+```vue
+<template>
+  <v-img
+    :src="icon"
+    alt="plugin-icon"
+    max-width="200"
+  />
+</template>
+
+<script>
+  import { inject } from 'vue';
+  import { getPluginAssetUrl } from '@vcmap/ui';
+  import { name } from '../package.json';
+
+  export const windowId = 'hello_world_window_id_plugin-cli';
+
+  export default {
+    name: 'HelloWorld',
+    components: { VcsButton },
+    setup() {
+      const app = inject('vcsApp');
+
+      return {
+        icon: getPluginAssetUrl(app, name, 'plugin-assets/icon.png'),
+      };
+    },
+  };
+</script>
+```
+You can of course, use `fetch` to retrieve assets in the same fashion. Should you
+wish to use assets (such as images) in your _css_ make sure that they are embedded or
+you will have to use an inline style & a bound vue property, since the helper 
+cannot handle css resources.
+
+If you have to access assets _before_ your plugin is created (in the exported function of
+your plugin code), you will have to use the `baseUrl` provided to you to generate the URL yourself.
 
 ## Notes on Developing
 To develop the plugin-cli, be sure to not `npm link` into plugins, since this will

package/assets/helloWorld/src/helloWorld.vue

@@ -1,9 +1,16 @@
 <template>
-  <v-sheet>
+  <v-sheet class="hello-world">
     <v-card class="pa-2 ma-2">
       <v-container>
         <v-row class="justify-center mb-4">
-          <h1>{{ $t('helloWorld.helloWorld')}}</h1>
+          <h1>{{ $t('helloWorld.helloWorld') }}</h1>
+        </v-row>
+        <v-row class="justify-center mb-4">
+          <v-img
+            :src="logoUrl"
+            alt="plugin-assets example"
+            max-width="200"
+          />
         </v-row>
         <v-row class="justify-center">
           <VcsButton
@@ -18,9 +25,15 @@
   </v-sheet>
 </template>
 
+<style>
+.hello-world {
+  background-color: aqua;
+}
+</style>
 <script>
   import { inject } from 'vue';
-  import { VcsButton } from '@vcmap/ui';
+  import { VcsButton, getPluginAssetUrl } from '@vcmap/ui';
+  import { name } from '../package.json';
 
   export const windowId = 'hello_world_window_id_plugin-cli';
 
@@ -34,6 +47,7 @@
         closeSelf() {
           app.windowManager.remove(windowId);
         },
+        logoUrl: getPluginAssetUrl(app, name, 'plugin-assets/vcs_logo.png'),
       };
     },
   };

package/assets/helloWorld/src/index.js

@@ -4,11 +4,12 @@ import HelloWorld, { windowId } from './helloWorld.vue';
 
 /**
  * @param {T} config - the configuration of this plugin instance, passed in from the app.
+ * @param {string} baseUrl - the absolute URL from which the plugin was loaded (without filename, ending on /)
  * @returns {import("@vcmap/ui/src/vcsUiApp").VcsPlugin<T>}
  * @template {Object} T
  * @template {Object} S
  */
-export default function(config) {
+export default function(config, baseUrl) {
   return {
     get name() { return name; },
     get version() { return version; },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vcmap/plugin-cli",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "A CLI to help develop and build plugins for the VC Map",
   "main": "index.js",
   "type": "module",

package/src/buildStagingApp.js

@@ -6,7 +6,6 @@ import { getConfigJson } from './hostingHelpers.js';
 import { getPluginName } from './packageJsonHelpers.js';
 import buildModule, { getDefaultConfig } from './build.js';
 import setupMapUi from './setupMapUi.js';
-import { replaceAssets } from './pack.js';
 
 
 /**
@@ -28,7 +27,6 @@ export default async function buildStagingApp() {
 
   // copy assets folder if exists
   if (fs.existsSync(resolveContext('plugin-assets'))) {
-    await replaceAssets(path.join(distPath, 'plugins', pluginName, 'index.js'), pluginName);
     await cp(
       resolveContext('plugin-assets'),
       path.join(distPath, 'plugins', pluginName, 'plugin-assets'),

package/src/create.js

@@ -9,6 +9,7 @@ import { LicenseType, writeLicense } from './licenses.js';
 import { getDirname } from './hostingHelpers.js';
 
 export const { version, name } = JSON.parse(fs.readFileSync(path.join(getDirname(), '..', 'package.json')).toString());
+const exec = util.promisify(childProcess.exec);
 
 /**
  * @typedef {Object} PluginTemplateOptions
@@ -22,6 +23,51 @@ export const { version, name } = JSON.parse(fs.readFileSync(path.join(getDirname
  * @property {Array<string>} peerDeps
  */
 
+/**
+ * @enum {number}
+ */
+const DepType = {
+  DEP: 1,
+  PEER: 2,
+  DEV: 3,
+};
+
+/**
+ * @param {Array<string>} deps
+ * @param {DepType} type
+ * @param {string} pluginPath
+ * @returns {Promise<void>}
+ */
+async function installDeps(deps, type, pluginPath) {
+  let save = '--save';
+  if (type === DepType.PEER) {
+    save = '--save-peer';
+  } else if (type === DepType.DEV) {
+    save = '--save-dev';
+  }
+  const installCmd = `npm i ${save} ${deps.join(' ')}`;
+  const { stdout, stderr } = await exec(installCmd, { cwd: pluginPath });
+  logger.log(stdout);
+  logger.error(stderr);
+}
+
+/**
+ * @param {Array<string>} deps
+ * @param {string} pluginPath
+ * @returns {Promise<void>}
+ */
+async function setUiPeerDepVersions(deps, pluginPath) {
+  const uiPackageJsonContent = await fs.promises.readFile(
+    path.join(pluginPath, 'node_modules', '@vcmap', 'ui', 'package.json'),
+  );
+  const uiPackageJson = JSON.parse(uiPackageJsonContent);
+  deps.forEach((dep, index) => {
+    if (uiPackageJson.peerDependencies[dep]) {
+      deps[index] = `${dep}@${uiPackageJson.peerDependencies[dep]}`;
+    }
+  });
+}
+
 /**
  * @param {PluginTemplateOptions} options
  */
@@ -135,21 +181,15 @@ async function createPluginTemplate(options) {
 
 
   logger.spin('installing dependencies... (this may take a while)');
-  const exec = util.promisify(childProcess.exec);
   try {
-    options.peerDeps.push('@vcmap/ui');
-    const installCmd = `npm i --save-peer ${options.peerDeps.join(' ')}`;
-    const { stdout, stderr } = await exec(installCmd, { cwd: pluginPath });
-    logger.log(stdout);
-    logger.error(stderr);
+    await installDeps(['@vcmap/ui'], DepType.PEER, pluginPath);
+    await setUiPeerDepVersions(options.peerDeps, pluginPath);
+    await installDeps(options.peerDeps, DepType.PEER, pluginPath);
     const devDeps = [`${name}@${version}`];
     if (installEsLint) {
       devDeps.push('@vcsuite/eslint-config');
     }
-    const installDevCmd = `npm i --save-dev ${devDeps.join(' ')}`;
-    const { stdout: stdoutDev, stderr: stderrDev } = await exec(installDevCmd, { cwd: pluginPath });
-    logger.log(stdoutDev);
-    logger.error(stderrDev);
+    await installDeps(devDeps, DepType.DEV, pluginPath);
     logger.success('installed dependencies');
   } catch (e) {
     logger.error(e);
@@ -175,9 +215,9 @@ export default async function create() {
   const peerDependencyChoices = [
     { title: '@vcmap/core', value: '@vcmap/core' },
     { title: '@vcmap/cesium', value: '@vcmap/cesium' },
-    { title: 'ol', value: 'ol@~6.13.0' },
-    { title: 'vue', value: 'vue@~2.7.3' },
-    { title: 'vuetify', value: 'vue@~2.6.7' },
+    { title: 'ol', value: 'ol' },
+    { title: 'vue', value: 'vue' },
+    { title: 'vuetify', value: 'vuetify' },
   ];
 
   const questions = [

package/src/hostingHelpers.js

@@ -269,6 +269,16 @@ export async function getMapUiIndexHtml(production) {
   return buffer.toString();
 }
 
+/**
+ * @param {Express} app
+ * @param {string} base
+ */
+export function addPluginAssets(app, base) {
+  app.use(`/${base}/plugin-assets*`, (req, res) => {
+    res.redirect(308, req.originalUrl.replace(`/${base}`, ''));
+  });
+}
+
 /**
  * @param {Express} app
  * @param {import("vite").ViteDevServer} server

package/src/pack.js

@@ -1,21 +1,10 @@
 import fs from 'fs';
-import { readFile, writeFile } from 'fs/promises';
 import archiver from 'archiver';
 import { logger } from '@vcsuite/cli-logger';
 import { getPluginName } from './packageJsonHelpers.js';
 import { resolveContext } from './context.js';
 import build from './build.js';
 
-/**
- * @param {string} fileName
- * @param {string} name
- * @returns {Promise<void>}
- */
-export async function replaceAssets(fileName, name) {
-  let fileContent = await readFile(fileName, { encoding: 'utf8' });
-  fileContent = fileContent.replace(/\.?\/?(plugin-assets)\//g, `plugins/${name}/$1/`);
-  await writeFile(fileName, fileContent);
-}
 
 /**
  * @returns {Promise<void>}
@@ -94,8 +83,6 @@ export default async function pack() {
   const pluginName = await getPluginName();
   logger.spin(`building plugin: ${pluginName}`);
   await build({});
-  await replaceAssets(resolveContext('dist', 'index.js'), pluginName);
-  logger.debug('fixed asset paths');
   await ensureConfigJson();
   logger.debug('ensuring config.json');
   await zip(pluginName);

package/src/preview.js

@@ -7,6 +7,7 @@ import {
   addConfigRoute,
   addIndexRoute,
   addMapConfigRoute,
+  addPluginAssets,
   checkReservedDirectories,
   createConfigJsonReloadPlugin,
   printVcmapUiVersion, resolveMapUi,
@@ -83,6 +84,7 @@ export default async function preview(options) {
 
   addMapConfigRoute(app, options.vcm ? `${options.vcm}/map.config.json` : null, options.auth, options.config, true);
   addIndexRoute(app, server, true, options.vcm, options.auth);
+  addPluginAssets(app, 'dist');
 
   if (!options.vcm) {
     logger.spin('compiling preview');

package/src/serve.js

@@ -10,7 +10,7 @@ import { getContext } from './context.js';
 import {
   addConfigRoute,
   addIndexRoute,
-  addMapConfigRoute,
+  addMapConfigRoute, addPluginAssets,
   checkReservedDirectories,
   createConfigJsonReloadPlugin,
   printVcmapUiVersion,
@@ -114,6 +114,7 @@ export default async function serve(options) {
 
   addMapConfigRoute(app, options.mapConfig, options.auth, options.config);
   addIndexRoute(app, server);
+  addPluginAssets(app, 'src');
   await addConfigRoute(app, options.auth, options.config);
 
   app.use(server.middlewares);