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
:Copied1┣ support-tools/ ⭐ PROJECT ROOT2┃ ┣ helpers/3┃ ┃ ┗ utils.ts4┃ ┣ my_task.airplane.ts5┃ ┣ airplane.yaml6┃ ┗ package.json7┗ 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:Copied1support-tools/ ⭐ PROJECT ROOT2┣ helpers/3┃ ┗ utils.ts4┣ my_task.airplane.ts5┣ airplane.yaml6┣ package.json7┗ 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.Copied1┣ sales/ ⭐ PROJECT ROOT2┃ ┣ useful-tools/3┃ ┃ ┗ salesTask.airplane.ts4┃ ┣ airplane.yaml5┃ ┗ package.json6┗ support-tools/ ⭐ PROJECT ROOT7┣ my_task.airplane.ts8┣ airplane.yaml9┗ package.json
The root of the project is determined by the nearest
requirements.txt
.If your task does not have a
requirements.txt
, 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.Copied1┣ sales/ ⭐ PROJECT ROOT2┃ ┣ useful-tools/3┃ ┃ ┗ salesTask_airplane.py4┃ ┣ airplane.yaml5┃ ┗ requirements.txt6┗ support-tools/ ⭐ PROJECT ROOT7┣ my_task_airplane.py8┣ airplane.yaml9┗ requirements.txt
The root of the project is determined by the nearest
custom
Dockerfile
.If your task does not have a custom
Dockerfile
, 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.Copied1┣ sales/ ⭐ PROJECT ROOT2┃ ┣ useful-tools/3┃ ┃ ┣ salesTask.sh4┃ ┃ ┗ salesTask.task.yaml5┃ ┣ airplane.yaml6┃ ┗ Dockerfile7┗ support-tools/ ⭐ PROJECT ROOT8┣ myTask.sh9┣ airplane.yaml10┗ myTask.task.yaml
For all other cases, 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.Copied1┣ sales/2┃ ┗ useful-tools/ ⭐ PROJECT ROOT3┃ ┃ ┣ salesTask.sql4┃ ┃ ┗ salesTask.task.yaml5┗ support-tools/ ⭐ PROJECT ROOT6┗ myTask.task.yaml
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.Use the
airplane.yaml
file to configure common build and runtime options for all of the tasks and
views in the project.See Project configuration 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.
Copied1airplane/ ⭐ PROJECT ROOT2┣ sales/3┃ ┣ my_task.airplane.ts4┃ ┣ my_task_airplane.py5┃ ┣ my_view.airplane.tsx6┃ ┗ rest_task.task.yaml7┣ support/8┃ ┣ my_sales_task.airplane.ts9┃ ┣ sales_query.sql10┃ ┗ sql_task.task.yaml11┣ airplane.yaml12┣ package.json13┗ 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.
Copied1airplane2┣ sales/ ⭐ PROJECT ROOT3┃ ┣ airplane.yaml4┃ ┣ my_task.airplane.ts5┃ ┣ my_task_airplane.py6┃ ┣ my_view.airplane.tsx7┃ ┣ package.json8┃ ┣ requirements.txt9┃ ┗ rest_task.task.yaml10┗ support/ ⭐ PROJECT ROOT11┣ airplane.yaml12┣ my_sales_task.airplane.ts13┣ package.json14┣ sales_query.sql15┗ 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.
Copied1root/ ⭐ PROJECT ROOT2┣ folder/3┃ ┣ my_main_code.ts4┃ ┗ my_task.airplane.ts5┣ airplane.yaml6┗ 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:
Copied1airplane/ ⭐ PROJECT ROOT2┣ packages/3┃ ┣ sales/4┃ ┃ ┣ my_sales_task.airplane.ts5┃ ┃ ┗ package.json6┃ ┗ support/7┃ ┃ ┣ my_support_task.airplane.ts8┃ ┃ ┗ package.json9┣ airplane.yaml10┗ package.json
Each of
airplane/packages/sales/package.json
and airplane/packages/support/package.json
must
have the following:jsonCopied1{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.