How to use packages

How to use packages

The Dart ecosystem uses packages to manage shared softwaresuch 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 andwith your SDK version.

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

At a minimum,a Dart package is 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, apps, resources, tests, images, and examples.

To use a package, do the following:

Create a pubspec (a file named pubspec.yaml that lists package dependencies and includesother metadata, such as a version number).
Use pub to get your package’s dependencies.
If your Dart code depends on a library in the package, import the library.

Creating a pubspec

The pubspec is a file named pubspec.yamlthat’s in the top directory of your application.The simplest possible pubspec lists only the package name:

name: my_app

Here is an example of a pubspec that declares dependencies ontwo packages (js and intl) that are hosted on the pub.dev site:

name: my_app
dependencies:
  js: ^0.6.0
  intl: ^0.15.8

For details on creating a pubspec,see the pubspec documentationand the documentation for the packages that you want to use.

Getting packages

Once you have a pubspec, you can run pubget 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.If your app depends on a published package, pub downloads that package from thepub.dev site.For a Git dependency,pub clones the Git repository.Transitive dependencies are included, too.For example, if the js package depends on the test package, pubgrabs both the js package and the test package.

Pub creates a.packages file (under your app’s top directory)that maps each package namethat your app depends on to the corresponding package in the system cache.

Importing libraries from packages

To import libraries found in packages, use thepackage: 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 foryour app.

You can also use this style to import libraries from within your own package.Consider the following pubspec file, which declares a dependency onthe (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 parsertest file _could import parser.dart like this:

import '../../lib/parser.dart';

But that’s a fragile relative path. If parser_test.dart ever movesup or down a directory, that path breaks.Instead, you can do as follows:

import 'package:transmogrify/parser.dart';

This way, the import can always get to parser.dart regardless of where theimporting 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 withyour other dependencies.It then locks your package to always use that version bycreating a lockfile.This is a file named pubspec.lock that pub creates and stores next to yourpubspec. It lists the specific versions of each dependency (immediate andtransitive) that your package uses.

If your package is an application package,you should check this file intosource control.That way, everyone working on your app uses the same versionsof all of the packages.Checking in the lockfile also ensures that your deployed appuses the same versions of code.

When you’re ready to upgrade your dependencies to the latest versions,use pub upgrade:

$ pub upgrade

That command tells pub to regenerate the lockfile, using the newestavailable versions of your package’s dependencies.If you want to upgrade only one dependency,you can specify the package to upgrade:

$ pub upgrade transmogrify

That command upgrades transmogrify to the latest versionbut leaves everything else the same.

More information

The following pages have more information about packages andthe pub package manager.

How to

Reference

Pub commands

The pub tool provides the following commands:

For an overview of all the pub commands,see the pub tool documentation.

Troubleshooting

Troubleshooting pub gives solutions to problems thatyou might encounter when using pub.