Getting Started with Pub
You can use pub to manage Dart packages.
At the very minimum, a Dart package is simply a directory containing a pubspec file.
The pubspec contains some metadata about the package. Additionally, a package can contain dependencies (listed in the pubspec), Dart libraries, command-line apps, web apps, resources, tests, images, or examples. If your app uses one or more packages, then your app itself must be a package.
A package can live anywhere. For example, some packages are on GitHub. The Dart team publishes packages at the Pub site, and we hope you will, too.
To use a library that is in a Dart package, you need to do the following:
- Create a pubspec (a file that lists package dependencies and includes other metadata, such as a name for your package).
- Use pub to get your package’s dependencies.
- Import the library.
Creating a pubspec
To use a package, your application must define a pubspec. The simplest possible pubspec lists only the package name:
name: my_app
A pubspec is where you list dependencies and their download locations.
The pubspec is a file named pubspec.yaml,
and it must be in the top directory of your application.
Here is an example of a pubspec that specifies the locations of two packages. First, it points to the js package that is hosted on the Pub site, and then it points to the intl package in the Dart SDK:
name: my_app dependencies: js: ^0.3.0 intl: ^0.12.4
For details, see the pubspec documentation and the documentation for the packages you are interested in using.
Installing packages
Once you have a pubspec, you can run pub
get from the top directory of your application:
cd <path-to-my_app> pub get
This process is called getting the dependencies.
The pub get command determines which packages your app depends on,
and puts them in a central system cache.
For git dependencies, pub clones the git repository.
For hosted dependencies, pub downloads the package from the
Pub site. Transitive dependencies are included, too.
For example, if the js package depends on the test package, pub
grabs both the js package and the test package.
Pub creates a
.packages file (under your app’s top directory)
that maps each package name
that your app depends on to the corresponding package in the system cache.
Importing libraries from packages
To import libraries found in packages, use the
package: prefix:
import 'package:js/js.dart' as js; import 'package:intl/intl.dart';
The Dart runtime takes everything after package:
and looks it up within the .packages file for
your app.
You can also use this style to import libraries from within your own package.
Consider the following pubspec file, which declares a dependency on
the (fictional) transmogrify package:
name: my_app dependencies: transmogrify:
Let’s say that your package is laid out as follows:
transmogrify/
lib/
transmogrify.dart
parser.dart
test/
parser/
parser_test.dart
The parser_test file could import parser.dart like this:
import '../../lib/parser.dart';
But that’s a fragile relative path. If parser_test.dart is ever moved
up or down a directory, that path will break and you’ll have to fix the code.
Instead, you can do as follows:
import 'package:transmogrify/parser.dart';
This way, the import can always get to parser.dart regardless of where the
importing file is.
Upgrading a dependency
The first time you get a new dependency for your package,
pub downloads the latest version of it that’s compatible with
your other dependencies.
It then locks your package to always use that version by
creating a lockfile.
This is a file named pubspec.lock that pub creates and stores next to your
pubspec. It lists the specific versions of each dependency (immediate and
transitive) that your package uses.
If this is an application package, you should check this file into source control. That way, everyone working on your app ensures they are using the same versions of all of the packages. This also makes sure that you use the same versions of code when you deploy your app to production.
When you are ready to upgrade your dependencies to the latest versions, do:
$ pub upgrade
This tells pub to regenerate the lockfile using the newest available versions of your package’s dependencies. If you only want to upgrade a specific dependency, you can specify that too:
$ pub upgrade transmogrify
This upgrades transmogrify to the latest version but leaves everything else
the same.