3_dart_ecosystem

Step 3: Dart ecosystem

Estimated time: 1 day

These steps describe the common Dart tooling, packages and ecosystem approaches, proven to be especially useful and commonly used when building modern modular Dart applications.

Project structure

The Dart ecosystem uses packages to manage shared software such as libraries and tools. To get Dart packages, you use the pub package manager. You can find publicly available packages on the pub.dev site, or you can load packages from the local file system or elsewhere, such as Git repositories. Wherever your packages come from, pub manages version dependencies, helping you get package versions that work with each other and with your SDK version.

Most Dart-savvy IDEs offer support for using pub that includes creating, downloading, updating, and publishing packages. Or you can use dart pub on the command line.

Dart project represents a Dart package when it has a pubspec.yaml manifest file.

name: task
description: A sample command-line application.
version: 1.0.0
# repository: https://github.com/my_org/my_repo

environment:
  sdk: ^3.0.2

# Add regular dependencies here.
dependencies:
  # path: ^1.8.0

# Add development dependencies here.
dev_dependencies:
  lints: ^2.0.0
  test: ^1.21.0

To import libraries found in packages, use the package: prefix:

import 'package:js/js.dart' as js;
import 'package:intl/intl.dart';

The initial files layout of a Dart project looks like this:

lib/
├── ...
└── main.dart
pubspec.yaml

However, real-world Dart projects, depending on their needs, may also include a test/ directory for unit testing, an example/ directory providing usage examples (if it's a library), and other similar ones.

To learn more about packages, dependencies and project structure in Dart, read through the following articles:

• Dart Guides: How to use packages
• Dart Guides: Creating packages
• Dart Docs: Package layout conventions
• Dart Docs: Package dependencies

Tooling

When it comes to sharing Dart code with anyone, it's necessary to follow some core guidelines in order for the source code to be readable and consistent in its style. Such core guidelines in Dart are called Effective Dart.

Dart provides several CLI tools for maintaining project source code and helping following project guidelines.

Formatter

dart format tool formats source code according to Effective Dart style.

However, this tool is not as smart as it could be. In order for it to format the code in a more readable and beautiful way, dart format relies on commas.

For better understanding of dart format purpose, capabilities and usage, read through the following articles:

• Dart Tools: dart format
• Dart Tools: Code formatting
• Official dart_style package docs
• Official dart_style package FAQ

Analyzer

dart analyze tool uses the analyzer package to perform the basic source code static analysis and to lint it against Effective Dart guidelines or any other custom code style rules.

For better understanding of dart analyze purpose, capabilities and usage, read through the following articles:

• Dart Tools: dart analyze
• Dart Guides: Customizing static analysis
• Official analyzer package docs

Documentation

dart doc tool uses the dartdoc package to generates an HTML documentation right from the project source code.

For better understanding of dart doc purpose, capabilities and usage, read through the following articles:

• Dart Tools: dart doc
• Dart Docs: Documentation comments
• Effective Dart: Documentation
• Official dartdoc package docs

Task

Create a Dart package (dart create -t package task) implementing a simple Calculator class having sum, subtract, multiply and divide methods.

• Use dart format to format the code.
• Configure the analyzer package and use dart analyze.
• Generate its API documentation using dart doc.

Questions

After completing everything above, you should be able to answer (and understand why) the following questions:

• What is pub? What it does? Why do we need it?
• What is pub spec? Which purpose does it serve?
• What is the purpose of pubspec.lock file? When and why it should be stored in VCS, and when not?
• What does "version range" mean? How is it useful for dependencies?
• Where is pub able to get dependencies from?
• What is the difference between development dependencies and regular one? Which ones should be used and when?
• How Dart projects are structured in files? Which are common conventions and what for?
• What do we need Effective Dart for? Why is it vital?
• What is dart format used for? What are the benefits of using it?
• How commas are used to guide code formatting in Dart?
• What is static analysis? What is linting? How they are represented in Dart? Why should we use them?
• Why source code documentation matters? How is it represented in Dart?
• Which are good practices for documenting code and APIs in Dart?
• How can one publish and serve API documentation in Dart?