Package layout conventions

Package layout conventions

When you build a pub package,we encourage you to follow the conventions that this page describes.They describe how you organize the files and directories within yourpackage, and how to name things.

Note: Flutter apps can use custom directories for their assets. For details, see Adding assets and images on the Flutter website.

Here’s what a complete package (named enchilada)that uses every corner of these guidelinesmight look like:

enchilada/
  .dart_tool/ *
  .packages *
  pubspec.yaml
  pubspec.lock **
  LICENSE
  README.md
  CHANGELOG.md
  benchmark/
    make_lunch.dart
  bin/
    enchilada
  doc/
    api/ ***
    getting_started.md
  example/
    main.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 .dart_tool directory and .packages file exist after you’ve run pub get. Don’t check them 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.

Note: The .packages file has replaced packages directories. For more information, see pub get.

The pubspec

enchilada/
  pubspec.yaml
  pubspec.lock

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

Running pub get,pub upgrade, orpub downgrade on the package creates alockfile, named pubspec.lock. If your package is an applicationpackage, check the lockfile into sourcecontrol. Otherwise, don’t.

For more information, see the pubspec page.

LICENSE

enchilada/
  LICENSE

If you’re publishing your package, include a license file named LICENSE,optionally with a file extension such as .md. We recommend using an OSI-approved licensesuch as BSD-3-Clause,so that others can reuse your work.

README

enchilada/
  README.md

One file that’s very common in open source is a README file thatdescribes the project. This is especially important in pub. When you uploadto the pub.dev site, your README is shown onthe page for your package. This is the perfect place to introduce people toyour code.

If your README ends in .md, it’s parsed asMarkdown.

CHANGELOG

enchilada/
  CHANGELOG.md

To show users the latest changes to your package, you can include a changelogfile where you can write a short note about the changes in your latestrelease. When you upload your package to thepub.dev site, your package’s changelog file (if any)appears in the changelog tab.

If your CHANGELOG ends in .md, it’s parsed asMarkdown.

Public directories

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

Public libraries

The following directory structure shows the lib portion of enchilada:

enchilada/
  lib/
    enchilada.dart
    tortilla.dart

Many packages are librarypackages: theydefine Dart libraries that other packages can import and use.These public Dart 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, likeenchilada.dart in the example here. But you can also define otherlibraries with whatever names make sense for your package.

When you do, users can import these libraries using the name of thepackage 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 createsubdirectories inside lib. If you do that, users will specify that pathwhen 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—Dart scripts with a main() function—cannotgo in lib. If you place a Dart script inside lib,you will discover that any package: imports it contains don’tresolve. Instead, your entrypoints should go in the appropriateentrypoint directory.

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

For more information on library packages, seeCreating packages.

Public tools

Dart scripts placed inside of the bin directory are public. If you’reinside the directory of a package, you can usepub run to run scripts from the bindirectories of any other package the package depends on. From _any_directory, you can use pub global run to runscripts from packages you have activated using pub global activate.

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

Public assets

enchilada/
  lib/
    guacamole.css

While most library packages exist to let you reuse Dart code, you can alsoreuse other kinds of content. For example, a package forBootstrap might include a number of CSS filesfor consumers of the package to use.

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

You can reference another package’s assets using theresource package.

Warning:Old code might refer to assets using /packages/<package>/<path> URLs.

Implementation files

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

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

You are free to import libraries that live in lib/src from within other Dartcode in the same package (like other libraries in lib, scripts in bin, andtests) 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 inways that could break your code.

When you use libraries from within your own package, even code in src, youcan (and should) still use package: to import them. For example:

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

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

Web files

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

For web packages, place entrypoint code—Dart scripts that includemain() and supporting files, such as CSS or HTML—under web.You can organize the web directory into subdirectories if you like.

Put library code under lib.If the library isn’t imported directly by code under web, or byanother package, put it under lib/src.Put web-based examples under example. SeePublic assets for tips on where to put assets,such as images.

Command-line apps

enchilada/
  bin/
    enchilada

Some packages define programs that can be run directly from the commandline. These can be shell scripts or any other scripting language,including Dart. The pub application itself is one example: it’sa 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 upusingpub global.

Tests and benchmarks

enchilada/
  test/
    enchilada_test.dart
    tortilla_test.dart

Every package should have tests. With pub, the convention isthat 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 testpackage.

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 maybeother empirical metrics).

Documentation

enchilada/
  doc/
    api/
    getting_started.md

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

When you run the dartdoctool, 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’thave any guidelines about format or organization of the documentationthat you author. Use whatever markup format that you prefer.

Examples

enchilada/
  example/
    main.dart

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

In your examples, use package: to import files from your own package.That ensures that the example code in your package looks exactlylike code outside of your package would look.

If you might publish your package,consider creating an example file with one of the following names(case insensitive):

example/readme[.md]
example/example[.md]
example[/lib]/main.dart
example[/lib]/package_name.dart
example[/lib]/package_name_example.dart
example[/lib]/example.dart

When you publish a package that contains one or more of the above files,the pub.dev site creates an Example tab to display the first file it finds(searching in the order shown in the list above).For example, if your package has many files under its example directory,including a file named README.md,then your package’s Example tab displays the contents of example/README.md(parsed as Markdown.)

Internal tools and scripts

enchilada/
  tool/
    generate_docs.dart

Mature packages often have little helper scripts and programs that peoplerun 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.