Cover image by DALL-E.
defaultProject setting for the Nx CLI was originally inherited from the Angular CLI. In integrated and standalone Nx workspaces, the
defaultProject setting is located in
nx.json. In package-based Nx workspaces,
defaultProject is located in
package.json#nx. While it was removed from Angular CLI version 16, it is still present but unofficially deprecated in Nx version 16.x as evident by the
nx.json reference which doesn't list it.
As of Nx 16.2, a
defaultProject setting is still configured when using
create-nx-workspace to generate a standalone Nx workspace. However, it is safe to remove this setting as Nx detects the
project.json file in the root directory of a standalone workspace.
In this article, we discuss why the
defaultProject is being deprecated, which use cases it affects with example commands not depending on it, and finally the viable replacement for
defaultProject setting is being depreacted and eventually removed because it doesn't make sense in integrated and package-based Nx workspaces where the preferred project usually varies between teams and developers and so shouldn't be committed to a configuration shared between most or all teams and developers.
Standalone Nx workspaces can have more than one project but the original project is defined in a
project.json file in the root workspace directory which Nx detects to infer the project for Nx CLI commands run from this directory.
Let's explore most of the use cases affected by the
defaultProject setting and how we can complete them without this setting.
An Nx workspace defines projects, targets, and, optionally, configurations.
To run a task for a specific configuration of a project target, we use the following command format.
nx run <project>:<target>[:<configuration>]
nx run <project>:<target> [--configuration=<configuration>]
For example, to start a task running the
build target on the
my-app project, we use the following command.
nx run my-app:build
Common target names have alias commands, for example the following command is an alias of the previous
nx run command.
nx build my-app
To make sure we use the
production build configuration, we prepend
:production to our
nx run command as seen in the following.
nx run my-app:build:configuration
The aliased version is as follows.
nx build my-app --configuration=production
Some Nx generators and Angular schematics require a
--project option but use the
defaultProject setting when omitted, for example
deafultProject setting, we must pass a
--project option as seen in the following example.
nx generate @nx/angular:component button --standalone --project=my-app
Although the preferred project isn't the same for all teams or developers, it is still convenient to leave out the same project name for most task runs and generators.
As a viable replacement for the
defaultProject setting, we can use the
NX_DEFAULT_PROJECT environment variable which is planned to outlive the
defaultProject setting as we have many options for setting this in individual environments, both for CI and local development use cases.
When we set the value of the
NX_DEFAULT_PROJECT environment variable to a project name, both task running and code generation works as if we had specified the
defaultProject setting but without committing it to a shared configuration.
For example, with the
NX_DEFAULT_PROJECT environment variable set to
my-app, we can use the following build commands.
# build the app nx run build # or nx build # build the app in production mode nx run build: production # or nx build --configuration=production
Additionally, we can use generators and schematics that require a
--project option witout specifying a project.
nx generate @nx/angular:component button --standalone # or nx generate @schematics/angular:component button --standalone
In this article, we learned that
defaultProject is being deprecated and removed because it is no longer necessary for standalone Nx workspaces and in the case of integrated or package-based Nx workspaces, different teams and developers often want a different default project. Because of this, we shouldn't commit a shared setting.
We learned how the
defaultProject setting affects the
nx run command as well as Nx generators and Angular schematics that require a
Finally, we learned how we can use the
NX_DEFAULT_PROJECT environment variable to configure an individual environment for CI tasks or local development in the same way as we would have used the
defaultProject setting in the past but without committing a setting to a shared configuration.