Nationwide Polamorous Matrimony

    This package has been deprecated

    Author message:

    Deprecated and replaced by feebs-cli

    ap3-cli

    0.2.5 • Public • Published

    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://:3000$hostname/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.

    Keywords

    none

    Install

    npm i ap3-cli

    DownloadsWeekly Downloads

    4

    Version

    0.2.5

    License

    Apache 2.0

    Last publish

    Collaborators

    • rmanalan