Creating packages

The Dart ecosystem uses packagesto share software such as libraries and tools.This page tells you how to create a package,with a focus on the most common kind of package,library packages.

What makes a library package

The following diagram shows the layout of the simplestlibrary package:

The minimal requirements for a library are:

• pubspec file

• The pubspec.yaml file for a library is the sameas for an application package—there is no specialdesignation to indicate that the package is a library.

• lib directory

• As you might expect, the library code lives under the lib_directory and is public to other packages.You can create any hierarchy under lib, as needed.By convention, implementation code is placed under _lib/src.Code under lib/src is considered private;other packages should never need to import src/….To make APIs under lib/src public, you can export lib/src filesfrom a file that’s directly under lib.

Note:When the library directive isn’t specified, a uniquetag is generated for each library based on its path and filename.Therefore, we suggest that you omit the library directive fromyour code unless you plan togenerate library-level documentation.

Organizing a library package

Library packages are easiest to maintain, extend, and testwhen you create small, individual libraries, referred to asmini libraries.In most cases, each class should be in its own mini library, unlessyou have a situation where two classes are tightly coupled.

Note: You may have heard of the part directive, which allowsyou to split a library into multiple Dart files. We recommendthat you avoid using part and create mini libraries instead.

Create a “main” library file directly under lib,lib/<package-name>.dart, thatexports all of the public APIs.This allows the user to get all of a library’s functionalityby importing a single file.

The lib directory might also include other importable, non-src, libraries.For example, perhaps your main library works across platforms, butyou create separate libraries that rely on dart:io or dart:html.Some packages have separate libraries that are meant to be importedwith a prefix, when the main library is not.

Let’s look at the organization of a real-world library package: shelf. Theshelfpackage provides an easy way to create web servers using Dart,and is laid out in a structure that is commonly used for Dartlibrary packages:

Directly under lib, the main library file,shelf.dart, exports several files from lib/src:

export 'src/cascade.dart';
export 'src/handler.dart';
export 'src/handlers/logger.dart';
export 'src/hijack_exception.dart';
export 'src/middleware.dart';
export 'src/pipeline.dart';
export 'src/request.dart';
export 'src/response.dart';
export 'src/server.dart';
export 'src/server_handler.dart';

The shelf package also contains a mini library: shelf_io.This adapter handles HttpRequest objects from dart:io.

Tip for web apps:For the best performance when developing withdartdevc,put implementationfiles under /lib/src,instead of elsewhere under /lib.Also, avoid imports of package:package_name/src/….

Importing library files

When importing a library file, you can use thethe package: directive to specify the URI of that file.

import 'package:utilities/utilities.dart';

You can import a library using a relative path whenboth files are inside of lib,or when both files are outside of lib.However, you must use package: when importing a file that reachesinside, or outside, of lib.When in doubt, use the package: directive; it works in all cases.

The following graphic shows howto import lib/foo/a.dart from both lib and web.

Note:Although the lib graphic shows lib/bar/b.dart using a relative import(import '../foo/a.dart'),it could instead use the package: directive(import 'package:my_package/foo/a.dart').

Conditionally importing and exporting library files

If your library supports multiple platforms,then you might need to conditionally import or export library files.A common use case is a library that supports both web and native platforms.

To conditionally import or export,you need to check for the presence of dart:* libraries.Here’s an example of conditional export code thatchecks for the presence of dart:io and dart:html:

export 'src/hw_none.dart' // Stub implementation
    if (dart.library.io) 'src/hw_io.dart' // dart:io implementation
    if (dart.library.html) 'src/hw_html.dart'; // dart:html implementation

lib/hw_mp.dart

Here’s what that code does:

• In an app that can use dart:io(for example, a command-line app),export src/hw_io.dart.
• In an app that can use dart:html(a web app),export src/hw_html.dart.
• Otherwise, export src/hw_none.dart.

To conditionally import a file, use the same code as above,but change export to import.

Note: The conditional import or export checks only whether the library is available for use on the current platform, not whether it’s actually imported or used.

All of the conditionally exported libraries must implement the same API.For example, here’s the dart:io implementation:

import 'dart:io';
void alarm([String text]) {
  stderr.writeln(text ?? message);
}
String get message => 'Hello World from the VM!';

lib/src/hw_io.dart

And here’s the default implementation,which is a stub that throws UnsupportedErrors:

void alarm([String text]) => throw UnsupportedError('hw_none alarm');
String get message => throw UnsupportedError('hw_none message');

lib/src/hw_none.dart

On any platform,you can import the library that has the conditional export code:

import 'package:hw_mp/hw_mp.dart';
void main() {
  print(message);
}

Providing additional files

A well designed library package is easy to test.We recommend that you write tests using thetest package,placing the test code in the test directory at thetop of the package.

If you create any command-line tools intended for public consumption,place those in the bin directory, which is public.Enable running a tool from the command line, usingpub global activate.Listing the tool in theexecutables sectionof the pubspec allows a user to run it directly without callingpub global run.

It’s helpful if you include an example of how to use your library.This goes into the example directory at the top of the package.

Any tools or executables that you create during development that aren’t forpublic use go into the tool directory.

Other files that are required if you publish your library to thepub.dev site, such as a README and a CHANGELOG, aredescribed in Publishing a package.For more information on how to organize a package directory,see the pub package layout conventions.

Documenting a library

You can generate API docs for your library usingthe dartdoc tool.Dartdoc parses the source looking fordocumentation comments,which use the /// syntax:

/// The event handler responsible for updating the badge in the UI.
void updateBadge() {
  ...
}

For an example of generated docs, see theshelf documentation.

Note:To include any library-level documentation in the generated docs,you must specify the library directive.See issue 1082.

Distributing an open source library

If your library is open source,we recommend sharing it on the pub.dev site.To publish or update the library,use pub publish,which uploads your package and creates or updates its page.For example, see the page for the shelf package.See Publishing a packagefor details on how to prepare your package for publishing.

The pub.dev site not only hosts your package,but also generates and hosts your package’s API reference docs.A link to the latest generated docs is in the package’s About box;for example, see the shelf package’sAPI docs.Links to previous versions’ docs are in theVersions tab of the package’s page.

To ensure that your package’s API docs look good on the pub.dev site,follow these steps:

• Before publishing your package, run the dartdoc toolto make sure that your docs generate successfully and look as expected.
• After publishing your package, check the Versions tabto make sure that the docs generated successfully.
• If the docs didn’t generate at all,click failed in the Versions tab to see the dartdoc output.

Resources

Use the following resources to learn more about library packages:

• Libraries and visibilityin the language tour coversusing library files.
• The package documentation is useful, particularly thepackage layout conventions.
• What not to commitcovers what should not be checked into a source code repository.
• The newer library packages under thedart-lang organization tendto show best practices. Consider studying these examples:dart_style,path,shelf,source_gen, andtest.