nx-dart is a Nx plugin, that adds support for developing Dart and Flutter packages in a Nx workspace.

This plugin is at an early stage of development. Please open an issue if you find a bug or have a feature request. Feel free to open a discussion, if you have a question.

Features

• Surface dependencies between packages to the Nx project graph.
• Executors:
  • format
  • analyze
  • test
• Generators:
  • add-package
  • change-lints

Getting started

Create a new Nx workspace with the nx-dart preset

Run the following command to create a new Nx workspace including nx-dart:

npx create-nx-workspace <workspace-name> --preset=@nx-dart/nx-dart

Add Nx and nx-dart to an existing monorepo

In an existing monorepo, run the following command to add Nx and nx-dart:

npx add-nx-dart-to-monorepo

Nx projects and Dart packages

Every package that should be part of the Nx workspace needs to have a project.json file in the package root and needs to be registered in the workspace.json file at the root of the workspace.

The add-package generator takes care of creating an initial project.json file and registering the project in workspace.json, under the package's name.

If package B depends on package A and both live in the same workspace, the Nx project graph will reflect this dependency. Dependencies on local packages are not automatically overridden with path dependency for development, though. If this is something you need, implement your own mechanism for overriding dependencies or check out Melos.

Melos is a Dart/Flutter specific monorepo tool with support for conventional commit based versioning and publishing, among other features. Melos and Nx complement each other, and can be used together.

Generators

add-package

Adds an existing Dart package to the workspace.

This generator is usually used to integrate a package into the Nx workspace after creating it with dart create or flutter create:

flutter create -t app apps/counter
npx nx generate @nx-dart/nx-dart:add-package apps/counter

Options

• --project-type: The Nx project type of the package. This is optional. If not specified, the project type is inferred.

change-lints

Changes the lint rules in the workspace analysis options.

Lint rules are defined in the analysis_options.yaml file at the project root. These options apply to all packages in the workspace, that don't have a analysis_options.yaml file of their own.

This generator changes the lint rules to one of the following:

• core: Core rules from the lints package.
• recommended: Recommended rules from the lints package.
• flutter: Rules from the flutter_lints package.
• all: All available lint rules. Requires resolving conflicting rules.

npx nx generator @nx-dart/nx-dart:change-lints flutter

Executors

format

Formats Dart files in a package.

// libs/foo/project.json
{
  "targets": {
    "format": {
      "executor": "@nx-dart/nx-dart:format",
      "outputs": []
    }
  }
}

Options

• check: Whether to validate the current formatting instead of fixing it. Default is false.

analyze

Analyzes a Dart package.

// libs/foo/project.json
{
  "targets": {
    "analyze": {
      "executor": "@nx-dart/nx-dart:analyze",
      "outputs": []
    }
  }
}

Options

• fatalInfos: Treat info level issues as fatal. Default is true.
• fatalWarnings: Treat warning level issues as fatal. Default is true.

test

Runs Dart or Flutter tests in a package.

// libs/foo/project.json
{
  "targets": {
    "test": {
      "executor": "@nx-dart/nx-dart:test",
      "outputs": ["libs/foo/coverage"]
    },
    "e2e": {
      "executor": "@nx-dart/nx-dart:test",
      "outputs": ["libs/foo/coverage"],
      "options": {
        "targets": ["integration_test"]
      }
    }
  }
}

Options

• targets: The files or directories which contain the tests to run. When not specified, all tests in the test directory are run.
• coverage: Whether to collect coverage information. The dart tool does not output lcov.info files by default. The executor converts the Dart coverage data into a lcov.info file automatically. The flutter tool outputs a lcov.info file by default.

All additional options are passed to the Dart or Flutter test tool. Abbreviations are not supported.