Node.js

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 Node.js task. For specific details see:

Getting started

We'll use the Airplane CLI airplane to demonstrate how to get started with a Node.js task.
If you haven't yet, first install the Airplane CLI by following the instructions at Installing 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:
bash
Copied
1
airplane init
You'll be prompted for some information:
  • Enter a name for the task.
  • Select Node as the kind.
  • Enter a name for the script and the definition file. The script contains the task code (e.g. delete_user_by_email.js) while the definition file contains task metadata (e.g. delete_user_by_email.task.yaml).
To use TypeScript, use a .ts extension instead of .js for the script.

Parameters

Parameters allow you to prompt users for input before triggering your task. See Parameters for more information about Airplane parameters.
Open up the definition file (the file with extension .task.yaml) to add parameters to the task.
Example:
yaml
Copied
1
parameters:
2
- name: User email
3
slug: user_email
4
type: shorttext
5
description: The email address of the user

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.
yaml
Copied
1
node:
2
envVars:
3
# From value
4
NODE_ENV:
5
value: production
6
# From config variable
7
MY_SECRET:
8
config: MY_SECRET_CONFIG_VAR
Access environment variables in your script using standard node patterns. For example:
javascript
Copied
1
const mySecret = process.env.MY_SECRET;

Develop your script

A minimal Node.js script looks like this (generated by airplane init):
javascript
Copied
1
// Put the main logic of the task in this function.
2
export default async function (params) {
3
console.log("parameters:", params);
4
// You can return data to show output to users.
5
// Output documentation: https://docs.airplane.dev/tasks/output
6
return [
7
{ element: "hydrogen", weight: 1.008 },
8
{ element: "helium", weight: 4.0026 },
9
];
10
}
When Airplane executes your script, it will look for a default export. This export should be a function with 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" }.
Your script will be run the latest version of Node 16, which includes the latest JS language features from ES2022. Airplane also polyfills support for ECMAScript-style modules (import/export) and will transparently handle transpiling any TypeScript files used by your script (just make sure they end with .ts!).

Install dependencies

To install dependencies, you can add them to your script's package.json via npm or yarn like you normally would:
bash
Copied
1
# Example installing the airplane SDK
2
# Updates package-lock.json
3
npm install airplane
Airplane skips installation of devDependencies—if your application requires devDependencies, you can override the install command. See Custom build steps.
To use your organization's private NPM packages, see Private NPM Packages.

Develop locally

To test your task locally, ensure you have the Airplane CLI installed, then run:
bash
Copied
1
$ airplane dev your_task.task.yaml -- --user_email="hello@airplane.dev"
2
parameters: {'user_email': 'hello@airplane.dev'}
For more details on local task execution, including how to set environment variables, see Local task execution.

Deploy to Airplane

Finally, run deploy to push your task to Airplane:
bash
Copied
1
airplane deploy your_task.task.yaml
Once deployed, go to the Tasks page to run and share your task!