tidy_imports 1.0.0

Automatically organize your Dart imports. Sorts and groups dart, flutter, package, and project imports alphabetically. Spiritual successor to import_sorter.

████████╗██╗██████╗░██╗░░░██╗  ██╗███╗░░░███╗██████╗░░█████╗░██████╗░████████╗░██████╗
╚══██╔══╝██║██╔══██╗╚██╗░██╔╝  ██║████╗░████║██╔══██╗██╔══██╗██╔══██╗╚══██╔══╝██╔════╝
░░░██║░░░██║██║░░██║░╚████╔╝░  ██║██╔████╔██║██████╔╝██║░░██║██████╔╝░░░██║░░░╚█████╗░
░░░██║░░░██║██║░░██║░░╚██╔╝░░  ██║██║╚██╔╝██║██╔═══╝░██║░░██║██╔══██╗░░░██║░░░░╚═══██╗
░░░██║░░░██║██████╔╝░░░██║░░░  ██║██║░╚═╝░██║██║░░░░░╚█████╔╝██║░░██║░░░██║░░░██████╔╝
░░░╚═╝░░░╚═╝╚═════╝░░░░╚═╝░░░  ╚═╝╚═╝░░░░░╚═╝╚═╝░░░░░░╚════╝░╚═╝░░╚═╝░░░╚═╝░░░╚═════╝░

A Dart CLI tool that automatically organizes your import statements — sorted alphabetically and grouped by origin (Dart, Flutter, package, project).

Spiritual successor to import_sorter, rebuilt for Dart 3+ with bug fixes, new flags, custom import tiers, pubspec.yaml sorting, and monorepo support.

How it works

Imports are grouped in this order and sorted alphabetically within each group:

1. Dart imports (dart:)
2. Flutter imports (package:flutter/)
3. Package imports (package:)
4. Project imports (relative or package:<your_package>/)

Before

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import 'dart:io';
import 'package:myapp/home.dart';
import 'dart:async';
import 'package:intl/intl.dart';
import 'another_file.dart';

After

// Dart imports:
import 'dart:async';
import 'dart:io';

// Flutter imports:
import 'package:flutter/material.dart';

// Package imports:
import 'package:intl/intl.dart';
import 'package:provider/provider.dart';

// Project imports:
import 'package:myapp/home.dart';
import 'another_file.dart';

Installation

As a dev dependency (per project)

dart pub add dev:tidy_imports
dart run tidy_imports

This adds the latest version to dev_dependencies for you.

Global activation

dart pub global activate tidy_imports
tidy_imports

Usage

# Sort all dart files in the project
dart run tidy_imports

# Sort specific files
dart run tidy_imports lib/main.dart lib/app.dart

# Sort files matching a glob pattern
dart run tidy_imports "lib/src/*"

# Preview changes without writing (dry run)
dart run tidy_imports --dry-run

# CI: fail if any file is unsorted
dart run tidy_imports --exit-if-changed

Options

Flag	Short	Description
--emojis	-e	Add emojis to import group comments
--no-comments		Omit group comments entirely
--no-blank-lines		Omit blank lines between import groups
--sort-pubspec		Also sort pubspec.yaml dependencies alphabetically
--dry-run		Preview changes without writing files
--exit-if-changed		Exit with code 1 if any file would change
--ignore-config		Ignore configuration file / pubspec.yaml block
--version	-v	Print version and exit
--help	-h	Show help

Configuration

Add a tidy_imports: block to your pubspec.yaml:

tidy_imports:
  emojis: false          # Default: false — add emojis to group comments
  comments: true         # Default: true  — add group comments
  blank_lines: true      # Default: true  — blank lines between groups
  sort_pubspec: false    # Default: false — also sort pubspec.yaml deps
  ignored_files:         # Regex patterns applied to relative file paths
    - \/lib\/generated\/  # ignore a whole folder
    - \.g\.dart$          # ignore generated files (build_runner)
    - \.freezed\.dart$    # ignore freezed files
    - \.gr\.dart$         # ignore auto_route files
  tiers:                 # Custom import groups (see below)
    - name: "Company imports:"
      pattern: "package:acme_"

The ignored_files patterns are regular expressions matched against the path relative to the project root (e.g. /lib/src/foo.dart).

Standalone config file

Instead of the pubspec.yaml block, you can place the same options in a tidy_imports.yaml file at the project root. When present, it takes precedence over the pubspec.yaml block — handy for monorepos with a shared root config.

# tidy_imports.yaml
emojis: false
sort_pubspec: true
ignored_files:
  - \.g\.dart$

Custom import tiers

By default, all third-party packages share the single Package imports group. Custom tiers let you split out internal/shared packages into their own group, placed between the generic package group and your project imports:

tidy_imports:
  tiers:
    - name: "Shared imports:"
      pattern: "package:acme_shared"
    - name: "Company imports:"
      pattern: "package:acme_"

Each import whose line contains a tier's pattern goes into that tier (first match wins, so list the most specific patterns first). Result:

// Package imports:
import 'package:http/http.dart';

// Shared imports:
import 'package:acme_shared/utils.dart';

// Company imports:
import 'package:acme_billing/api.dart';

// Project imports:
import 'package:myapp/home.dart';

Sorting pubspec.yaml

Pass --sort-pubspec (or set sort_pubspec: true) to also alphabetize the dependencies, dev_dependencies, and dependency_overrides sections of your pubspec.yaml. Nested dependency blocks (git/path/hosted) and comments attached to a dependency are preserved.

dart run tidy_imports --sort-pubspec

CI Integration

GitHub Actions

- name: Check import order
  run: dart run tidy_imports --exit-if-changed

The command exits with code 1 if any file has unsorted imports, causing the CI job to fail. Use --dry-run locally to preview what would change without modifying files.

pre-commit hook

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Franklyn-R-Silva/tidy_imports
    rev: 'v1.1.0' # use the latest release tag
    hooks:
      - id: dart-import-sorter      # for plain Dart projects
      # - id: flutter-import-sorter # for Flutter projects

Directories scanned

lib/, src/, bin/, test/, tests/, test_driver/, integration_test/, packages/

The packages/ directory is included to support pub workspaces and monorepos.

Monorepo / pub workspace support

tidy_imports works in pub workspaces where individual packages do not have their own pubspec.lock. When no lock file is found, the tool continues normally — Flutter plugin registrant detection is simply skipped. No crash, no manual workaround needed.

Improvements over import_sorter

Issue	import_sorter	tidy_imports
Arg parsing	Raw string matching — breaks with flags	ArgParser — correct flag resolution
Positional file args	Passes raw args (includes flags)	Uses argResults.rest
pubspec.lock in monorepos	Crashes with PathNotFoundException	Graceful fallback
packages/ folder	Not scanned	Scanned
--dry-run preview	Not available	Available
--no-blank-lines	Not available	Available
Custom import tiers	Not available	Available
Sort pubspec.yaml deps	Not available	--sort-pubspec
Standalone config file	Not available	tidy_imports.yaml
Direct CLI command	dart pub global run ...:main	tidy_imports
Dart SDK	>=2.12.0	>=3.0.0
Conditional imports	Misclassified	Handled correctly
Versioning	Manual	Automated via Release Please

Contributing

Pull requests are welcome! See CONTRIBUTING.md for dev setup, commit format, and the release process.

• Code of Conduct
• Security Policy
• Changelog

Credits

Based on the original work by @gleich and contributors of import_sorter.

License

MIT © Franklyn R. Silva