Working with Monorepos

Flightcontrol supports the use of monorepos to deploy one or more Flightcontrol services. A monorepo is a shared source code repository for many projects, which can be useful for keeping all of the projects in sync.

Monorepos are a complicated subject - and many software development organizations have different strategies for organizing their source code. Often times, you might be using custom tooling or a specialized build tool to help manage the monorepo.

We give general guidance here on how to deploy your code out of a monorepo. We’re also happy to help you out if you have a question that isn’t covered in this guide.

Configuration File

You can place the flightcontrol.json configuration file at the root of your Git repository and use one file to configure each Flightcontrol service in the monorepo.

Using buildType: nixpacks

Packages managed with monorepo tooling

For a JS monorepo using npm, yarn, pnpm or a monorepo that requires running command from the root, you’ll need to point basePath to the repo root. Then manually specify the install/build command and account for the right path depending on the command needed, like so:

{
  "environments": [
    {
      ...
      "services": [
        {
          "id": "api",
          "buildType": "nixpacks",
          "ci": {
            "type": "ec2"
          },
          "basePath": ".",
          "startCommand": "cd packages/api && npm run start",
          "buildCommand": "cd packages/api && npm run build"
          ...
 
        },
        ...
      ]
    }
  ]
}

If you have a nx package-based monorepo, then you’ll need to specify the nx command, including the package name, but basePath should be empty or set to . (it’s . by default):

{
  "environments": [
    {
      ...
      "services": [
        {
          "id": "api",
          "basePath": ".",
          "buildType": "nixpacks",
          "ci": {
            "type": "ec2"
          },
          "buildCommand": "nx build blog",
          "startCommand": "nx serve blog --verbose",
          ...
        },
        ...
      ]
    }
  ]
}

Independent packages in a repo

You should indicate a basePath alongside the [install|build|start] commands for each service, like illustrated in the contrived config example below.

{
  "environments": [
    {
      "id": "development",
      "name": "Development",
      "region": "us-east-2",
      "source": {
        "branch": "main"
      },
      "services": [
        {
          "id": "api",
          "name": "Rails API",
          "type": "web",
          "target": {
            "type": "fargate"
          },
          "buildType": "nixpacks",
          "ci": {
            "type": "ec2"
          },
          "basePath": "./packages/api",
          "buildCommand": "bundle exec rake assets:precompile",
          "startCommand": "rails start"
        },
        {
          "id": "frontend",
          "name": "Frontend Web",
          "type": "static",
          "buildType": "nixpacks",
          "ci": {
            "type": "ec2"
          },
          "singlePageApp": true,
          "basePath": "./packages/frontend",
          "buildCommand": "npm build",
          "outputDirectory": "packages/frontend/dist"
        }
      ]
    }
  ]
}

Further customization

If there are specific needs for building/installing your service, such as custom phases or specific OS packages, then you can use a nixpacks.toml file. The .toml file is specific to each package and should be placed in the package’s folder.

If you’re using basePath in your flightcontrol configuration, you don’t need to do anything else and the file will be picked up.

If you’re not using basePath, you’ll need to set a NIXPACKS_CONFIG_FILE environment variable with the service’s nixpacks.toml file path, like the following:

{
  id: "production",
  name: "production",
  services: [
    {
      id: "frontend",
      buildType: "nixpacks",
      envVariables: {
        "NIXPACKS_CONFIG_FILE": "./apps/frontend/nixpacks.toml"
      }
      ...
    },
    {
      id: "api",
      buildType: "nixpacks",
      envVariables: {
        "NIXPACKS_CONFIG_FILE": "./packages/api/nixpacks.toml"
      }
      ...
    },
  ],
}

Watch Paths

Most monorepo users will want to use Watch Paths so that only services with changes are deployed instead of everything.