Build a task with code

Airplane makes it incredibly easy to take scripts, code snippets, etc. and turn them into apps ("tasks") that you and your teammates can use.
If you have a simple SQL query, you can use a SQL task to get started quickly. For more complicated logic, external dependencies, etc. you can write tasks in languages like TypeScript, JavaScript, or Python.
In this guide, we'll build a JavaScript-based task that demonstrates using an external library to talk to the Countries GraphQL API.
This guide focuses on JavaScript as an example. Check out the documentation for Python, REST, or Shell for more examples. Shell tasks allow you to provide a Dockerfile-based environment and run arbitrary commands in any language.

Before you begin

If you haven't yet, first install the Airplane CLI by following the instructions at Installing the CLI. (If you have already installed the Airplane CLI, ensure you have the latest version by Upgrading the CLI.)

Create your task

Once you've installed and logged in to the CLI, navigate to the folder where you want to create your task and run init:
shell
Copied
1
airplane tasks init
You'll be prompted for details. Make sure to choose Node for the kind of task:
Copied
1
? What should this task be called?
2
> Country lookup
3
? What kind of task should this be?
4
> Node
5
? Where is the script for this task?
6
> country_lookup.js
7
? Where should the definition file be created?
8
> country_lookup.task.yaml
To use TypeScript, use a .ts extension instead of .js for the script.
This will create a country_lookup.js file that has your code entrypoint, plus a country_lookup.task.yaml file that has your task definition. We'll write a task that, given a country code (e.g. US), returns information about the country. Let's edit the YAML file to configure the basics:
yaml
Copied
1
# country_lookup.task.yaml
2
slug: country_lookup
3
name: Country lookup
4
parameters:
5
- slug: code
6
name: Country code
7
type: shorttext
8
node:
9
nodeVersion: "18"
10
entrypoint: country_lookup.js
This configures a Node 18 task with a single parameter, code, that is the country code our task will receive as a function argument.
For a full reference of available configuration, see Task definition reference.
We're going to be issuing a GraphQL request to the countries API. First, we'll need the graphql-request package. Dependencies can be installed like any normal Node project, via package.json.
shell
Copied
1
# Create an empty package.json file for now.
2
echo '{}' > package.json
3
# Install the dependency. This should update package.json and package-lock.json automatically.
4
npm install graphql-request
Open country_lookup.js in your code editor of choice to implement the actual function.
Airplane expects a single function as the default export from your file. This is what gets executed—parameters are passed in as the first argument (so we can access code via params.code).
javascript
Copied
1
// country_lookup.js
2
import { request, gql } from "graphql-request";
3
4
// We'll run the following query against the countries endpoint:
5
const endpoint = "https://countries.trevorblades.com/graphql";
6
const query = gql`
7
query Query($code: ID!) {
8
country(code: $code) {
9
name
10
native
11
capital
12
emoji
13
currency
14
languages {
15
code
16
name
17
}
18
}
19
}
20
`;
21
22
export default async function (params) {
23
const variables = {
24
code: params.code,
25
};
26
// We can request with a single line of code:
27
const data = await request(endpoint, query, variables);
28
// The return value becomes the output of the task.
29
// Airplane supports any JSON-serializeable output. Objects are formatted into tables:
30
const country = data.country;
31
return country;
32
}
Notice that we return country above. This is a JSON object with simple fields (name) as well as object fields (languages). Airplane will automatically render this output in a user-friendly manner:

Test your task locally

You can use airplane dev --editor to test the task:
Copied
1
$ airplane dev --editor country_lookup.task.yaml
(Note that this will call through to node and requires you have Node installed already.)
This will ask you interactively for the parameters (in this case, just the country code). Try a few examples like US, BR, or JP:
Copied
1
Output for task country_lookup:
2
3
name
4
Brazil
5
6
native
7
Brasil
8
9
capital
10
Brasília
11
12
emoji
13
🇧🇷
14
15
currency
16
BRL
17
18
languages
19
+------+------------+
20
| code | name |
21
+------+------------+
22
| pt | Portuguese |
23
+------+------------+

Deploy your task

You can deploy the task via the CLI:
shell
Copied
1
airplane deploy country_lookup.task.yaml
2
# Alternatively, to look for and deploy all tasks in the current directory:
3
# airplane deploy .
Once deployed, find the task in your Library to see your task in action!
That's it! Try executing a lookup for US:

Wrapping up

That's it! It took just a few simple commands to deploy a JavaScript task to Airplane. Adding GraphQL support simply requires installing a package.
For further details, check out: