Install shared packages

Borrow and share code.

Once you can create and run a Dart app, you’re ready to leverage code written by other programmers. Many interesting and useful packages of reusable Dart code are available at the pub.dev site repository.

This tutorial shows how to use dart pub—a package manager that comes with Dart—to install one of the packages in the repository, the vector_math package. You can follow these same steps to install any package hosted at the pub.dev site; just change the package name when you get to that step. This tutorial also describes some of the resources you can expect to find in a well-built package.

About the pubspec.yaml file

To use an external package, your app must itself be a package. Any app with a valid pubspec.yaml file in its top-level directory is a package and can therefore use external packages.

You can use the dart create command to generate packages with valid pubspec.yaml files and directory structures. This command works either at the command line or (behind the scenes) in an IDE such as IntelliJ or WebStorm.

Now run the dart create command to see what kinds of template files it can generate:

$ dart create

You’ll see a list of generators, including various web and server-side apps. One of the generators is named console-full.

Use the dart create command to generate a command-line app named vector_victor:

$ dart create -t console-full vector_victor 
$ cd vector_victor

The pubspec.yaml file contains the package specification written in YAML. (Visit Pubspec Format for in-depth coverage.) The contents of your pubspec.yaml file should look something like this:

name: vector_victor
description: A sample command-line application.

environment:
  sdk: '>=2.8.1 <3.0.0'

#dependencies:
#  path: ^1.7.0

dev_dependencies:
  pedantic: ^1.9.0
  test: ^1.14.4

Name the package dependencies

To use an external library package, you need to add the package to your app’s list of dependencies in the pubspec.yaml file. Each item in the dependencies list specifies the name and version of a package that your app uses.

Let’s make the vector_victor app have a dependency on the vector_math package, which is available at the pub.dev site.

1. Get the current installation details for the package:

   1. Go to vector_math’s entry on the Package site.
   2. Click the Installing tab.

   3. Copy the vector_math line from the sample dependencies entry. The entry should look something like this:

      dependencies:
        vector_math: ^2.0.8
      

2. Edit pubspec.yaml.

3. In the dependencies section, add the string you copied from the pub.dev site. Be careful to keep the indentation the same; YAML is picky! For example:

   environment:
     sdk: '>=2.8.1 <3.0.0'
   
   dependencies:
     vector_math: ^2.0.8
   
   dev_dependencies:
     pedantic: ^1.9.0
     test: ^1.14.4
   

For details of what version numbers mean and how you can format them, see Pub versioning philosophy.

The pub.dev site is the primary public repository for Dart packages. dart pub automatically checks that website when resolving package dependencies. To use one of the packages from that site, you can specify it by its simple name, as we have done here.

Install the package dependencies

If you’re using an IDE or Dart-savvy editor to edit pubspec.yaml, it might automatically install the packages your app depends on.

If not, do it yourself by running dart pub get:

$ dart pub get
Resolving dependencies...
+ vector_math 2.0.8
Changed 1 dependency!

The dart pub get command installs the packages in your app’s dependencies list. Each package can contain libraries and other assets. Pub works recursively; if an included package has dependencies, those packages are installed as well. Pub caches the files for each package your app depends on, pointing to them from a file named .packages.

Pub creates a file called pubspec.lock that identifies the specific versions of the packages that were installed. This helps to provide a stable development environment. Later you can modify the version constraints and use dart pub upgrade to update to new versions as needed.

What did you get (and not get)?

Besides the Dart libraries, the vector_math package has other resources that might be useful to you that do not get installed into your app directory. Let’s take a step back for a moment to look at what you got and where it came from.

To see the contents of the vector_math package, visit the Dart vector math repository at GitHub. Although many files and directories are in the repository, only one, lib, was installed when you ran pub get.

---

Dart libraries: The lib directory contains one or more Dart libraries, which can be imported into your Dart programs.

---

Housekeeping files: When using a package written by someone else, the README.md file is a good place to start. It should contain important information about the package, such as its intent, contents, samples, and instructions. The LICENSE file provides copyright and rules-of-use information. All of these files are in the package repository; the contents of some, such as README.md, are also displayed in pub.dev. These files aren't installed when you install a package.

---

Other resources: Along with Dart libraries, a package might also contain other resources such as example code, tests, scripts, and documentation. If a package contains these resources, they should be in the directories as specified in the pub conventions.

---

Import libraries from a package

Now that you’ve installed the package, you can import its libraries and use them in your app.

As with the SDK libraries, use the import directive to use code from an installed library. The Dart SDK libraries are built in and are identified with the special dart: prefix. For external libraries installed by pub, use the package: prefix.

1. Get the import details for the package’s main library:

   1. Go to vector_math’s entry on the Package site.
   2. Click the Installing tab.

   3. Copy the import line. It should look something like this:

      import 'package:vector_math/vector_math.dart';
      

2. In your vector_victor app, edit lib/vector_victor.dart, so that it imports the vector_math library and uses some of its API. For inspiration, look at the vector_math API docs, which you can find from the pub.dev site entry.

Other resources

• Dart developers share packages at the pub.dev site. Look there for packages that might be useful to you, or share your own Dart packages.
• See the pub package documentation for more information on using and sharing packages.