Pass Args to Commands

When you have an inferred task (or an explicitly defined task using the nx:run-commands executor) running a command, there'll come a time when you'll need to pass args to the underlying command being run. This recipe explains how you can achieve that.

Example project and tasks

For this recipe we'll use a project with the following project.json file:

apps/my-app/project.json
1{ 2 "sourceRoot": "apps/my-app/src", 3 "projectType": "application", 4 "targets": {} 5} 6

And the following final configuration:

Project Details View

my-app

Vite

Root: apps/my-app

Type:application

Targets

  • build

    Vite

    vite build

    Cacheable
  • preview

    Vite

    vite preview

  • serve

    Vite

    vite serve

  • test

    Vite

    vitest run

    Cacheable

We'll focus on the build target of the project. If you expand the build target in the Project Details View above, you'll see that it runs the command vite build. In the next sections, we'll see how to provide --assetsInlineLimit=2048 and --assetsDir=static/assets args to that command.

Pass args in the project.json task configuration

To statically pass some extra args to a specific project, you can update its project.json file. You can do it by either providing the args as individual options or by providing the args option:

Providing command args as options

Support for providing command args as options was added in Nx v18.1.1.

apps/my-app/project.json
1{ 2 "sourceRoot": "apps/my-app/src", 3 "projectType": "application", 4 "targets": { 5 "build": { 6 "options": { 7 "assetsInlineLimit": 2048, 8 "assetsDir": "static/assets" 9 } 10 } 11 } 12} 13
Precedence

Args specified in the args option take precedence and will override any arg specified as an option with the same name. So, defining both "args": ["--assetsDir=static/assets"] and "assetsDir": "different/path/to/assets" will result in Nx running the command with --assetsDir=static/assets.

Pass args in the targetDefaults for the task

To provide the same args for all projects in the workspace, you need to update the task configuration in the nx.json file. Similar to the previous section, you can do it by either providing the args as individual options or by providing the args option:

nx.json
1{ 2 "targetDefaults": { 3 "build": { 4 "options": { 5 "assetsInlineLimit": 2048, 6 "assetsDir": "static/assets" 7 } 8 } 9 } 10} 11
Be careful

If multiple targets with the same name run different commands (or use different executors), do not set options in targetDefaults. Different commands would accept different options, and the target defaults will apply to all targets with the same name regardless of the command they run. If you were to provide options in targetDefaults for them, the commands that don't expect those options could throw an error.

Pass args when running the command in the terminal

To pass args in a one-off manner when running a task, you can also provide them as individual options or by providing the --args option when running the task:

nx build my-app --assetsInlineLimit=2048 --assetsDir=static/assets

Conflicting options

If you provide an arg with the same name as an Nx CLI option (e.g. --configuration) or an nx:run-commands option (e.g. --env), the arg will be parsed as an option for the Nx CLI or the executor and won't be forwarded to the underlying command. You should provide the arg using the -args option in such cases.

You can also provide an arg with the same name to both the Nx CLI and the underlying command. For example, to run the ci configuration of a test target that runs the command detox test and pass the --configuration arg to the command, you can run:

nx test mobile-e2e --configuration=ci --args="--configuration=ios.sim.release"