Building a Package

Packages lie at the heart of Mailspring. Each part of the core experience is a separate package that uses the Mailspring Package API to add functionality to the client. Want to make a read-only mail client? Remove the core Composer package and you'll see reply buttons and composer functionality disappear.

Let's explore the files in a simple package that adds a Translate option to the Composer. When you tap the Translate button, we'll display a popup menu with a list of languages. When you pick a language, we'll make a web request and convert your reply into the desired language.

Package Structure

Each package is defined by a package.json file that includes its name, version and dependencies. Packages may also declare dependencies which are loaded from npm - in this case, the request library. You'll need to npm install these dependencies locally when developing the package.

{
  "name": "translate",
  "version": "0.1.0",
  "main": "./lib/main",
  "description": "An example package for Mailspring",
  "license": "GPL-3.0",
  "engines": {
    "mailspring": ">=0.3.0 <0.5.0"
  },
  "dependencies": {
    "request": "^2.53"
  }
}

Our package also contains source files, a spec file with complete tests for the behavior the package adds, and a stylesheet for CSS:

- package.json
- lib/
   - main.coffee
   - translate-button.cjsx
- spec/
   - main-spec.coffee
- stylesheets/
   - translate.less

package.json lists lib/main as the root file of our package. Since Mailspring runs NodeJS, we can require other source files, Node packages, etc.

Mailspring can read js, coffee, jsx, and cjsx files automatically.

Inside main.coffee, there are three important functions being exported:

require './translate-button'

module.exports =

  # Activate is called when the package is loaded. If your package previously
  # saved state using `serialize` it is provided.
  #
  activate: (@state) ->
    ComponentRegistry.register TranslateButton,
      role: 'Composer:ActionButton'

  # Serialize is called when your package is about to be unmounted.
  # You can return a state object that will be passed back to your package
  # when it is re-activated.
  #
  serialize: ->
      {}

  # This optional method is called when the window is shutting down,
  # or when your package is being updated or disabled. If your package is
  # watching any files, holding external resources, providing commands or
  # subscribing to events, release them here.
  #
  deactivate: ->
    ComponentRegistry.unregister(TranslateButton)

Mailspring uses CJSX, a CoffeeScript version of JSX, which makes it easy to express Virtual DOM in React render methods! You may want to add the Babel plugin to Sublime Text, or the CJSX Language for syntax highlighting.

Package Stylesheets

Style sheets for your package should be placed in the styles directory. Any style sheets in this directory will be loaded and attached to the DOM when your package is activated. Style sheets can be written as CSS or Less, but Less is recommended.

Ideally, you won't need much in the way of styling. We've provided a standard set of components which define both the colors and UI elements for any package that fits into Mailspring seamlessly.

If you do need special styling, try to keep only structural styles in the package stylesheets. If you must specify colors and sizing, these should be taken from the active theme's [ui-variables.less][ui-variables]. For more information, see the [theme variables docs][theme-variables]. If you follow this guideline, your package will look good out of the box with any theme!

An optional stylesheets array in your package.json can list the style sheets by name to specify a loading order; otherwise, all style sheets are loaded.

Package Assets

Many packages need other static files, like images. You can add static files anywhere in your package directory, and reference them at runtime using the mailspring:// url scheme:

<img src="mailspring://my-package-name/assets/goofy.png">

a = new Audio()
a.src = "mailspring://my-package-name/sounds/bloop.mp3"
a.play()

Installing a Package

Mailspring ships with many packages already bundled with the application. When the application launches, it looks for additional packages in ~/Library/Application Support/Mailspring/dev/packages. Each package you create belongs in its own directory inside this folder.

In the future, it will be possible to install packages directly from within the client.