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.
Before you begin
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
Updating the CLI.)
Create your task
Create your task
We'll be developing in Studio, Airplane's development tool for building
tasks and views. For this guide, we recommend using Studio with a local development server in a new,
empty directory.
shellCopied1# mkdir airplane-getting-started-javascript2# cd airplane-getting-started-javascript3airplane dev
Navigate to Studio in your browser.
To create a new task, click the
New
button in the upper right.
Select
Task
to create a new task.
Choose
JavaScript
to specify a JavaScript task. Name your task Country lookup
. You can add a
description to the task if you like.
Click
Create
to create your task. 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:typescriptCopied1// country_lookup.airplane.ts2import airplane from "airplane";34export default airplane.task(5{6slug: "country_lookup",7name: "Country lookup",8parameters: {9code: {10name: "Country code",11type: "shorttext",12},13},14},15async (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.shellCopied1# Install the dependency. This should update package.json and package-lock.json automatically.2npm 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
)typescriptCopied1// country_lookup.airplane.ts2import airplane from "airplane";3import { request, gql } from "graphql-request";45// We'll run the following query against the countries endpoint:6const endpoint = "https://countries.trevorblades.com/graphql";7const query = gql`8query Query($code: ID!) {9country(code: $code) {10name11native12capital13emoji14currency15languages {16code17name18}19}20}21`;2223export default airplane.task(24{25slug: "country_lookup",26name: "Country lookup",27parameters: {28code: {29name: "Country code",30type: "shorttext",31},32},33},34async (params) => {35const variables = {36code: params.code,37};38// We can request with a single line of code:39const data = await request(endpoint, query, variables);40// The return value becomes the output of the task.41// Airplane supports any JSON-serializeable output.42return 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
Test your task locally
You can test your task locally by executing your task 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
Deploy your task
You can deploy the task via the CLI:
shellCopied1airplane 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
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: