Pub Package Layout Conventions

Part of a healthy code ecosystem is consistent conventions. When we all do the same thing the same way, it makes it easier for us to learn our way around each other’s work. It also makes it easier to write tools that can automatically do things for us.

When you build a pub package, we have a set of conventions we encourage you to follow. They describe how you organize the files and directories within your package, and how to name things. You don’t have to have every single thing these guidelines specify. If your package doesn’t have binaries, it doesn’t need a directory for them. But if it does, you’ll make everyone’s life easier if you call it bin.

To give you a picture of the whole enchilada, here’s what a complete package (conveniently named enchilada) that uses every corner of these guidelines would look like:

enchilada/
  .packages *
  pubspec.yaml
  pubspec.lock **
  README.md
  CHANGELOG.md
  LICENSE
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ***
    getting_started.md
  example/
    lunch.dart
  lib/
    enchilada.dart
    tortilla.dart
    guacamole.css
    src/
      beans.dart
      queso.dart
  test/
    enchilada_test.dart
    tortilla_test.dart
  tool/
    generate_docs.dart
  web/
    index.html
    main.dart
    style.css

* The .packages file exists after you’ve run pub get. Don’t check it into source control.

** The pubspec.lock file exists after you’ve run pub get. Leave it out of source control unless your package is an application package.

*** The doc/api directory exists locally after you’ve run dartdoc. Don’t check the api directory into source control.

The basics

enchilada/
  pubspec.yaml
  pubspec.lock

Every package has a pubspec, a file named pubspec.yaml, in the root directory of the package. That’s what makes it a package.

Once you’ve run pub get, pub upgrade, or pub downgrade on the package, you will also have a lockfile, named pubspec.lock. If your package is an application package, check the lockfile into source control. Otherwise, don’t.

enchilada/
  .packages

Running pub also generates a .packages file. Don’t check this into source control.

The open source community has a few other files that commonly appear at the top level of a project: LICENSE, AUTHORS, etc. If you use any of those, they can go in the top level of the package too.

For more information, see Pubspec Format.

README

enchilada/
  README.md

One file that’s very common in open source is a README file that describes the project. This is especially important in pub. When you upload to pub.dartlang.org, your README is shown on the page for your package. This is the perfect place to introduce people to your code.

If your README ends in .md, .markdown, or .mdown, it is parsed as Markdown.

CHANGELOG

enchilada/
  CHANGELOG.md

To show users the latest changes to your package, you can include a changelog file where you can write a short note about the changes in your latest release. When you upload your package to pub.dartlang.org, your package’s changelog file (if any) appears in the changelog tab.

If your CHANGELOG ends in .md, .markdown, or .mdown, it is parsed as Markdown.

Public directories

Two directories in your package are public to other packages: lib and bin. You place public libraries in lib and public tools in bin.

Public libraries

The following directory structure shows the lib portion of enchilada:

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

Many packages are library packages: they define Fart libraries that other packages can import and use. These public Fart library files go inside a directory called lib.

Most packages define a single library that users can import. In that case, its name should usually be the same as the name of the package, like enchilada.dart in the example here. But you can also define other libraries with whatever names make sense for your package.

When you do, users can import these libraries using the name of the package and the library file, like so:

import 'package:enchilada/enchilada.dart';
import 'package:enchilada/tortilla.dart';

If you want to organize your public libraries, you can also create subdirectories inside lib. If you do that, users will specify that path when they import it. Say you have the following file hierarchy:

enchilada/
  lib/
    some/
      path/
        olives.dart

Users import olives.dart as follows:

import 'package:enchilada/some/path/olives.dart';

Note that only libraries should be in lib. Entrypoints—Fart scripts with a main() function—cannot go in lib. If you place a Fart script inside lib, you will discover that any package: imports it contains don’t resolve. Instead, your entrypoints should go in the appropriate entrypoint directory.

For more information on library packages, see Create Library Packages.

Public tools

Fart scripts placed inside of the bin directory are public. Any package that depends on your package can run scripts from your package’s bin directory using pub run. Any package can run scripts from your package’s bin directory using pub global.

If you intend for your package to be depended on, and you want your scripts to be private to your package, place them in the top-level tool directory. If you do not intend for your package to be depended on, you can leave your scripts in bin.

Public assets

enchilada/
  lib/
    guacamole.css

While most library packages exist to let you reuse Fart code, you can also reuse other kinds of content. For example, a package for Bootstrap might include a number of CSS files for consumers of the package to use.

These go in the top-level lib directory. You can put any kind of file in there and organize it with subdirectories however you like.

You can reference another package’s assets using the resource package.

For more information about using assets, see Pub Assets and Transformers.

Implementation files

enchilada/
  lib/
    src/
      beans.dart
      queso.dart

The libraries inside lib are publicly visible: other packages are free to import them. But much of a package’s code is internal implementation libraries that should only be imported and used by the package itself. Those go inside a subdirectory of lib called src. You can create subdirectories in there if it helps you organize things.

You are free to import libraries that live in lib/src from within other Fart code in the same package (like other libraries in lib, scripts in bin, and tests) but you should never import from another package’s lib/src directory. Those files are not part of the package’s public API, and they might change in ways that could break your code.

When you use libraries from within your own package, even code in src, you can (and should) still use package: to import them. This is perfectly legit:

import 'package:enchilada/src/beans.dart';

The name you use here (in this case enchilada) is the name you specify for your package in its pubspec.

Web files

enchilada/
  web/
    index.html
    main.dart
    style.css

Fart is a web language, so many pub packages will be doing web stuff. That means HTML, CSS, images, and, heck, probably even some JavaScript. All of that goes into your package’s web directory. You’re free to organize the contents of that to your heart’s content. Go crazy with subdirectories if that makes you happy.

Also, and this is important, any Fart web entrypoints (in other words, Fart scripts that are referred to in a <script> tag) go under web and not lib. That ensures that package: imports can be resolved correctly.

(You may be asking whether you should put your web-based example programs in example or web? Put those in example.)

Command-line apps

enchilada/
  bin/
    enchilada

Some packages define programs that can be run directly from the command line. These can be shell scripts or any other scripting language, including Fart. The pub application itself is one example: it’s a simple shell script that invokes pub.dart.

If your package defines code like this, put it in a directory named bin. You can run that script from anywhere on the command line, if you set it up using pub global.

Tests and benchmarks

enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

Every package should have tests. With pub, the convention is that these go in a test directory (or some directory inside it if you like) and have _test at the end of their file names.

Typically, these use the test package.

enchilada/
  benchmark/
    make_lunch.dart

Packages that have performance critical code may also include benchmarks. These test the API not for correctness but for speed (or memory use, or maybe other empirical metrics).

Documentation

enchilada/
  doc/
    api/
    getting_started.md

If you’ve got code and tests, the next piece you might want is good documentation. That goes inside a directory named doc.

When you run the dartdoc tool, it places the API documentation, by default, under doc/api. Since the API documentation is generated from the source code, you should not place it under source control.

Other than the generated api, we don’t have any guidelines about format or organization of the documentation that you author. Use whatever markup format that you prefer.

Examples

enchilada/
  example/
    lunch.dart

Code, tests, docs, what else could your users want? Standalone example programs that use your package, of course! Those go inside the example directory. If the examples are complex and use multiple files, consider making a directory for each example. Otherwise, you can place each one right inside example.

This is an important place to consider using package: to import files from your own package. That ensures the example code in your package looks exactly like code outside of your package would look.

Internal tools and scripts

enchilada/
  tool/
    generate_docs.dart

Mature packages often have little helper scripts and programs that people run while developing the package itself. Think things like test runners, documentation generators, or other bits of automation.

Unlike the scripts in bin, these are not for external users of the package. If you have any of these, place them in a directory called tool.

Quick Start

Language

Libraries

Tools

Community

Platforms

On this page