Getting started with tasks

This guide will get you up and running with an example JavaScript task. We'll set up a task end to end and explore Airplane features including parameters, outputs, and config variables. (For more detailed Node.js guides, see the Node.js docs.)

Create a task

We'll be creating a task that fetches data from a trivia API and presents a trivia question and answer.
First, let's create a task from the UI. From your home page, click New to reach the New Task page and select Node.

Define your task

Give your task a name (e.g. "Get Trivia Question").
For now, you can leave the description and parameters empty.
Click Continue to skip through the Build and Advanced sections for now. At the last section, click Create task to be taken to your new task's page:
You've created a task, but there's no code backing the task yet! Next, we'll write and deploy some JavaScript to implement our task.

Deploying task code

If you haven't yet, first install the Airplane CLI (airplane) by following the installation instructions. We'll be using airplane to deploy from the terminal.
Once you've installed and logged in to the CLI, you can run the init command shown on the task page:
bash
Copied
1
# airplane init --slug [slug] path/to/new_file.js
2
airplane init --slug get_trivia_question ./get_trivia_question.js
You can choose any path you want for where the script is stored. To use TypeScript, use a .tsextension instead of .js.
This will create a script that looks something like this:
javascript
Copied
1
// Linked to https://app.airplane.dev/t/get_trivia_question [do not edit this line]
2
3
export default async function (params) {
4
console.log("parameters: ", params);
5
}
Airplane looks for the default export function and calls it. The first argument will contain the parameters for the run—more on that later.
As noted by the comment, you're welcome to change the script but leave the first line intact. The Airplane CLI uses that line to identify which task your code corresponds to.
Now you can deploy the task:
bash
Copied
1
airplane deploy ./get_trivia_question.js
This will bundle up the source code, build it, and deploy it to Airplane.
Go back to the task page (or reload it), and you should now be able to execute it!
The task should succeed (but you won't see any useful output):

Adding NPM dependencies and output

Next, let's have this task actually do something. We'll make an HTTP request to http://jservice.io/api/random?count=5 to retrieve (e.g.) 5 trivia questions.
If you haven't yet, let's create an NPM package:
bash
Copied
1
# This creates a package.json file. Make sure you're not in a directory
2
# that already has one!
3
npm init
4
# If you want to skip all the prompts:
5
# npm init -y
Next, let's install the airplane SDK as well as node-fetch:
bash
Copied
1
npm install airplane node-fetch
This should have updated your `package.json` with `airplane` and `node-fetch`. The Airplane CLI looks for `package.json` when deploying and will use it to install dependencies. Both NPM and Yarn lock files are supported.
Update your script with the following code:
javascript
Copied
1
// Linked to https://app.airplane.dev/t/get_trivia_question [do not edit this line]
2
3
import airplane from "airplane";
4
import fetch from "node-fetch";
5
6
export default async function (params) {
7
// Fetch JSON from API
8
const res = await fetch("http://jservice.io/api/random?count=10");
9
const questions = await res.json();
10
11
// Output results as a structured table
12
for (const q of questions) {
13
airplane.appendOutput({
14
id: q.id,
15
question: q.question,
16
answer: q.answer,
17
});
18
}
19
}
And redeploy: airplane deploy ./get_trivia_question.js
Now try executing the task again, and you should see a table of questions!
Here, we've used airplane.appendOutput from the SDK to hook into the Outputs feature of Airplane. This allows us to log both structured and unstructured data from the task and surface that to the user. When objects are outputted, Airplane automatically collects the object into a table with object keys as columns.
You can filter/search in a table directly from Airplane as well as export to CSV:

Adding parameters

Next, let's add a parameter so that we can configure how many trivia questions are returned.
Click Edit task from the task page:
And click Add Parameter. Give it a name, "Number of Questions", and select Integer for the Type. Click Update task to save.
Note the text saying Slug is number_of_questions. This is the parameter slug and serves as an identifier you'll need from your code.
Let's use the parameter from our code. Airplane automatically passes parameters in as the first parameter to your function. We'll find our parameter at params.number_of_questions:
javascript
Copied
1
// Linked to https://app.airplane.dev/t/get_trivia_question [do not edit this line]
2
3
import fetch from "node-fetch";
4
import airplane from "airplane";
5
6
export default async function (params) {
7
// 🌟 params is an object keyed by parameter slugs
8
const count = params.number_of_questions;
9
// 🌟 Interpolate count into the URL:
10
const res = await fetch(`http://jservice.io/api/random?count=${count}`);
11
const questions = await res.json();
12
13
for (const q of questions) {
14
airplane.appendOutput({
15
id: q.id,
16
question: q.question,
17
answer: q.answer,
18
});
19
}
20
}
Redeploy: airplane deploy ./get_trivia_question.js.
You'll now be able to enter Number of Questions:
And you'll see that the output table now only has 3 rows:

Config variables

Config Variables provide a way to store configuration and secrets securely on Airplane. Config variables can be set via the UI and then read in as environment variables on the task.
In a more realistic example, you would likely store your `database_url` as a config variable and access it from your code to connect to your DB.
First, click the Config variables page from the sidebar:
Click New config variable and in this example, we'll store the API URL as a config variable pointing to http://jservice.io/api/random:
Return to your task and click Edit task. Under the Build section, add an environment variable called TRIVIA_API_URL and set it to the config variable you just added:
Don't forget to click Update task when you're done.
Now, let's read that environment variable in our code, via process.env.TRIVIA_API_URL:
javascript
Copied
1
// Linked to https://app.airplane.dev/t/get_trivia_question [do not edit this line]
2
3
import fetch from "node-fetch";
4
import airplane from "airplane";
5
6
export default async function (params) {
7
const count = params.number_of_questions;
8
// 🌟 we can now read from process.env.TRIVIA_API_URL
9
const res = await fetch(`${process.env.TRIVIA_API_URL}?count=${count}`);
10
const questions = await res.json();
11
12
for (const q of questions) {
13
airplane.appendOutput({
14
id: q.id,
15
question: q.question,
16
answer: q.answer,
17
});
18
}
19
}

Wrapping Up

That's it for now! In this quickstart, you were able to take a custom script, deploy it to Airplane, and configure both its parameters and outputs.