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 site repository.

This tutorial shows how to use 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 site](https://pub.dartlang.org; 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 Stagehand tool to generate packages with valid pubspec.yaml files and directory structures. Stagehand works either at the command line or (behind the scenes) in an IDE such as IntelliJ or WebStorm.

Install or update Stagehand using pub global activate:

> pub global activate stagehand

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

> stagehand

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

In a new directory named vector_victor, use Stagehand to generate a command-line app:

> mkdir vector_victor
> cd vector_victor
> stagehand console-full

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.1.0 <3.0.0'

#dependencies:
#  path: ^1.4.1

dev_dependencies:
  test: ^1.0.0

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 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.7
      

2. Edit pubspec.yaml.

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

   environment:
     sdk: '>=2.1.0 <3.0.0'
   
   dependencies:
     vector_math: ^2.0.7
   
   dev_dependencies:
     test: ^1.0.0
   

See Pub Versioning Philosophy for details of what version numbers mean, and how you can format them.

The Pub site is the primary public repository for Dart packages. 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 pub get:

> pub get
Resolving dependencies...
+ vector_math 2.0.7
Changed 1 dependency!
Precompiling executables...
Precompiled vector_math:mesh_generator.

The 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 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 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. These files can be found at the package repository. They are not 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 site entry.

Other resources

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