adobexd/xdpm

A helper CLI for XD plugin development

xdpm

xdpm is a command line tool that makes it easy to develop Adobe XD plugins. It is capable of the following tasks:

• bootstrap: Creates a new plugin scaffold: headless, panel, react, modal. Optionally specify the name for your new plugin's directory.
• install: copies one or more plugins in a develoment folder into Adobe XD's develop folder
• watch: Watches a plugin folder and copies it into Adobe XD whenever the contents change
• validate: Validates a plugin's manifest to ensure that it will be accepted by XD.
• package: Packages a plugin folder into an xdx file suitable for distribution
• ls: Lists plugins installed in Adobe XD in development mode.

Install

npm install -g @adobe/xdpm

If you've cloned the repository:

npm install
npm link

Bootstrapping a plugin

any of the following:

xdpm bootstrap                        # Bootstrap a headless plugin
xdpm bootstrap my-panel               # Bootstrap a headless plugin in dir ./my-panel
xdpm bootstrap panel                  # Bootstrap a panel plugin
xdpm bootstrap panel my-panel         # Bootstrap a panel plugin in dir ./my-panel

Plugin type options:

• headless (default)
• panel
• modal
• react

Installing a plugin

xdpm install                                                    # Install the current folder into Adobe XD
xdpm install path/to/plugin                                     # Install the specified folder into Adobe XD
xdpm install -w release                                         # Install to Adobe XD CC Release (`r` is also valid; default)
xdpm install -w prerelease                                      # Install to Adobe XD CC Prerelease (`p` is also valid)
xdpm install -o                                                 # Overwrite plugin if it exists
xdpm install -c                                                 # Install cleanly (remove existing)
xdpm install --ignore-files ".xdignore, .npmignore"             # Override default list of .*ignore files ".gitignore, .xdignore, .npmignore"

You can install a plugin folder into Adobe XD using xdpm install [...folders]. If you don't specify a folder xdpm install assumes your current directory is a plugin and will install it into Adobe XD.

If the plugin folder is not a valid XD plugin, you'll receive an error upon attempting to install it. If the plugin is already installed in XD, you'll need to specify -o to overwrite the plugin.

Watching a plugin

xdpm watch                                                      # Watch current folder and install changes into Adobe XD
xdpm watch path/to/plugin                                       # Watch the specified folder and install changes into Adobe XD
xdpm watch -w release                                           # Install to Adobe XD CC Release (`r` is also valid; default)
xdpm watch -w prerelease                                        # Install to Adobe XD CC Prerelease (`p` is also valid)
xdpm watch -c                                                   # Perform clean installs when watching
xdpm watch --ignore-files ".xdignore, .npmignore"               # Override default list of .*ignore files ".gitignore, .xdignore, .npmignore"

When developing a plugin, you can work directly in Adobe XD's develop folder, but this may not fit your particular workflow. In this case, you can invoke xdpm watch on a folder (or the current directory) and whenever changes are made, xdpm install will be automatically invoked to reinstall the plugins. This can simplify your development process significantly, especially if you don't use a build process.

Validating plugin manifests

xdpm validate [...folders]           # Validate the manifests in the list of folders

You can validate that a manifest is correct using this command. Any errors found will be listed; otherwise the report will be that the plugin validated successfully.

Packaging plugins

xdpm package [...folders]            # Create Adobe XD package

When you're finished with a plugin, you can simply zip the folder and rename the file to an .xdx extension. If you are using a build process, however, you may have additional files you want to exclude when building the package. xdpm package can perform the compression steps for you, but will also read the .gitignore, .npmignore, and a special .xdignore file in your plugin's folder and skip adding those to the zip file. This can allow you to easily exclude files from the final package that you distribute to others.

NOTE: Plugins that fail validation will not be packaged.

Listing installed plugins

xdpm ls                              # List installed plugins in Adobe XD's `develop` folder
xdpm ls -w release                   # List installed plugins in Adobe XD's `develop` folder (default)
xdpm ls -w prerelease                # List installed plugins in Adobe XD Prerelease `develop` folder

You can install plugins that are currently installed in Adobe XD using ls.

Help

Usage:
  xdpm [OPTIONS] <command> [ARGS]

Options:
  -c, --clean BOOL       Clean before install
  -j, --json BOOL        If true, indicates that JSON output should be
                         generated
  -o, --overwrite BOOL   Allow overwriting plugins
  -w, --which [VALUE]    Which Adobe XD instance to target. VALUE must be
                         either
                         [r|p|d|release|pre|prerelease|dev|development]  (Default is r)
  -k, --no-color         Omit color from output
      --debug            Show debug information
      --ignore-files     Provide a custom list of .*ignore files, to override default ".gitignore, .xdignore, .npmignore"
  -h, --help             Display help and usage details

Commands:
  install                Install a plugin in development mode
  ls                     List all plugins in development mode
  package                Package a plugin
  validate               Validate a plugin's manifest
  watch                  Watch a plugin directory. If no directory is
                         specified, `.` is assumed

LICENSE

Apache 2.0

DISCLAIMER

You use this utility at your own risk. Under no circumstances shall Adobe be held liable for the use, misuse, or abuse of this utility.

Use of this utility means that you agree to Adobe's Terms of Use and the Adobe Developer Additional Terms.

xdpm's Issues

Request: xdpm should provide command to output installed directory

xdpm provides a mechanism for developers to sync their code against the development folder. However for plugins that use npm packages this means building your package with a third party tool (like rollup, webpack, or parcel) and then executing xdpm as a second command or running a second tab to run the watcher.

This effectively doubles the number of watchers (one for the package tool and one for xdpm).

I'd like to propose adding a where command that only outputs the developer install directory (which may be different than running other npm modules that expose where,which, or locate).

The command xdpm where should only output a directory:

Example:
<<adobe xd install>>/develop

which can then be passed to cli commands as an output directory

OR

The command should be usable from within a script (for use with rollup, webpack, parcel, etc...) like so:

const xdWhere = require('@adobe/xdpm/commands/where');
const path = require('path');

module.exports =  {
  entry: 'main.js',
  output: path.resolve(xdWhere(), 'main.js'),
  plugins: [
    copyPlugin(['.json'])
  ]
}

This enables developers to quickly get started when using npm (or even transpiling)

Inform update of the format of manifest.json (xdpm 1.x.x)

Summary

As of XD 17.x update, old (~16.x ), manifest.json format will not work in latest XD. So please announce the update with the tool used for development every day.

For who

The developer ser uses the old format of manifest.json and xdpm 1.1.x.

How

xdpm informs developers about the updates of manifest.json. When they execute xdpm commands (validate, package, deploy, etc.) output (info) of xdpm accompanies URL of the updated manifest.json doc.

I guess, xdpm can notice the old fashioned manifest.json be validating "host.minVersion"

Setup linter

Please setup code linting utility such as eslint, prettier.

Request: Validating the menus (uiEntryPoints)

Currently (v1.1.2), xdpm checks if the uiEntryPoints exists or not. However, it would be better to check the "structure" of uiEntryPoints.
For example, to check the nesting level of submenus, and required field.

xdpm/lib/validate.js

Lines 90 to 93 in 0269854

	// validate entry points (this is a bit lax ATM, but easy verifiable with XD)
	if (!manifest.uiEntryPoints) {
	errors.push("F1040: Manifest must contain UI entry points.");
	}

xdpm helped saved a lot of my development time, and I believe that this tool accelerates the speed of developing plugins for many developers.

Thanks,

xdpm searches for wrong folder

When I'm trying to run xdpm install, xdpm watch or xdpm ls with the Release version of Adobe XD (it works for the prerelease version with -w p) on Windows, I get the following error message:

ERROR: Could not locate C:\Users\pablo\AppData\Local\Packages\Adobe.CC.XD.adky2gkssdxte\LocalState. Do you have the release version of Adobe XD CC installed?

The problem here is that xdpm searches for an Adobe.CC.XD.adky2gkssdxte-folder, while only an Adobe.CC.XD_adky2gkssdxte-folder exists (_ instead of .).

Validate website and helpUrl fields in manifest

https://github.com/AdobeXD/xdpm/blob/master/lib/validate.js

Add PR template

Autoreload + autoexecute

Hi all, this is a very speculative exploration, but I thought it might be worth doing in the open, since I'd wager most of us have wished plugins would autoreload (any maybe even re-run) during development.

I've made a branch here, which for now, is meant to get feedback on both the idea and the approach.

It's definitely not fully fleshed out, and comes with limitations at the moment, including:

1. Doesn't support Windows yet
2. Probably doesn't support panels (currently in prerelease)
3. Various rough edges (still an early idea)

https://github.com/AdobeXD/xdpm/tree/osa

Usage:

$ xdpm watch -r -u "Create Rectangle" -x "Create Rectangle"

Where:
-r = autoreload
-u [command name] = autoundo, if last action matches the command name passed
-x [command name] = autoexecute

`npm install -g @adobe/xdpm` does not install dependent packages

Reproducing steps

1. npm install -g @adobe/xdpm
2. cd pugin-development-folder
3. xdpm install

then it throws following error

module.js:545
    throw err;
    ^

Error: Cannot find module 'cli'
...

Otherwise, git clone, npm install and npm link installation works fine.

Update Developer Terms Link

The link displayed by xdpm has an encoded date. Should link to http://www.adobe.com/go/developer-terms instead.

Setup develop branch

This is just an idea. But I'm always afraid to create PR for the master branch.

According to A successful Git branching model, the master branch should point out the latest release.

We consider origin/master to be the main branch where the source code of HEAD always reflects a production-ready state.

Expected Behaviour

Keep the master branch as same as the latest release on npm.
and use the develop branch for future release

Actual Behaviour

xdpm does not have develop branch

Reproduce Scenario (including but not limited to)

N/A

Steps to Reproduce

N/A

Platform and Version

N/A

Sample Code that illustrates the problem

N/A

Logs taken while reproducing problem

N/A

Add support for building in a Linux environment

While this might seem a bit strange, building in a Linux environment could be extremely useful since it allows for building on nearly every CI/CD system. Also, this doesn't seem to be too difficult. It wouldn't require much change (just document that "on Linux, some commands might not work as expected," since the only command which would get used would be "build" – that install doesn't work should be obvious).

I might be wrong here, but from what it looks like, the only thing that's between me and building on my CI/CD server is this line. If you only replace that line with a warning (leading to xdpm not aborting in the build command on Linux), that would prettty much be the only thing that's needed...

Add optional list for .ignore files

Feature Request

How about adding an option to pass extra list of .*ignore files to install command, to get more flexibility to end user? Something like:

xdpm install --ignore-files ".gitignore, .xdignore, .npmignore"

Now it's hardcoded value here https://github.com/AdobeXD/xdpm/blob/master/commands/install.js#L83

Use case

I've added main.js file to .gitignore, because it's not expected for me to have a git diff after each new build. As result I can't use xdpm to automate my build process.

I'm ready to implement this feature and create a PR, if there are no objections

Console update v2

Corresponding to AdobeXD/plugin-docs#206,
Please update validator of manifest.json aka. validate.js

Subfolders are breaking the build process

I am a big fan of xdpm so far. But I am running into a problem when I have subfolders in my project structure (e.g. additional libraries, config files etc.)

e.g. "./data/samples/sample1.json"

I think xdpm is not creating all folders recursively. Right now I cannot use xdpm.
Or am I just missing something?

Here is the error log:

INFO: Boilerplate changed; reinstalling...
fs.js:902
  return binding.mkdir(pathModule.toNamespacedPath(path),
                 ^

Error: ENOENT: no such file or directory, mkdir '/Users/simonwidjaja/Library/Application Support/Adobe/Adobe XD CC/develop/com.trendspurt.xd.boilerplate/src/data/wireframes/mobile/wires'
    at Object.fs.mkdirSync (fs.js:902:18)
    at files.forEach.file (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/commands/install.js:90:20)
    at Array.forEach (<anonymous>)
    at args.map.pluginToInstall (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/commands/install.js:85:15)
    at Array.map (<anonymous>)
    at install (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/commands/install.js:39:26)
    at FSWatcher.watcher.on.debounce (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/commands/watch.js:76:13)
    at Timeout.later [as _onTimeout] (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/node_modules/debounce/index.js:27:23)
    at ontimeout (timers.js:466:11)
    at tryOnTimeout (timers.js:304:5)
Simons-MBP-2:dist simonwidjaja$ xdpm watch
path.js:1087
          cwd = process.cwd();
                        ^

Error: ENOENT: no such file or directory, uv_cwd
    at Object.resolve (path.js:1087:25)
    at Function.Module._resolveLookupPaths (internal/modules/cjs/loader.js:435:17)
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:542:20)
    at Function.Module._load (internal/modules/cjs/loader.js:475:25)
    at Module.require (internal/modules/cjs/loader.js:598:17)
    at require (internal/modules/cjs/helpers.js:11:18)
    at Object.<anonymous> (/Data/Temp/MAX2018/XD Lab/Resources/xdpm/index.js:19:17)
    at Module._compile (internal/modules/cjs/loader.js:654:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:665:10)
    at Module.load (internal/modules/cjs/loader.js:566:32)

Add version flag

How about something like xdpm [-v --version] for easily checking which version of the tool is running?

xdpm package should fail with some error code when there are validation errors.

Expected Behaviour

xdpm package should fail with some error code when there are validation errors.

Actual Behaviour

xdpm package shows validation errors but it returns "success" as execution code.

Reproduce Scenario (including but not limited to)

I'm trying to configure plugin auto-build on Bitbucket pipelines. I put some commands including yarn run xdpm package dist.

Auto-build works fine but if (for example) the manifest is not correct - package command fails but Bitbucket shows that build pipeline worked without errors.

Sample Code that illustrates the problem

When I run xdpm from command line and if the manifest is incorrect - it gives following result:

yarn run xdpm package dist
yarn run v1.19.1
$ xdpm package dist
INFO: xdpm 3.0.2 - XD Plugin Manager CLI
INFO: Use of this tool means you agree to the Adobe Terms of Use at
https://www.adobe.com/legal/terms.html and the Developer Additional
Terms at https://wwwimages2.adobe.com/content/dam/acom/en/legal/servicetou/Adobe-Developer-Additional-Terms_en_US_20180605_2200.pdf.
ERROR: Can't package a plugin that has validation errors in the manifest.json:
.icons ({"limit":2}) -> should NOT have more than 2 items
.icons[2].width ({"allowedValues":[24,48]}) -> should be equal to one of the allowed values
.icons[2].height ({"allowedValues":[24,48]}) -> should be equal to one of the allowed values
Done in 0.49s.

It would be great if xdpm returned some error code if package command is failed.

....
error Command failed with exit code 2.

In that case Bitbucket pipeline (and probably other CI tools) would be able to track