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:
- JavaScript Task configuration
- Installing dependencies
- Using the Airplane SDK
- Customizing the build process
Before you begin
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
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
:bashCopied1airplane 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
Develop your script
The default Airplane JavaScript task looks like this:
typescriptCopied1import airplane from "airplane";23export default airplane.task(4{5slug: "delete_user",6name: "Delete user",7},8// This is your task's entrypoint. When your task is executed, this9// function will be called.10async () => {11const 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];1920// Sort the data in ascending order by name.21data.sort((u1, u2) => {22return u1.name.localeCompare(u2.name);23});2425// You can return data to show output to users.26// Output documentation: https://docs.airplane.dev/tasks/output27return 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
Develop locally
To test your task locally in Studio, run:
bashCopied1$ airplane dev
For more details on local task execution, including how to set environment variables and resources,
see Studio.
Add Parameters
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:
typescriptCopied1// country_lookup.airplane.ts2import airplane from "airplane";34export default airplane.task(5{6slug: "delete_user",7name: "Delete user",8parameters: {9user_email: {10name: "User email",11type: "shorttext",12description: "The email address of the user"13},14},15},16async (params) => {17// Rest of code
For more information on configuration parameters, see
JavaScript parameter configuration.
Add environment variables
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:
typescriptCopied1// country_lookup.airplane.ts2import airplane from "airplane";34export default airplane.task(5{6slug: "delete_user",7name: "Delete user",8parameters: {9user_email: {10name: "User email",11type: "shorttext",12description: "The email address of the user"13},14},15envVars: {16NODE_ENV: { value: "production" }, // From value17MY_SECRET: { config: "MY_SECRET_CONFIG_VAR" }, // From config variable18},19},20async (params) => {21// Rest of code
Access environment variables in your script using standard JavaScript patterns. For example:
typescriptCopied1const mySecret = process.env.MY_SECRET;
For more information on configuration environment variables, see
JavaScript task configuration.
Install dependencies
Install dependencies
To install dependencies, you can add them to your project's
package.json
via npm
or yarn
like
you normally would:bashCopied1npm install uuid
bashCopied1yarn add uuid
Airplane skips installation of
devDependencies
—if your application requires devDependencies
, you
can override the install command. See Custom build steps.Deploy to Airplane
Deploy to Airplane
Finally, run deploy to push your task to Airplane:
bashCopied1airplane deploy
Once deployed, go to the Tasks page to run and share your task!