ap3-cli

ap3-cli

A simple CLI for Atlassian Plugins 3 Add-ons

You can install me with:

npm i -g ap3-cli

Usage

ap3 doesn't attempt to do too much. Mainly, it's a helper tool for creating a add-on project scaffold.

Usage: ap3 [-h|--help] <command> [<args>]

The most commonly used ap3 commands are:
    keygen      Generate public and private RSA keys
    new         Generate a new Plugins 3 Add-on scaffold

Options:
  -h, --help     Show usage
  -v, --version  Show version

Getting Started

The ap3-cli simplifies the process of building an Atlassian Add-on using the Express framework through:

• A project scaffold generator with great default settings
• An OAuth public/private key pair generation

On top of that, the generated scaffold bundles the node-ap3 package which greatly simplifies the process of creating remote add-ons.

Create a project

Let's start by creating an add-on project:

ap3 new <project_name>

This will create the following code:

.
├── README.md
├── app.js
├── atlassian-plugin.xml
├── config.json
├── package.json
├── private-key.pem
├── public
│   ├── css
│   │   └── main.css
│   └── js
│       └── main.js
├── public-key.pem
├── routes
│   └── index.js
└── views
    ├── example.jade
    └── layout.jade

Go into your new project directory, then install the dependencies:

npm install

Setting up a Development Environment

At this point, you're all set to run your add-on, but you'll need to have a host for your add-on. You have a few options:

1. You can do all your development work locally using the p3-dev-env-vagrant Vagrant box. This Vagrant box will set up a local JIRA or Confluence VM (using VirtualBox). This is by far the most flexible option.
2. Soon you'll be able to register a local add-on inside an Atlassian OnDemand instance in development mode. STAY TUNED!

Running your Add-on Server

If you've chosen the first option and have a running instance of the Vagrant box, you're all set. Now all you need to do to run your add-on inside your local JIRA or Confluence instance is:

node app.js

This will boot up your Express server on the default port of 3000 and do the following:

• Register your add-on's atlassian-plugin.xml (at http://$hostname:3000/atlassian-plugin.xml) with the host
• Start watching for changes to your atlassian-plugin.xml. If the file is modified, node-ap3 will re-register your add-on with the host.

The Dev Loop

At this point, you can start building your add-on. Changes to views will load automatically, however, if you make changes to any JavaScript, you will need to restart Express. If you want your server to automatically restart when your JavaScript changes, you may want to consider using nodemon or the like.

As you've noticed, node-ap3 automatically registers your add-on with the host when it's started. Another nice feature is that it automatically de-registers it at shutdown <ctrl-c>.

Configuration

The configuration for your add-on is done in two files:

• ./config.json -- This file contains the configuration for each runtime environment your plugin runs in. The file has comments to help you understand the settings available.
• ./atlassian-plugin.xml -- This file is a manifest of all the "plugin points" your add-on uses. To see all of the available plugin point options check out the interactive guides for JIRA or Confluence.

Getting Help or Support

The ap3 tools are currently experimental. With that said, feel free to report issues. If you want to learn more about Atlassian's Plugins 3 framework, you can visit https://developers.atlassian.com.

Contributing

Even though this is just an exploratory project at this point, it's also open source Apache 2.0. So, please feel free to fork and send us pull requests.