JavaScript

Airplane makes it easy to write and deploy JavaScript and TypeScript-based tasks when you need to write custom code that SQL or REST might not be able to handle.

This guide will get you up and running with an example JavaScript task. For specific details see:

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

Once you've installed and logged in to the CLI, navigate to the folder where you want to create your task and run init:

bash
Copied
1
airplane tasks init

You'll be prompted for some information:

Enter a name for the task.
Select JavaScript as the kind.
Enter a name for the task file. The file can have any name, but it must end in .airplane.ts or .airplane.js.

The init command will create your task file in a new Project along with a few other files:

package.json: Contains any external dependencies that your task will use.
airplane.yaml: A Project configuration file that allows you to set project-wide configuration such as the Node.js version your task will be executed with.
tsconfig.json: Configures TypeScript settings if your task uses TypeScript.

Develop your script

The default Airplane JavaScript task looks like this:

typescript
Copied
1
import airplane from "airplane";
2

3
export default airplane.task(
4
  {
5
    slug: "delete_user",
6
    name: "Delete user",
7
  },
8
  // This is your task's entrypoint. When your task is executed, this
9
  // function will be called.
10
  async () => {
11
    const data = [
12
      { id: 1, name: "Gabriel Davis", role: "Dentist" },
13
      { id: 2, name: "Carolyn Garcia", role: "Sales" },
14
      { id: 3, name: "Frances Hernandez", role: "Astronaut" },
15
      { id: 4, name: "Melissa Rodriguez", role: "Engineer" },
16
      { id: 5, name: "Jacob Hall", role: "Engineer" },
17
      { id: 6, name: "Andrea Lopez", role: "Astronaut" },
18
    ];
19

20
    // Sort the data in ascending order by name.
21
    data.sort((u1, u2) => {
22
      return u1.name.localeCompare(u2.name);
23
    });
24

25
    // You can return data to show output to users.
26
    // Output documentation: https://docs.airplane.dev/tasks/output
27
    return data;
28
  },
29
);

When Airplane executes your script, it will look for an exported call to airplane.task(). The second parameter to airplane.task() (after the configuration) is the function that will be executed when the task is run. This function may accept a single argument (params) which will be set to an object of the parameter values passed in by the user. For example: { "user_email": "hello@airplane.dev" }.

Although this task is simple, Airplane tasks can Execute other tasks, call Airplane built-ins to perform common operations like query a database or send an email, display interactive Prompts to gather input from operators, and much more!

Develop locally

To test your task locally in Studio, run:

bash
Copied
1
$ airplane dev

For more details on local task execution, including how to set environment variables and resources, see Studio.

Add Parameters

Parameters allow you to prompt users for input before triggering your task.

In the following example, we add a single parameter user_email to our task. The user_email must be provided when the task is executed:

Example:

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

4
export default airplane.task(
5
  {
6
    slug: "delete_user",
7
    name: "Delete user",
8
    parameters: {
9
      user_email: {
10
        name: "User email",
11
        type: "shorttext",
12
        description: "The email address of the user"
13
      },
14
    },
15
  },
16
  async (params) => {
17
  // Rest of code

For more information on configuration parameters, see JavaScript parameter configuration.

Add environment variables

Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.

In the following example, we add two environment variables to our task. The first is set directly from a value, and the second is set from a config variable:

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

4
export default airplane.task(
5
  {
6
    slug: "delete_user",
7
    name: "Delete user",
8
    parameters: {
9
      user_email: {
10
        name: "User email",
11
        type: "shorttext",
12
        description: "The email address of the user"
13
      },
14
    },
15
    envVars: {
16
      NODE_ENV: { value: "production" }, // From value
17
      MY_SECRET: { config: "MY_SECRET_CONFIG_VAR" }, // From config variable
18
    },
19
  },
20
  async (params) => {
21
  // Rest of code

Access environment variables in your script using standard JavaScript patterns. For example:

typescript
Copied
1
const mySecret = process.env.MY_SECRET;

For more information on configuration environment variables, see JavaScript task configuration.

Install dependencies

To install dependencies, you can add them to your project's package.json via npm or yarn like you normally would:

bash
Copied
1
npm install uuid

Airplane skips installation of devDependencies—if your application requires devDependencies, you can override the install command. See Custom build steps.

Deploy to Airplane

Finally, run deploy to push your task to Airplane:

bash
Copied
1
airplane deploy

Once deployed, go to the Tasks page to run and share your task!