Speeding up the Nixpacks Build

You can optimize your Nixpacks builds by limiting the amount of times the package installation phase runs.

For instance, if you are working with Node, the install phase can be cached if your package lock file hasn't changed.

You should see a significant speedup in your builds if you are working with a large number of packages, or if you are working with a monorepo.

Understanding Build Caching and Optimization

Build optimization requires an additional file - nixpacks.toml to be added to your Git repo to let Nixpacks know which files are required for the installation phase. If these files are the same between builds, Nixpacks detects that this step does not need to be re-run, and skips it.

If you do add or change a package, Nixpacks will detect this change and run the install phase before the build phase.

This can help to bring down build times and bandwidth usage for your build runtimes. This comes in particularly useful if you are working with private or gated artifact repositories, such as FontAwesome.

You can find more information about this feature in the Nixpacks documentation (opens in a new tab).

Add onlyIncludeFiles to nixpacks.toml

All of these examples would typically be placed in a nixpacks.toml file in the root of your Git repository. If you already have a nixpacks.toml file with the install phase, you can add the onlyIncludeFiles configuration to the existing file.

If you would like to use a different name or location for the configuration file, you can specify this using the NIXPACKS_CONFIG_FILE environment variable.

NPM

[phases.install]
onlyIncludeFiles = [
  ".npmrc",
  "package.json",
  "package-lock.json",
  "./patches/",
]

PNPM

[phases.install]
onlyIncludeFiles = [
  ".npmrc",
  "package.json",
  "pnpm-lock.yaml",
  "./patches/",
]

Important Note: Include All Needed Files

When you use this feature to optimize the installation step, you do need to be sure to include all of the files needed. Nixpacks only copies the files you specify during the install step, so if you forget to include a file, you may get an error about a missing file.

This includes the package.json files for monorepos, and any files needed in pre or post install steps.

We suggest running Nixpacks locally to ensure that you have all of the files needed for the install step first, as this will help you to avoid any errors.

Working with Monorepos

Monorepos are a special case when optimizing the install step. If you are working with a PNPM-based Node monorepo, you will need to include the package.json files for each package subdirectory in the monorepo.

For instance, let's say that you were using PNPM (opens in a new tab), and you had a monorepo with the following structure:

packages/
  api/
    package.json
  frontend/
    package.json
  shared/
    package.json

You would need to include the package.json files for each of the subdirectories in the packages directory. Here's an example of what that might look like:

[phases.install]
onlyIncludeFiles = [
  ".npmrc",
  "package.json",
  "pnpm-lock.yaml",
  "pnpm-workspace.yaml",
  "./patches/",
  "./packages/api/package.json",
  "./packages/frontend/package.json",
  "./packages/shared/package.json",
]

You would need to adjust this example for your own package structure.