Skip to content

package-types.md

Latest commit

 

History

History
82 lines (65 loc) · 4.81 KB

package-types.md

File metadata and controls

82 lines (65 loc) · 4.81 KB

Package types

Note: This feature is currently experimental and not covered by the automated tests.

make-pkg supports an optional <pkg-type> argument that allows creation of specific package types.

Specifying a type implies:

  • A streamlined package-initialization process that skips certain prompts and used appropriate default values.
  • Additionally, type-specific prompts may be presented, and the resulting package may have additional features and/or a different internal structure.
  • Conversely, not specifying a type provides the most flexibility for creating a package that contains a JS library and/or a CLI.

Supported types are:

  • lib: a regular Node.js library package without a CLI.
  • cli: a CLI-only package, with global installation preferred.
  • awf: an Alfred 2 workflow package - see below.

Package type awf: managing development and publication of Alfred 2 workflows

Package of this type

  • must have name suffix .awf
  • complementarily, should define keyword awf via the package.json file (this keyword will be suggested automatically, among others)

This facilitates identifying and searching for Alfred 2 workflow packages in the npm registry.

For publication in the npm registry, the usual naming rules apply, notably: lowercase letters only, no names starting with a period or underscore, and URL-safe characters only.

Example:

$ mkdir strlen.awf   # create package folder - SUFFIX '.awf' REQUIRED
$ cd strlen.awf      # change to it
$ make-pkg awf       # initialize it as type 'awf'

Specifying package type awf changes make-pkg's behavior as follows:

  • Some prompts have type-specific edit-buffer default values and other prompts are skipped altogether:

    • The buffer for the package-description prompt is prefilled with An Alfred workflow , to be completed.
    • The buffer for the keywords prompt is prefilled with several keywords, notably awf.
    • The package is implicitly marked as preferring global installation, and has neither a CLI nor a main library file defined.

  • An additional prompt will ask for the workflow's bundle ID, whose default value is constructed as <your-reverse-domain>.<package-name>; e.g., if you've configured make-pkg with http://net.same2u as your website URL, and the package's name is strlen.awf, the suggested bundle ID is net.same2u.strlen.awf

  • The resulting package-internal folder structure is specialized:

    • Subfolder alfredworkflow/ houses the actual Alfred 2 workflow source.
      • It is an empty workflow whose info.plist file is initialized with the package name, description, and bundle ID. Note that later changes to the package's metadata are not automatically propagated to the workflow.
      • On releasing the package with make release, the new version number is also copied to file alfredworkflow/version, which is where - by convention - the workflow's current version number is maintained.
    • Subfolder archive/ houses the installable *.alfredworkflow archive autogenerated from the workflow source on performing a Git commit. The auto-generated README.md file contains manual-installation instructions that point to the latest archive/*.alfredworkflow file for easy download and installation directly from GitHub.
    • CLI installAwf is placed in bin/ and installed as a post-installation and post-uninstallation hook, which comes into play when users install the published package from the npm registry: on installation, it triggers import of the workflow into Alfred; on uninstallation of the npm package, the workflow is also removed from Alfred.

  • A custom-initialization step is performed at the end:

    • Since the workflow source code will remain inside the package folder's alfredworkflow/ subfolder, it must be symlinked to from the folder in which Alfred 2 maintains all its installed workflows - only then will you be able to use this in-development workflow from Alfred and edit it in Alfred's Preferences application.
    • Helper CLI awf facilitates creating this symlink, so - if not already installed - you will be prompted to install it.
    • Note that if an installed workflow with the same bundle ID already exists, you will be offered to move it to your package's alfredworkflow/ folder, and have its original folder replaced with a symlink there - this is handy if you've originally created a workflow directly in Alfred and later decide to turn it into a package for sharing.
    • After creating the symlink, you are prompted to open the new workflow for editing in Alfred Preferences.app.