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
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
:shellCopied1airplane tasks init
You'll be prompted for details. Make sure to choose
JavaScript
for the kind of task:Copied1? What should this task be called?2> Country lookup3? What kind of task should this be?4> JavaScript5? 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: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
You can use
airplane dev
to test the task:shellCopied1airplane 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:
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
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: