# Package layout conventions

> Learn more about the directory structure used by Dart's package management tool, pub.



When you build a [pub package](/tools/pub/packages),
we encourage you to follow the conventions that this page describes.
They describe how you organize the files and directories within your
package, and how to name things.

:::flutter-note
Flutter apps can use custom directories for their assets.
For details, see
[Adding assets and images](https://docs.flutter.dev/development/ui/assets-and-images)
on the [Flutter website.](https://docs.flutter.dev)
:::

Here's what a complete package (named `enchilada`)
that uses every corner of these guidelines
might look like:

<FileTree>

- enchilada/
  - .dart_tool/ *
  - benchmark/
    - make_lunch.dart
  - bin/
    - enchilada
  - doc/
    - api/ ****
    - getting_started.md
  - example/
    - main.dart
  - hook/
    - build.dart
  - integration_test/
    - app_test.dart
  - lib/
    - fix_data.yaml
    - enchilada.dart
    - tortilla.dart
    - guacamole.css
    - src/
      - beans.dart
      - queso.dart
  - skills/
    - enchilada-cooking/
      - SKILL.md
  - test/
    - enchilada_test.dart
    - tortilla_test.dart
  - test_fixes/
    - enchilada_fix.dart
    - enchilada_fix.dart.expect
  - tool/
    - generate_docs.dart
  - web/
    - index.html
    - main.dart
    - style.css
  - CHANGELOG.md
  - LICENSE
  - pubspec.yaml
  - pubspec_overrides.yaml **
  - pubspec.lock ***
  - README.md

</FileTree>

\* The `.dart_tool/` directory exists after you've run `dart pub get`.
   Don't check it into source control.
   To learn more, see 
   [Project specific caching for tools](#project-specific-caching-for-tools).

\** The [`pubspec_overrides.yaml`][] file,
    if present, overrides certain aspects of `pubspec.yaml`.
    Usually you don't want to check it into source control.

\*** The `pubspec.lock` file exists after you've run `dart pub get`.
    Leave it out of source control unless your package is an
    [application package](/resources/glossary#application-package).

\**** The `doc/api` directory exists locally after you've run
     [`dart doc`](/tools/dart-doc).
     Don't check the `api` directory into source control.


[`pubspec_overrides.yaml`]: /tools/pub/dependencies#pubspec-overrides

## The pubspec

<FileTree>

- enchilada/
  - pubspec.yaml
  - pubspec.lock

</FileTree>

Every package has a [_pubspec_](/tools/pub/pubspec), a file named
`pubspec.yaml`, in the root directory of the package. That's what *makes* it a
package.

Running [`dart pub get`](/tools/pub/cmd/pub-get),
[`dart pub upgrade`](/tools/pub/cmd/pub-upgrade), or
[`dart pub downgrade`](/tools/pub/cmd/pub-downgrade) on the package
creates a **lockfile**, named `pubspec.lock`. 
If your package is an 
[application package](/resources/glossary#application-package), 
check the lockfile into source control. Otherwise, don't.

For more information, see the [pubspec page](/tools/pub/pubspec).

## LICENSE

<FileTree>

- enchilada/
  - LICENSE

</FileTree>

If you're publishing your package, include a license file named `LICENSE`.
We recommend using an [OSI-approved license](https://opensource.org/licenses)
such as [BSD-3-Clause,](https://opensource.org/licenses/BSD-3-Clause)
so that others can reuse your work.

## README.md

<FileTree>

- enchilada/
  - README.md

</FileTree>

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 the [pub.dev site,](https://pub.dev) your `README.md` file
is shown—rendered as [Markdown][]—on the page for your package. 
This is the perfect place to introduce people to your code.

For guidance on how to write a great README, see
[Writing package pages](/tools/pub/writing-package-pages).

<a id="changelogmd" aria-hidden="true"></a>

## CHANGELOG.md {:#changelog}

<FileTree>

- enchilada/
  - CHANGELOG.md

</FileTree>

Include a `CHANGELOG.md` file that has a section for
each release of your package,
with notes to help users of your package upgrade.
Users of your package often review the changelog
to discover bug fixes and new features,
or to determine how much effort it will take to upgrade
to the latest version of your package.

To support tools that parse `CHANGELOG.md`,
use the following format:

* Each version has its own section with a heading.
* The version headings are either all level 1 or all level 2.
* The version heading text contains a package version number,
  optionally prefixed with "v".

When you upload your package to the [pub.dev site,](https://pub.dev)
your package's `CHANGELOG.md` file (if any)
appears in the **Changelog** tab, rendered as [Markdown.][Markdown]

Here's an example of a `CHANGELOG.md` file.
As the example shows, you can add subsections.

```markdown
# 1.0.1

* Fixed missing exclamation mark in `sayHi()` method.

# 1.0.0

* **Breaking change:** Removed deprecated `sayHello()` method.
* Initial stable release.

## Upgrading from 0.1.x

Change all calls to `sayHello()` to instead be to `sayHi()`.

# 0.1.1

* Deprecated the `sayHello()` method; use `sayHi()` instead.

# 0.1.0

* Initial development release.
```


## Public directories

Two directories in your package are public to other packages: `lib` and
`bin`. You place [public libraries](#public-libraries) in `lib` and
[public tools](#public-tools) in `bin`.

### Public libraries

The following directory structure shows the `lib` portion of enchilada:

<FileTree>

- enchilada/
  - lib/
    - enchilada.dart
    - tortilla.dart

</FileTree>

Many [packages](/resources/glossary#package)
define 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, 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:

```dart
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:

<FileTree>

- enchilada/
  - lib/
    - some/
      - path/
        - olives.dart

</FileTree>

Users import `olives.dart` as follows:

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

Note that only *libraries* should be in `lib`.
*Entrypoints*—Dart scripts with a `main()` function—cannot
go in `lib`. If you place a Dart 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](/resources/glossary#entrypoint-directory).

:::note Tip for web apps
For the best performance when developing web apps,
put [implementation files](#implementation-files) under `/lib/src`,
instead of elsewhere under `/lib`.
Also, avoid imports of <code>package:<em>package_name</em>/src/...</code>.
:::

For more information on packages, see
[Creating packages](/tools/pub/create-packages).

### Data-driven fixes

<FileTree>

- enchilada/
  - lib/
    - fix_data.yaml

</FileTree>

If you update or deprecate APIs in your package,
you can provide automated migrations for your users
by placing a `fix_data.yaml` file in the `lib` directory.
When users run [`dart fix`](/tools/dart-fix) or use IDE quick fixes,
the Dart analyzer uses this file to automatically upgrade their code.

For details on writing and testing fixes, see
[Data-driven fixes](/tools/pub/data-driven-fixes).

### Public tools

Dart scripts placed inside of the `bin` directory are public. If you're
inside the directory of a package, you can use
[`dart run`](/tools/dart-run) to run scripts from the `bin`
directories of any other package the package depends on. From _any_
directory, you can [run scripts][]
from packages that you have activated using
[`dart pub global activate`][activate].

[run scripts]: /tools/pub/cmd/pub-global#running-a-script
[activate]: /tools/pub/cmd/pub-global#activating-a-package

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 don't intend for your package to be depended on, you can leave your
scripts in `bin`.


## Public assets

<FileTree>

- enchilada/
  - lib/
    - guacamole.css

</FileTree>

While most packages exist to let you reuse Dart code, you can also
reuse other kinds of content. For example, a package for
[Bootstrap](https://getbootstrap.com/) 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.


## Implementation files

<FileTree>

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

</FileTree>

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

How you import libraries from within your own package
depends on the locations of the libraries:

 * When [reaching inside or outside `lib/`][]
   (lint: [_avoid_relative_lib_imports_][]),
   use `package:`.
 * Otherwise, [prefer relative imports][].
 
 [reaching inside or outside `lib/`]: /effective-dart/usage#dont-allow-an-import-path-to-reach-into-or-out-of-lib
 [_avoid_relative_lib_imports_]: /tools/linter-rules/avoid_relative_lib_imports
 [prefer relative imports]: /effective-dart/usage#prefer-relative-import-paths

For example:

```dart title="lib/beans.dart"
// When importing from within lib:
import 'src/beans.dart';
```

```dart title="test/beans_test.dart"
// When importing from outside lib:
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](/tools/pub/pubspec).

## Web files

<FileTree>

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

</FileTree>

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

Put [library code](#public-libraries) under `lib`.
If the library isn't imported directly by code under `web`, or by
another package, put it under `lib/src`.
Put [web-based examples](#examples) under `example`. See
[Public assets](#public-assets) for tips on where to put assets,
such as images.

## Command-line apps

<FileTree>

- enchilada/
  - bin/
    - enchilada

</FileTree>

Some packages define programs that can be run directly from the command
line. These can be shell scripts or any other scripting language,
including 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
[`dart pub global`](/tools/pub/cmd/pub-global#running-a-script-from-your-path).

## Tests and benchmarks

<FileTree>

- enchilada/
  - test/
    - enchilada_test.dart
    - tortilla_test.dart

</FileTree>

Every package should have tests. With pub, the convention is
that most of 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](https://pub.dev/packages/test) package.

<FileTree>

- enchilada/
  - integration_test/
    - app_test.dart

</FileTree>

Flutter app packages might also have special integration tests, which use the
[integration_test](https://docs.flutter.dev/cookbook/testing/integration/introduction)
package. These tests live in their own `integration_test` directory.

Other packages might choose to follow a similar pattern, to separate their slower
integration tests from their unit tests, but note that by default `dart test`
will not run these tests. You will have to explicitly run them with
`dart test integration_test`.

<FileTree>

- enchilada/
  - benchmark/
    - make_lunch.dart

</FileTree>

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

<FileTree>

- enchilada/
  - test_fixes/
    - enchilada_fix.dart
    - enchilada_fix.dart.expect

</FileTree>

If your package provides [data-driven fixes][],
test them using paired Dart files and golden files
in a `test_fixes` directory.
Golden files contain the expected code after applying fixes.
To verify these tests,
run `dart fix --compare-to-golden`.
To learn how to configure and run the tests, see [Test your fixes][].

[data-driven fixes]: #data-driven-fixes
[Test your fixes]: /tools/pub/data-driven-fixes#test-your-fixes

## Documentation

<FileTree>

- enchilada/
  - doc/
    - api/
    - getting_started.md

</FileTree>

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

When you run the [`dart doc`](/tools/dart-doc)
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

<FileTree>

- enchilada/
  - example/
    - main.dart

</FileTree>

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

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

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

* <code>example/example[.md]</code>
* <code>example[/lib]/main.dart</code>
* <code>example[/lib]/<em>package_name</em>.dart</code>
* <code>example[/lib]/<em>package_name</em>_example.dart</code>
* <code>example[/lib]/example.dart</code>
* <code>example/README[.md]</code>

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

<FileTree>

- enchilada/
  - tool/
    - generate_docs.dart

</FileTree>

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

## Hooks

<FileTree>

- enchilada/
  - hook/
    - build.dart

</FileTree>

Packages can define hooks to be invoked by the Dart and Flutter SDK.
These hooks have a predefined CLI, and will be invoked by the SDK tools if present.

Because these hooks are invoked by the
`dart` and `flutter` tools on runs and builds, the dependencies
of these hooks must be normal dependencies and not `dev_dependencies`.

To learn more about how to define hooks, refer to the [build hooks][] documentation.

[build hooks]: /tools/hooks

## Skills

<FileTree>

- enchilada/
  - skills/
    - enchilada-cooking/
      - SKILL.md

</FileTree>

Packages can provide [AI agent skills][] to teach AI coding agents
how to use the package's APIs, architecture, and best practices.

Each skill lives in a subdirectory under `skills/`
and contains a `SKILL.md` file
following the [Agent Skills specification][agentskills].
To prevent naming collisions in consumer projects,
each skill subdirectory name must begin with the package name
(or the package name with underscores replaced by hyphens)
followed by a hyphen (such as `enchilada-cooking`).

When consumers depend on your package,
they can install and update your skills using the `package:skills` tool
(`dart run skills@ get`).

To learn how to author, test, and publish skills with your package,
see [Ship skills with packages][].

[AI agent skills]: /ai/package-skills
[Ship skills with packages]: /tools/pub/package-skills
[agentskills]: https://agentskills.io

## Project-specific caching for tools

:::note
Do not check the `.dart_tool/` directory into source control.
Instead, keep `.dart_tool/` in `.gitignore`.
:::

The `.dart_tool/` directory is created when you run `dart pub get`
and might be deleted at any time. Various tools use this directory
for caching files specific to your project and/or local machine.
The `.dart_tool/` directory should never be checked into
source control, or copied between machines.

It is also generally safe to delete the `.dart_tool/` directory,
though some tools might need recompute the cached information. 

**Example:** The [`dart pub get`](/tools/pub/cmd/pub-get) tool
will download and extract dependencies to a global `$PUB_CACHE` directory,
and then write a `.dart_tool/package_config.json` file mapping _package names_
to directories in the global `$PUB_CACHE` directory.
The `.dart_tool/package_config.json` file is used by other tools,
such as the analyzer and compilers when they need to resolve statements
such as `import 'package:foo/foo.dart'`.

When developing a tool that needs project-specific caching, 
you might consider using the `.dart_tool/` directory 
because most users already ignore it with `.gitignore`.
When caching files for your tool in a user's `.dart_tool/` directory,
you should use a unique subdirectory. To avoid collisions,
subdirectories of the form `.dart_tool/<tool_package_name>/`
are reserved for the package named `<tool_package_name>`.
If your tool isn't distributed through the [pub.dev site,](https://pub.dev)
you might consider publishing a placeholder package in order to 
reserve the unique name.

**Example:** [`package:build`](https://pub.dev/packages/build) provides a
framework for writing code generation steps.
When running these build steps, files are cached in `.dart_tool/build/`.
This helps speed-up future re-runs of the build steps.

:::warning
When developing a tool that wants to cache files in `.dart_tool/`,
ensure the following:
  
* You are using a subdirectory named after a package you own
  (`.dart_tool/<my_tool_package_name>/`)
* Your files don't belong under source control, 
  as `.dart_tool/` is generally listed in `.gitignore`
:::


[Markdown]: https://pub.dev/packages/markdown

