Create Alfred workflows with ease

Highlights

• Easy input↔output.
• Config and cache handling built-in.
• Fetching remote files with optional caching.
• Publish your workflow to npm.
• Automatic update notifications.
• Easily testable workflows.
• Finds the node binary.
• Support for top-level await.
• Presents uncaught exceptions and unhandled Promise rejections to the user.
  No need to manually .catch() top-level promises.

Prerequisites

You need Node.js 18+ and Alfred 4 or later with the paid Powerpack upgrade.

Install

npm install alfy

Usage

IMPORTANT: Your script will be run as ESM.

1. Create a new blank Alfred workflow.

2. Add a Script Filter (right-click the canvas → Inputs → Script Filter), set Language to /bin/bash, and add the following script:

./node_modules/.bin/run-node index.js "$1"

We can't call node directly as GUI apps on macOS doesn't inherit the $PATH.

Tip: You can use generator-alfred to scaffold out an alfy based workflow. If so, you can skip the rest of the steps, go straight to the index.js and do your thing.

3. Set the Keyword by which you want to invoke your workflow.

4. Go to your new workflow directory (right-click on the workflow in the sidebar → Open in Finder).

5. Initialize a repo with npm init.

6. Add "type": "module" to package.json.

7. Install Alfy with npm install alfy.

8. In the workflow directory, create a index.js file, import alfy, and do your thing.

Example

Here we fetch some JSON from a placeholder API and present matching items to the user:

import alfy from 'alfy';

const data = await alfy.fetch('https://jsonplaceholder.typicode.com/posts');

const items = alfy
	.inputMatches(data, 'title')
	.map(element => ({
		title: element.title,
		subtitle: element.body,
		arg: element.id
	}));

alfy.output(items);

More

Some example usage in the wild: alfred-npms, alfred-emoj, alfred-ng.

Update notifications

Alfy uses alfred-notifier in the background to show a notification when an update for your workflow is available.

Caching

Alfy offers the possibility of caching data, either with the fetch or directly through the cache object.

An important thing to note is that the cached data gets invalidated automatically when you update your workflow. This offers the flexibility for developers to change the structure of the cached data between workflows without having to worry about invalid older data.

Publish to npm

By adding alfy-init as postinstall and alfy-cleanup as preuninstall script, you can publish your package to npm instead of to Packal. This way, your packages are only one simple npm install command away.

{
	"name": "alfred-unicorn",
	"version": "1.0.0",
	"description": "My awesome unicorn workflow",
	"author": {
		"name": "Sindre Sorhus",
		"email": "sindresorhus@gmail.com",
		"url": "https://sindresorhus.com"
	},
	"scripts": {
		"postinstall": "alfy-init",
		"preuninstall": "alfy-cleanup"
	},
	"dependencies": {
		"alfy": "*"
	}
}

Tip: Prefix your workflow with alfred- to make them easy searchable through npm.

You can remove these properties from your info.plist file as they are being added automatically at install time