Organizing your Airplane code

Although Airplane provides flexibility in how your team organizes tasks and views, this document outlines some core concepts and best practices to keep in mind for code organization.

Projects

Code deployed on Airplane is organized into projects. Projects group together files that are uploaded together in a deployment—code in a project can only depend on files inside of its project. In other words, code outside of a project cannot be accessed by code within the project.

For example, in the following layout, the task my_task.airplane.ts can import helpers/utils.ts, but cannot access customers.json:


Copied
1
┣ support-tools/ ⭐ PROJECT ROOT
2
┃ ┣ helpers/
3
┃ ┃ ┗ utils.ts
4
┃ ┣ my_task.airplane.ts
5
┃ ┣ airplane.yaml
6
┃ ┗ package.json
7
┗ customers.json 🚫 OUTSIDE PROJECT

To include a file in a project, you can either move the file into the project or update your structure so that the project root includes the file.

To import customers.json from my_task.airplane.ts, we'll have to include it in the project:


Copied
1
support-tools/ ⭐ PROJECT ROOT
2
┣ helpers/
3
┃ ┗ utils.ts
4
┣ my_task.airplane.ts
5
┣ airplane.yaml
6
┣ package.json
7
┗ customers.json ✅ INSIDE PROJECT

Determing which project a task or view is in

The root directory of a project depends on the type of the task or view.

The root of the project is determined by the nearest package.json.

If you're using npm or Yarn workspaces, the root is instead based on the workspace's root package.json.

If your task does not have a package.json, the root of the project is determined by the nearest airplane.yaml configuration file.

If your project does not have an airplane.yaml configuration file, the root of the project is the directory that contains the task.


Copied
1
┣ sales/ ⭐ PROJECT ROOT
2
┃ ┣ useful-tools/
3
┃ ┃ ┗ salesTask.airplane.ts
4
┃ ┣ airplane.yaml
5
┃ ┗ package.json
6
┗ support-tools/ ⭐ PROJECT ROOT
7
  ┣ my_task.airplane.ts
8
  ┣ airplane.yaml
9
  ┗ package.json

Project configuration

A project can be optionally configured with an airplane.yaml configuration file. If included, the airplane.yaml file must be located in the root directory of the project.


Copied
1
support-tools/ ⭐ PROJECT ROOT
2
┣ helpers/
3
┃ ┗ utils.ts
4
┣ customers.json
5
┣ my_task.airplane.ts
6
┣ package.json
7
┗ airplane.yaml ✅ INSIDE PROJECT


Copied
1
repo/
2
┣ support-tools/ ⭐ PROJECT ROOT
3
┃ ┣ helpers/
4
┃ ┃ ┗ utils.ts
5
┃ ┣ my_task.airplane.ts
6
┃ ┗ package.json
7
┗ airplane.yaml 🚫 OUTSIDE PROJECT

Use this file to configure common build and runtime options for all of the tasks and views in the project. See the airplane.yaml reference for more information.

Code organization patterns

Organizing Airplane projects is no different than organizing any other codebase. We recommend using the simplest approach that suits your organization.

Single project (recommended)

Most Airplane teams should start with a single project in a single git repository. Using a single project ensures that tasks and views have access to all of the code in the project. It also simplifies dependency management for JavaScript and Python tasks, limiting your codebase to a single list of dependencies.

You can even include tasks of different types in the same project, so this pattern works even if your team uses a mix of JavaScript, Python, and SQL.


Copied
1
airplane/ ⭐ PROJECT ROOT
2
┣ sales/
3
┃ ┣ my_task.airplane.ts
4
┃ ┣ my_task_airplane.py
5
┃ ┣ my_view.airplane.tsx
6
┃ ┗ rest_task.task.yaml
7
┣ support/
8
┃ ┣ my_sales_task.airplane.ts
9
┃ ┣ sales_query.sql
10
┃ ┗ sql_task.task.yaml
11
┣ airplane.yaml
12
┣ package.json
13
┗ requirements.txt

Multiple projects

While most teams will find a single project sufficient, there are a few good reasons to split your Airplane code into multiple projects:

You have expensive dependencies. All tasks of a given type in a project share the same dependencies. This means that if a task has a dependency that takes a long time to install, all tasks in the project have to wait for that dependency to install on every deployment. You may want to split tasks that rely on this dependency into another project so that your other tasks and views can deploy quicker.
You have a large organization with distinct subteams. If you have different subteams working in distinct parts of the code, it might make sense to create an Airplane project for each of these teams. This ensures that code is isolated by team and that dependencies are managed per team.
Your code lives in different repositories. An Airplane project does not usually encompass multiple code repositories. If you write Airplane tasks & views in different repositories, they will exist in different projects.


Copied
1
airplane
2
┣ sales/ ⭐ PROJECT ROOT
3
┃ ┣ airplane.yaml
4
┃ ┣ my_task.airplane.ts
5
┃ ┣ my_task_airplane.py
6
┃ ┣ my_view.airplane.tsx
7
┃ ┣ package.json
8
┃ ┣ requirements.txt
9
┃ ┗ rest_task.task.yaml
10
┗ support/ ⭐ PROJECT ROOT
11
  ┣ airplane.yaml
12
  ┣ my_sales_task.airplane.ts
13
  ┣ package.json
14
  ┣ sales_query.sql
15
  ┗ sql_task.task.yaml

Intermixing Airplane tasks with your main codebase

While some Airplane users separate their Airplane projects from the rest of their company's main code (using either a separate folder or a separate repository), others integrate Airplane tasks and views throughout their main codebase. This is especially helpful if your code is already written in JavaScript or Python and you want to call your main code from your Airplane tasks.

If you do want to include Airplane code in your main codebase, keep in mind that in order for Airplane code to import your main code, you must include all of your main code in your Airplane project. This means that each time you deploy to Airplane, you will be uploading, installing and building your main codebase. This may slow down deployments depending on the size and complexity of your main codebase.


Copied
1
root/ ⭐ PROJECT ROOT
2
┣ folder/
3
┃ ┣ my_main_code.ts
4
┃ ┗ my_task.airplane.ts
5
┣ airplane.yaml
6
┗ package.json

Yarn / npm workspaces (JavaScript only)

Yarn workspaces or npm workspaces are features built for managing multiple JavaScript packages from within a singlular top-level, root package.

If your team is already using workspaces or is interested in organizing their Airplane code into workspaces, you can use this framework to organize your Airplane tasks.

To use yarn/npm workspaces, you must include a root field in the package.json of each workspace project that tells Airplane how to find the root of your workspace.

For example, if your project looks like the following:


Copied
1
airplane/ ⭐ PROJECT ROOT
2
┣ packages/
3
┃ ┣ sales/
4
┃ ┃ ┣ my_sales_task.airplane.ts
5
┃ ┃ ┗ package.json
6
┃ ┗ support/
7
┃ ┃ ┣ my_support_task.airplane.ts
8
┃ ┃ ┗ package.json
9
┣ airplane.yaml
10
┗ package.json

Each of airplane/packages/sales/package.json and airplane/packages/support/package.json must have the following:

json
Copied
1
{
2
  "airplane": {
3
    "root": "../.."
4
  }
5
}

With this setup, your code will be organized into a single Airplane project and you can manage your dependencies with standard workspace patterns.