Node.js
Write custom tasks in JavaScript or TypeScript
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).

Getting Started

To create a Node.js task, visit the New Task page.

Define Your Task

In this first step, you'll be asked to give your task a name and an (optional) description.

Parameters

Here, you can define parameters for your task - these parameters will later be passed to your code. (See the Parameters documentation for a full reference on what parameters are available.)

Build Your Task

You'll only define environment variables in this next section. For custom code tasks, the code is deployed separately after the task is created.

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.

Configure Settings

In this last step, you can optionally configure permissions, timeouts, run constraints, and more. These settings are optional.
That's it! Finish the task creation wizard and you have a shrinkwrapped task for safely running Node.js scripts.

Deploy Your Code

Airplane runs your code using Node 16 by default. You can change the node version in the "Configure" section of the task wizard.
Once created, the UI will show you instructions on how to init and deploy the task. Your task has a slug, which is a human-readable ID, which you'll need for running the init and deploy commands.
In your own code repository, run airplane init to create a blank task file:
1
$ airplane init --slug YOUR_TASK_SLUG ./yourTaskFile.js
Copied!
A minimal Airplane task in Node.js looks like this (and gets generated by airplane init):
yourTaskFile.js
1
// Linked to https://app.airplane.dev/t/your_task_slug [do not edit this line]
2
3
export default async function(params) {
4
console.log('parameters:', params);
5
}
Copied!
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: { "email": "[email protected]", "dry_run": false }.
Your scripts 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 compiling 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:
NPM
Yarn
1
# Example installing the airplane SDK
2
# Updates package-lock.json
3
npm install airplane
Copied!
1
# Example installing the airplane SDK
2
# Updates yarn.lock
3
yarn add airplane
Copied!
To use your organization's private NPM packages, see Private NPM Packages below.

Develop Locally

To test your task locally, ensure you have the Airplane CLI installed, then run:
1
$ airplane dev ./main.js -- --name="[email protected]"
Copied!
For more details on local task execution, including how to set environment variables, see these docs.

Deploy to Airplane

Finally, run deploy to push your script to Airplane:
1
airplane deploy ./yourTaskFile.js
Copied!
Once deployed, go to the Tasks page to run and share your task!

SDK

The Airplane JavaScript SDK is available as an NPM package, airplane. To install it, run:
npm
yarn
1
$ npm install airplane
Copied!
1
yarn add airplane
Copied!

Outputs

This SDK can be used to produce Outputs that will be rendered in the UI when someone runs your task. To learn more, see the Outputs documentation:
1
import airplane from 'airplane'
2
3
// ...
4
5
airplane.output("I like ~trains~ airplanes.")
6
7
// A key can be added to group together multiple outputs:
8
airplane.output("rows", { email: "[email protected]" })
9
airplane.output("rows", { email: "[email protected]" })
10
11
// Multiple keys can be used to separate outputs:
12
airplane.output("error", "Uh-oh, something went wrong!")
Copied!

Private NPM Packages

To install private packages from NPM, you'll need to generate an access token with read-only permissions. Add it as a Config Var and set it as an environment variable called BUILD_NPM_TOKEN:
Environment variables are set at build time in addition to runtime - when building, Airplane will look for BUILD_NPM_TOKEN and configure a .npmrc file for you.

Other Private Packages

If you're using other private registries like GitHub packages, you can upload the entire contents of your .npmrc file (assuming the tokens are stored there) and set the BUILD_NPM_RC environment variable:
.npmrc
1
//registry.npmjs.org/:_authToken=TOKEN_FOR_NPM
2
//npm.pkg.github.com/:_authToken=TOKEN_FOR_GITHUB
Copied!
1
cat .npmrc | airplane configs set --secret npm_rc
Copied!

NPM / Yarn Workspaces

By default, the airplane CLI will find the nearest package.json and use that as the root of your task. All code in the root is included when building the task.
If you're using NPM or Yarn workspaces, you may want the root to be the parent directory, so that you can install sibling packages. For example, you might be deploying packageA/scripts/myScript.ts:
1
/
2
package.json
3
packageA/
4
package.json
5
scripts/
6
myScript.ts
7
packageB/
8
package.json
Copied!
While packageA/package.json will be identified as the root package.json for your task, you'll also want to include the parent folder (and siblings like packageB/) in the build.
To do this, in packageA/package.json you can override the root to be a parent directory:
packageA/package.json
1
{
2
"airplane": {
3
"root": ".."
4
}
5
}
Copied!
This will cause the root to get moved up a level, thus including packageA/ as well as packageB/ in the build. Note that the working directory will remain at packageA/ - any build/install commands will still be run from the subdirectory.
Last modified 1mo ago