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 JavaScript 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
> JavaScript
5
? Where is the script for this task?
6
> country_lookup.airplane.ts

To use JavaScript, use a .airplane.js extension instead of .airplane.ts.

This creates a country_lookup.airplane.ts file where your task code will live. We'll write a task that, given a country code (e.g. US), returns information about the country.

The country_lookup.airplane.ts file contains both the task code and configuration for running the task on Airplane. First, let's edit the configuration:

typescript
Copied
1
// country_lookup.airplane.ts
2
import airplane from "airplane";
3

4
export default airplane.task(
5
  {
6
    slug: "country_lookup",
7
    name: "Country lookup",
8
    parameters: {
9
      code: {
10
        name: "Country code",
11
        type: "shorttext",
12
      },
13
    },
14
  },
15
  async (params) => {
16
  // Rest of code

This configures a JavaScript task with a single parameter, code, that is the country code our task will receive as a function argument. You can find a full reference on configuration options in JavaScript Task configuration.

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 via a package.json file.

shell
Copied
1
# Install the dependency. This should update package.json and package-lock.json automatically.
2
npm install graphql-request graphql

Next, let's implement the actual function.

The second parameter to airplane.task() (after the configuration) is the function that will be executed when the task is run. Parameters are passed in as the first argument (so we can access code via params.code)

typescript
Copied
1
// country_lookup.airplane.ts
2
import airplane from "airplane";
3
import { request, gql } from "graphql-request";
4

5
// We'll run the following query against the countries endpoint:
6
const endpoint = "https://countries.trevorblades.com/graphql";
7
const query = gql`
8
  query Query($code: ID!) {
9
    country(code: $code) {
10
      name
11
      native
12
      capital
13
      emoji
14
      currency
15
      languages {
16
        code
17
        name
18
      }
19
    }
20
  }
21
`;
22

23
export default airplane.task(
24
  {
25
    slug: "country_lookup",
26
    name: "Country lookup",
27
    parameters: {
28
      code: {
29
        name: "Country code",
30
        type: "shorttext",
31
      },
32
    },
33
  },
34
  async (params) => {
35
    const variables = {
36
      code: params.code,
37
    };
38
    // We can request with a single line of code:
39
    const data = await request(endpoint, query, variables);
40
    // The return value becomes the output of the task.
41
    // Airplane supports any JSON-serializeable output.
42
    return data.country;
43
  }
44
);

Notice that we return data.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 to test the task:

shell
Copied
1
airplane dev

This will allow you to develop your task locally in Studio. Select the Country lookup task and try executing it with the country code. Try a few examples like US, BR, or JP:

Developing a JavaScript task calls through to node and requires you have Node.js installed on your machine.

Deploy your task

You can deploy the task via the CLI:

shell
Copied
1
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.