CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="Learn more about the directory structure used by Dart's package management tool, pub."><title>Package layout conventions | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Package layout conventions"><meta name="twitter:description" content="Learn more about the directory structure used by Dart's package management tool, pub."><meta property="og:title" content="Package layout conventions"><meta property="og:description" content="Learn more about the directory structure used by Dart's package management tool, pub."><meta property="og:url" content="/tools/pub/package-layout/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css"><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min.js" integrity="sha512-3gJwYpMe3QewGELv8k/BX9vcqhryRdzRMxVfq6ngyWXwo03GFEzjsUm8Q7RZcHPHksttq7/GFoxjCVUjkjvPdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha384-+sLIOodYLS7CIrQpBjl+C7nPvqq+FbNUBDunl/OZv93DB7Ln/533i8e/mZXLi/P+" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/3.0.5/js.cookie.min.js" integrity="sha512-nlp9/l96/EpjYBx7EP7pGASVXNe80hGhYAUrjeXnu/fyF5Py0/RXav4BBNs7n5Hx1WFhOEOWSAVjGeC3oKxDVQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="/assets/js/os-tabs.js"></script><script src="/assets/js/utilities.js"></script><script src="/assets/js/main.js"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html show_banner"><a id="skip" href="#site-content-title">Skip to main content</a><section id="cookie-notice"><div class="container"><p>dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. <a href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a>.</p><button id="cookie-consent" class="btn btn-primary">OK, got it</button></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle"><i class="material-symbols">menu</i></div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/guides" class="nav-link active"><span>Docs</span></a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header__search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div class="banner"><p class="banner__text">Announcing Dart 3.5 and an updated Dart roadmap! <a href="https://medium.com/dartlang/dart-3-5-6ca36259fa2f" target="_blank">Learn more</a></p></div><div id="sidenav"><form action="/search/" class="site-header__search form-inline"><input class="site-header__searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><div class="site-sidebar"><ul class="navbar-nav"><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/guides" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li></ul><ul class="nav flex-column"><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-1" role="button" aria-expanded="false" aria-controls="sidenav-1">Language</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1"><li class="nav-item"><a class="nav-link" href="/language">Introduction</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-2" href="#sidenav-1-2" role="button" aria-expanded="false" aria-controls="sidenav-1-2">Syntax basics</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables">Variables</a></li><li class="nav-item"><a class="nav-link" href="/language/operators">Operators</a></li><li class="nav-item"><a class="nav-link" href="/language/comments">Comments</a></li><li class="nav-item"><a class="nav-link" href="/language/metadata">Metadata</a></li><li class="nav-item"><a class="nav-link" href="/language/libraries">Libraries & imports</a></li><li class="nav-item"><a class="nav-link" href="/language/keywords">Keywords</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-3" href="#sidenav-1-3" role="button" aria-expanded="false" aria-controls="sidenav-1-3">Types</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types">Built-in types</a></li><li class="nav-item"><a class="nav-link" href="/language/records">Records</a></li><li class="nav-item"><a class="nav-link" href="/language/collections">Collections</a></li><li class="nav-item"><a class="nav-link" href="/language/generics">Generics</a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs">Typedefs</a></li><li class="nav-item"><a class="nav-link" href="/language/type-system">Type system</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-4" href="#sidenav-1-4" role="button" aria-expanded="false" aria-controls="sidenav-1-4">Patterns</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types">Pattern types</a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener">Applied tutorial</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions">Functions</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-6" href="#sidenav-1-6" role="button" aria-expanded="false" aria-controls="sidenav-1-6">Control flow</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops">Loops</a></li><li class="nav-item"><a class="nav-link" href="/language/branches">Branches</a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling">Error handling</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-7" href="#sidenav-1-7" role="button" aria-expanded="false" aria-controls="sidenav-1-7">Classes & objects</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes">Classes</a></li><li class="nav-item"><a class="nav-link" href="/language/constructors">Constructors</a></li><li class="nav-item"><a class="nav-link" href="/language/methods">Methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extend">Extend a class</a></li><li class="nav-item"><a class="nav-link" href="/language/mixins">Mixins</a></li><li class="nav-item"><a class="nav-link" href="/language/enums">Enums</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods">Extension methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types">Extension types</a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects">Callable objects</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-8" href="#sidenav-1-8" role="button" aria-expanded="false" aria-controls="sidenav-1-8">Class modifiers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis">Class modifiers for API maintainers</a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference">Reference</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-9" href="#sidenav-1-9" role="button" aria-expanded="false" aria-controls="sidenav-1-9">Concurrency</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency">Overview</a></li><li class="nav-item"><a class="nav-link" href="/language/async">Asynchronous support</a></li><li class="nav-item"><a class="nav-link" href="/language/isolates">Isolates</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-10" href="#sidenav-1-10" role="button" aria-expanded="false" aria-controls="sidenav-1-10">Null safety</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety">Sound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide">Migrating to null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety">Understanding null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety">Unsound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq">FAQ</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-2" role="button" aria-expanded="false" aria-controls="sidenav-2">Core libraries</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries">Overview</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core">dart:core</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async">dart:async</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math">dart:math</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert">dart:convert</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io">dart:io</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-html">dart:html</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables">Iterable collections</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-2-10" href="#sidenav-2-10" role="button" aria-expanded="false" aria-controls="sidenav-2-10">Asynchronous programming</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await">Tutorial</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling">Futures and error handling</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams">Using streams</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams">Creating streams</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-3" role="button" aria-expanded="false" aria-controls="sidenav-3">Effective Dart</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart">Overview</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style">Style</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation">Documentation</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design">Design</a></li></ul></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" href="#sidenav-4" role="button" aria-expanded="true" aria-controls="sidenav-4">Packages</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages">How to use packages</a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages">Commonly used packages</a></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/create-packages">Creating packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing">Publishing packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages">Writing package pages</a></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" data-target="#sidenav-4-6" href="#sidenav-4-6" role="button" aria-expanded="true" aria-controls="sidenav-4-6">Package reference</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-4-6"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies">Dependencies</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link active" href="/tools/pub/package-layout">Package layout conventions</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables">Pub environment variables</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec">Pubspec file</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot">Troubleshooting pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers">Verified publishers</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories">Security advisories</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning">Versioning</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories">Custom package repositories</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/private-files">What not to commit</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-5" role="button" aria-expanded="false" aria-controls="sidenav-5">Development</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5"><li class="nav-item"><a class="nav-link" href="/guides/json">JSON</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/numbers">Number representation</a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis">Google APIs</a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps">Multi-platform apps</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-5" href="#sidenav-5-5" role="button" aria-expanded="false" aria-controls="sidenav-5-5">Command-line & server apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline">Write command-line apps</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data">Fetch data from the internet</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver">Write HTTP servers</a></li><li class="nav-item"><a class="nav-link" href="/server/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud">Google Cloud</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-6" href="#sidenav-5-6" role="button" aria-expanded="false" aria-controls="sidenav-5-6">Web apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web">Overview</a></li><li class="nav-item"><a class="nav-link" href="/web/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/web/deployment">Deployment</a></li><li class="nav-item"><a class="nav-link" href="/web/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/web/wasm">Wasm compilation</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/environment-declarations">Environment declarations</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-6" role="button" aria-expanded="false" aria-controls="sidenav-6">Interoperability</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop">C interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop">Objective-C & Swift interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop">Java & Kotlin interop</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-6-4" href="#sidenav-6-4" role="button" aria-expanded="false" aria-controls="sidenav-6-4">JavaScript interop</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop">Overview</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types">JS types</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials">Tutorials</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop">Past JS interop</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web">Web interop</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-7" role="button" aria-expanded="false" aria-controls="sidenav-7">Tools & techniques</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools">Overview</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2" href="#sidenav-7-2" role="button" aria-expanded="false" aria-controls="sidenav-7-2">Editors & debuggers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin">IntelliJ & Android Studio</a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code">VS Code</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools">Dart DevTools</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2-4" href="#sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="sidenav-7-2-4">DartPad</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot">Troubleshooting DartPad</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-3" href="#sidenav-7-3" role="button" aria-expanded="false" aria-controls="sidenav-7-3">Command-line tools</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-3"><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-1" href="#sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="sidenav-7-3-1">Dart SDK</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool">dart</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze">dart analyze</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile">dart compile</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create">dart create</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc">dart doc</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix">dart fix</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format">dart format</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info">dart info</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd">dart pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run">dart run</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test">dart test</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime">dartaotruntime</a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags">Experiment flags</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-2" href="#sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="sidenav-7-3-2">Other command-line tools</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner">build_runner</a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev">webdev</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-4" href="#sidenav-7-4" role="button" aria-expanded="false" aria-controls="sidenav-7-4">Static analysis</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis">Customizing static analysis</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/sound-problems">Fixing common type problems</a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons">Fixing type promotion failures</a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules">Linter rules</a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages">Diagnostic messages</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-5" href="#sidenav-7-5" role="button" aria-expanded="false" aria-controls="sidenav-7-5">Testing & optimization</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/guides/testing">Testing</a></li><li class="nav-item"><a class="nav-link" href="/web/debugging">Debugging web apps</a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-9" role="button" aria-expanded="false" aria-controls="sidenav-9">Resources</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet">Language cheatsheet</a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes">Breaking changes</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/evolution">Language evolution</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/spec">Language specification</a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration">Dart 3 migration guide</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-9-6" href="#sidenav-9-6" role="button" aria-expanded="false" aria-controls="sidenav-9-6">Coming from ...</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart">JavaScript to Dart</a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart">Swift to Dart</a></li></ul></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq">FAQ</a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/resources/books">Books</a></li><li class="nav-item"><a class="nav-link" href="/resources/videos">Videos</a></li><li class="nav-item"><a class="nav-link" href="/tutorials">Tutorials</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" href="#sidenav-10" role="button" aria-expanded="true" aria-controls="sidenav-10">Related sites</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener">API reference</a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener">Blog</a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener">DartPad (online editor)</a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener">Flutter</a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener">Package site</a></li></ul></li></ul></div></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#the-pubspec">The pubspec</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#license">LICENSE</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#readme-md">README.md</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#changelog">CHANGELOG.md</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#public-directories">Public directories</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#public-libraries">Public libraries</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#public-tools">Public tools</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#public-assets">Public assets</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#implementation-files">Implementation files</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#web-files">Web files</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#command-line-apps">Command-line apps</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#tests-and-benchmarks">Tests and benchmarks</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#documentation">Documentation</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#examples">Examples</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#internal-tools-and-scripts">Internal tools and scripts</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#hooks">Hooks</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#project-specific-caching-for-tools">Project-specific caching for tools</a></li></ul></div><article><div class="content"><div id="site-content-title"><h1>Package layout conventions</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents <span class="site-toc--inline__toggle toc-toggle-down"><i class="material-symbols">keyboard_arrow_down</i></span> <span class="site-toc--inline__toggle toc-toggle-up"><i class="material-symbols">keyboard_arrow_up</i></span></header><ul class="section-nav"><li class="toc-entry"><a href="#the-pubspec">The pubspec</a></li><li class="toc-entry"><a href="#license">LICENSE</a></li><li class="toc-entry"><a href="#readme-md">README.md</a></li><li class="toc-entry"><a href="#changelog">CHANGELOG.md</a></li><li class="toc-entry"><a href="#public-directories">Public directories</a><ul><li class="toc-entry"><a href="#public-libraries">Public libraries</a></li><li class="toc-entry"><a href="#public-tools">Public tools</a></li></ul></li><li class="toc-entry"><a href="#public-assets">Public assets</a></li><li class="toc-entry"><a href="#implementation-files">Implementation files</a></li><li class="toc-entry"><a href="#web-files">Web files</a></li><li class="toc-entry"><a href="#command-line-apps">Command-line apps</a></li><li class="toc-entry"><a href="#tests-and-benchmarks">Tests and benchmarks</a></li><li class="toc-entry"><a href="#documentation">Documentation</a></li><li class="toc-entry"><a href="#examples">Examples</a></li><li class="toc-entry"><a href="#internal-tools-and-scripts">Internal tools and scripts</a></li><li class="toc-entry"><a href="#hooks">Hooks</a></li><li class="toc-entry"><a href="#project-specific-caching-for-tools">Project-specific caching for tools</a></li></ul><span class="site-toc--inline__toggle toc-toggle-more-items"><i class="material-symbols">more_horiz</i></span></div><p>When you build a <a href="/tools/pub/packages">pub package</a>, 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.</p><aside class="alert alert-info"><div class="alert-header"><i class="material-symbols" aria-hidden="true">flutter</i> <span>Flutter note</span></div><div class="alert-content"><p>Flutter apps can use custom directories for their assets. For details, see <a href="https://docs.flutter.dev/development/ui/assets-and-images">Adding assets and images</a> on the <a href="https://docs.flutter.dev">Flutter website.</a></p></div></aside><p>Here's what a complete package (named <code>enchilada</code>) that uses every corner of these guidelines might look like:</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> .dart_tool/ *</span></span> <span class="line"><span> pubspec.yaml</span></span> <span class="line"><span> pubspec.lock **</span></span> <span class="line"><span> LICENSE</span></span> <span class="line"><span> README.md</span></span> <span class="line"><span> CHANGELOG.md</span></span> <span class="line"><span> benchmark/</span></span> <span class="line"><span> make_lunch.dart</span></span> <span class="line"><span> bin/</span></span> <span class="line"><span> enchilada</span></span> <span class="line"><span> doc/</span></span> <span class="line"><span> api/ ***</span></span> <span class="line"><span> getting_started.md</span></span> <span class="line"><span> example/</span></span> <span class="line"><span> main.dart</span></span> <span class="line"><span> hook/</span></span> <span class="line"><span> build.dart</span></span> <span class="line"><span> integration_test/</span></span> <span class="line"><span> app_test.dart</span></span> <span class="line"><span> lib/</span></span> <span class="line"><span> enchilada.dart</span></span> <span class="line"><span> tortilla.dart</span></span> <span class="line"><span> guacamole.css</span></span> <span class="line"><span> src/</span></span> <span class="line"><span> beans.dart</span></span> <span class="line"><span> queso.dart</span></span> <span class="line"><span> test/</span></span> <span class="line"><span> enchilada_test.dart</span></span> <span class="line"><span> tortilla_test.dart</span></span> <span class="line"><span> tool/</span></span> <span class="line"><span> generate_docs.dart</span></span> <span class="line"><span> web/</span></span> <span class="line"><span> index.html</span></span> <span class="line"><span> main.dart</span></span> <span class="line"><span> style.css</span></span></code></pre></div></div><p>* The <code>.dart_tool/</code> directory exists after you've run <code>dart pub get</code>. Don't check it into source control. To learn more, see <a href="#project-specific-caching-for-tools">Project specific caching for tools</a>.</p><p>** The <code>pubspec.lock</code> file exists after you've run <code>dart pub get</code>. Leave it out of source control unless your package is an <a href="/tools/pub/glossary#application-package">application package</a>.</p><p>*** The <code>doc/api</code> directory exists locally after you've run <a href="/tools/dart-doc"><code>dart doc</code></a>. Don't check the <code>api</code> directory into source control.</p><div class="header-wrapper"><h2 id="the-pubspec">The pubspec</h2><a class="heading-link" href="#the-pubspec" aria-label="Link to 'The pubspec' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> pubspec.yaml</span></span> <span class="line"><span> pubspec.lock</span></span></code></pre></div></div><p>Every package has a <a href="/tools/pub/pubspec"><em>pubspec</em></a>, a file named <code>pubspec.yaml</code>, in the root directory of the package. That's what <em>makes</em> it a package.</p><p>Running <a href="/tools/pub/cmd/pub-get"><code>dart pub get</code></a>, <a href="/tools/pub/cmd/pub-upgrade"><code>dart pub upgrade</code></a>, or <a href="/tools/pub/cmd/pub-downgrade"><code>dart pub downgrade</code></a> on the package creates a <strong>lockfile</strong>, named <code>pubspec.lock</code>. If your package is an <a href="/tools/pub/glossary#application-package">application package</a>, check the lockfile into source control. Otherwise, don't.</p><p>For more information, see the <a href="/tools/pub/pubspec">pubspec page</a>.</p><div class="header-wrapper"><h2 id="license">LICENSE</h2><a class="heading-link" href="#license" aria-label="Link to 'LICENSE' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> LICENSE</span></span></code></pre></div></div><p>If you're publishing your package, include a license file named <code>LICENSE</code>. We recommend using an <a href="https://opensource.org/licenses">OSI-approved license</a> such as <a href="https://opensource.org/licenses/BSD-3-Clause">BSD-3-Clause,</a> so that others can reuse your work.</p><div class="header-wrapper"><h2 id="readme-md">README.md</h2><a class="heading-link" href="#readme-md" aria-label="Link to 'README.md' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> README.md</span></span></code></pre></div></div><p>One file that's very common in open source is a <em>README</em> file that describes the project. This is especially important in pub. When you upload to the <a href="https://pub.dev">pub.dev site,</a> your <code>README.md</code> file is shown鈥攔endered as <a href="https://pub.dev/packages/markdown">Markdown</a>鈥攐n the page for your package. This is the perfect place to introduce people to your code.</p><p>For guidance on how to write a great README, see <a href="/tools/pub/writing-package-pages">Writing package pages</a>.</p><p><a id="changelogmd"></a></p><div class="header-wrapper"><h2 id="changelog">CHANGELOG.md</h2><a class="heading-link" href="#changelog" aria-label="Link to 'CHANGELOG.md' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> CHANGELOG.md</span></span></code></pre></div></div><p>Include a <code>CHANGELOG.md</code> 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.</p><p>To support tools that parse <code>CHANGELOG.md</code>, use the following format:</p><ul><li>Each version has its own section with a heading.</li><li>The version headings are either all level 1 or all level 2.</li><li>The version heading text contains a package version number, optionally prefixed with "v".</li></ul><p>When you upload your package to the <a href="https://pub.dev">pub.dev site,</a> your package's <code>CHANGELOG.md</code> file (if any) appears in the <strong>Changelog</strong> tab, rendered as <a href="https://pub.dev/packages/markdown">Markdown.</a></p><p>Here's an example of a <code>CHANGELOG.md</code> file. As the example shows, you can add subsections.</p><div class="code-block-wrapper language-markdown"><div class="code-block-body"><span class="code-block-language" title="Language markdown">markdown</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#222222;font-weight:bold"># 1.0.1</span></span> <span class="line"></span> <span class="line"><span style="color:#222222">* Fixed missing exclamation mark in </span><span style="color:#222222">`sayHi()`</span><span style="color:#222222"> method.</span></span> <span class="line"></span> <span class="line"><span style="color:#222222;font-weight:bold"># 1.0.0</span></span> <span class="line"></span> <span class="line"><span style="color:#222222">* </span><span style="color:#222222;font-weight:bold">**Breaking change:**</span><span style="color:#222222"> Removed deprecated </span><span style="color:#222222">`sayHello()`</span><span style="color:#222222"> method.</span></span> <span class="line"><span style="color:#222222">* Initial stable release.</span></span> <span class="line"></span> <span class="line"><span style="color:#222222;font-weight:bold">## Upgrading from 0.1.x</span></span> <span class="line"></span> <span class="line"><span style="color:#222222">Change all calls to </span><span style="color:#222222">`sayHello()`</span><span style="color:#222222"> to instead be to </span><span style="color:#222222">`sayHi()`</span><span style="color:#222222">.</span></span> <span class="line"></span> <span class="line"><span style="color:#222222;font-weight:bold"># 0.1.1</span></span> <span class="line"></span> <span class="line"><span style="color:#222222">* Deprecated the </span><span style="color:#222222">`sayHello()`</span><span style="color:#222222"> method; use </span><span style="color:#222222">`sayHi()`</span><span style="color:#222222"> instead.</span></span> <span class="line"></span> <span class="line"><span style="color:#222222;font-weight:bold"># 0.1.0</span></span> <span class="line"></span> <span class="line"><span style="color:#222222">* Initial development release.</span></span></code></pre></div></div><div class="header-wrapper"><h2 id="public-directories">Public directories</h2><a class="heading-link" href="#public-directories" aria-label="Link to 'Public directories' section">#</a></div><p>Two directories in your package are public to other packages: <code>lib</code> and <code>bin</code>. You place <a href="#public-libraries">public libraries</a> in <code>lib</code> and <a href="#public-tools">public tools</a> in <code>bin</code>.</p><div class="header-wrapper"><h3 id="public-libraries">Public libraries</h3><a class="heading-link" href="#public-libraries" aria-label="Link to 'Public libraries' section">#</a></div><p>The following directory structure shows the <code>lib</code> portion of enchilada:</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> lib/</span></span> <span class="line"><span> enchilada.dart</span></span> <span class="line"><span> tortilla.dart</span></span></code></pre></div></div><p>Many <a href="/tools/pub/glossary#package">packages</a> define Dart libraries that other packages can import and use. These public Dart library files go inside a directory called <code>lib</code>.</p><p>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 <code>enchilada.dart</code> in the example here. But you can also define other libraries with whatever names make sense for your package.</p><p>When you do, users can import these libraries using the name of the package and the library file, like so:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:enchilada/enchilada.dart'</span><span style="color:#222222">;</span></span> <span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:enchilada/tortilla.dart'</span><span style="color:#222222">;</span></span></code></pre></div></div><p>If you want to organize your public libraries, you can also create subdirectories inside <code>lib</code>. If you do that, users will specify that path when they import it. Say you have the following file hierarchy:</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> lib/</span></span> <span class="line"><span> some/</span></span> <span class="line"><span> path/</span></span> <span class="line"><span> olives.dart</span></span></code></pre></div></div><p>Users import <code>olives.dart</code> as follows:</p><div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:enchilada/some/path/olives.dart'</span><span style="color:#222222">;</span></span></code></pre></div></div><p>Note that only <em>libraries</em> should be in <code>lib</code>. <em>Entrypoints</em>鈥擠art scripts with a <code>main()</code> function鈥攃annot go in <code>lib</code>. If you place a Dart script inside <code>lib</code>, you will discover that any <code>package:</code> imports it contains don't resolve. Instead, your entrypoints should go in the appropriate <a href="/tools/pub/glossary#entrypoint-directory">entrypoint directory</a>.</p><aside class="alert alert-info"><div class="alert-header"><i class="material-symbols" aria-hidden="true">info</i> <span>Tip for web apps</span></div><div class="alert-content"><p>For the best performance when developing web apps, put <a href="#implementation-files">implementation files</a> under <code>/lib/src</code>, instead of elsewhere under <code>/lib</code>. Also, avoid imports of <code>package:<em>package_name</em>/src/...</code>.</p></div></aside><p>For more information on packages, see <a href="/guides/libraries/create-packages">Creating packages</a>.</p><div class="header-wrapper"><h3 id="public-tools">Public tools</h3><a class="heading-link" href="#public-tools" aria-label="Link to 'Public tools' section">#</a></div><p>Dart scripts placed inside of the <code>bin</code> directory are public. If you're inside the directory of a package, you can use <a href="/tools/dart-run"><code>dart run</code></a> to run scripts from the <code>bin</code> directories of any other package the package depends on. From <em>any</em> directory, you can <a href="/tools/pub/cmd/pub-global#running-a-script">run scripts</a> from packages that you have activated using <a href="/tools/pub/cmd/pub-global#activating-a-package"><code>dart pub global activate</code></a>.</p><p>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 <code>tool</code> directory. If you don't intend for your package to be depended on, you can leave your scripts in <code>bin</code>.</p><div class="header-wrapper"><h2 id="public-assets">Public assets</h2><a class="heading-link" href="#public-assets" aria-label="Link to 'Public assets' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> lib/</span></span> <span class="line"><span> guacamole.css</span></span></code></pre></div></div><p>While most packages exist to let you reuse Dart code, you can also reuse other kinds of content. For example, a package for <a href="https://getbootstrap.com/">Bootstrap</a> might include a number of CSS files for consumers of the package to use.</p><p>These go in the top-level <code>lib</code> directory. You can put any kind of file in there and organize it with subdirectories however you like.</p><div class="header-wrapper"><h2 id="implementation-files">Implementation files</h2><a class="heading-link" href="#implementation-files" aria-label="Link to 'Implementation files' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> lib/</span></span> <span class="line"><span> src/</span></span> <span class="line"><span> beans.dart</span></span> <span class="line"><span> queso.dart</span></span></code></pre></div></div><p>The libraries inside <code>lib</code> 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 <code>lib</code> called <code>src</code>. You can create subdirectories in there if it helps you organize things.</p><p>You are free to import libraries that live in <code>lib/src</code> from within other Dart code in the <em>same</em> package (like other libraries in <code>lib</code>, scripts in <code>bin</code>, and tests) but you should never import from another package's <code>lib/src</code> directory. Those files are not part of the package's public API, and they might change in ways that could break your code.</p><p>How you import libraries from within your own package depends on the locations of the libraries:</p><ul><li>When <a href="/effective-dart/usage#dont-allow-an-import-path-to-reach-into-or-out-of-lib">reaching inside or outside <code>lib/</code></a> (lint: <a href="/tools/linter-rules/avoid_relative_lib_imports"><em>avoid_relative_lib_imports</em></a>), use <code>package:</code>.</li><li>Otherwise, <a href="/effective-dart/usage#prefer-relative-import-paths">prefer relative imports</a>.</li></ul><p>For example:</p><div class="code-block-wrapper language-dart"><div class="code-block-header">lib/beans.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// When importing from within lib:</span></span> <span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'src/beans.dart'</span><span style="color:#222222">;</span></span></code></pre></div></div><div class="code-block-wrapper language-dart"><div class="code-block-header">test/beans_test.dart</div><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// When importing from outside lib:</span></span> <span class="line"><span style="color:#D43324">import</span><span style="color:#11796D"> 'package:enchilada/src/beans.dart'</span><span style="color:#222222">;</span></span></code></pre></div></div><p>The name you use here (in this case <code>enchilada</code>) is the name you specify for your package in its <a href="/tools/pub/pubspec">pubspec</a>.</p><div class="header-wrapper"><h2 id="web-files">Web files</h2><a class="heading-link" href="#web-files" aria-label="Link to 'Web files' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> web/</span></span> <span class="line"><span> index.html</span></span> <span class="line"><span> main.dart</span></span> <span class="line"><span> style.css</span></span></code></pre></div></div><p>For web packages, place entrypoint code鈥擠art scripts that include <code>main()</code> and supporting files, such as CSS or HTML鈥攗nder <code>web</code>. You can organize the <code>web</code> directory into subdirectories if you like.</p><p>Put <a href="#public-libraries">library code</a> under <code>lib</code>. If the library isn't imported directly by code under <code>web</code>, or by another package, put it under <code>lib/src</code>. Put <a href="#examples">web-based examples</a> under <code>example</code>. See <a href="#public-assets">Public assets</a> for tips on where to put assets, such as images.</p><div class="header-wrapper"><h2 id="command-line-apps">Command-line apps</h2><a class="heading-link" href="#command-line-apps" aria-label="Link to 'Command-line apps' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> bin/</span></span> <span class="line"><span> enchilada</span></span></code></pre></div></div><p>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.</p><p>If your package defines code like this, put it in a directory named <code>bin</code>. You can run that script from anywhere on the command line, if you set it up using <a href="/tools/pub/cmd/pub-global#running-a-script-from-your-path"><code>dart pub global</code></a>.</p><div class="header-wrapper"><h2 id="tests-and-benchmarks">Tests and benchmarks</h2><a class="heading-link" href="#tests-and-benchmarks" aria-label="Link to 'Tests and benchmarks' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> test/</span></span> <span class="line"><span> enchilada_test.dart</span></span> <span class="line"><span> tortilla_test.dart</span></span></code></pre></div></div><p>Every package should have tests. With pub, the convention is that most of these go in a <code>test</code> directory (or some directory inside it if you like) and have <code>_test</code> at the end of their file names.</p><p>Typically, these use the <a href="https://pub.dev/packages/test">test</a> package.</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> integration_test/</span></span> <span class="line"><span> app_test.dart</span></span></code></pre></div></div><p>Flutter app packages may also have special integration tests, which use the <a href="https://docs.flutter.dev/cookbook/testing/integration/introduction">integration_test</a> package. These tests live in their own <code>integration_test</code> directory.</p><p>Other packages may choose to follow a similar pattern, to separate their slower integration tests from their unit tests, but note that by default <code>dart test</code> will not run these tests. You will have to explicitly run them with <code>dart test integration_test</code>.</p><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> benchmark/</span></span> <span class="line"><span> make_lunch.dart</span></span></code></pre></div></div><p>Packages that have performance critical code may also include <em>benchmarks</em>. These test the API not for correctness but for speed (or memory use, or maybe other empirical metrics).</p><div class="header-wrapper"><h2 id="documentation">Documentation</h2><a class="heading-link" href="#documentation" aria-label="Link to 'Documentation' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> doc/</span></span> <span class="line"><span> api/</span></span> <span class="line"><span> getting_started.md</span></span></code></pre></div></div><p>If you have code and tests, the next piece you might want is good documentation. That goes inside a directory named <code>doc</code>.</p><p>When you run the <a href="/tools/dart-doc"><code>dart doc</code></a> tool, it places the API documentation, by default, under <code>doc/api</code>. Since the API documentation is generated from the source code, you should not place it under source control.</p><p>Other than the generated <code>api</code>, we don't have any guidelines about format or organization of the documentation that you author. Use whatever markup format that you prefer.</p><div class="header-wrapper"><h2 id="examples">Examples</h2><a class="heading-link" href="#examples" aria-label="Link to 'Examples' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> example/</span></span> <span class="line"><span> main.dart</span></span></code></pre></div></div><p>Code, tests, docs, what else could your users want? Standalone example programs that use your package, of course! Those go inside the <code>example</code> 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 <code>example</code>.</p><p>In your examples, use <code>package:</code> 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.</p><p>If you might publish your package, consider creating an example file with one of the following names:</p><ul><li><code>example/example[.md]</code></li><li><code>example[/lib]/main.dart</code></li><li><code>example[/lib]/<em>package_name</em>.dart</code></li><li><code>example[/lib]/<em>package_name</em>_example.dart</code></li><li><code>example[/lib]/example.dart</code></li><li><code>example/README[.md]</code></li></ul><p>When you publish a package that contains one or more of the above files, the pub.dev site creates an <strong>Example</strong> 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 <code>example</code> directory, including a file named <code>README.md</code>, then your package's Example tab displays the contents of <code>example/README.md</code> (parsed as <a href="https://pub.dev/packages/markdown">Markdown.)</a></p><div class="header-wrapper"><h2 id="internal-tools-and-scripts">Internal tools and scripts</h2><a class="heading-link" href="#internal-tools-and-scripts" aria-label="Link to 'Internal tools and scripts' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> tool/</span></span> <span class="line"><span> generate_docs.dart</span></span></code></pre></div></div><p>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.</p><p>Unlike the scripts in <code>bin</code>, these are <em>not</em> for external users of the package. If you have any of these, place them in a directory called <code>tool</code>.</p><div class="header-wrapper"><h2 id="hooks">Hooks</h2><a class="heading-link" href="#hooks" aria-label="Link to 'Hooks' section">#</a></div><div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span>enchilada/</span></span> <span class="line"><span> hook/</span></span> <span class="line"><span> build.dart</span></span></code></pre></div></div><p>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.</p><p>Because these hooks are invoked by the <code>dart</code> and <code>flutter</code> tools on runs and builds, the dependencies of these hooks must be normal dependencies and not <code>dev_dependencies</code>.</p><aside class="alert alert-info"><div class="alert-header"><i class="material-symbols" aria-hidden="true">info</i> <span>Note</span></div><div class="alert-content"><p>Hook support is <strong>experimental</strong> and in active development.</p><p>To learn more about how to define hooks and their current status, refer to the <a href="https://github.com/dart-lang/native/blob/main/pkgs/native_assets_cli/README.md"><code>build.dart</code> hook documentation</a>.</p></div></aside><div class="header-wrapper"><h2 id="project-specific-caching-for-tools">Project-specific caching for tools</h2><a class="heading-link" href="#project-specific-caching-for-tools" aria-label="Link to 'Project-specific caching for tools' section">#</a></div><aside class="alert alert-info"><div class="alert-header"><i class="material-symbols" aria-hidden="true">info</i> <span>Note</span></div><div class="alert-content"><p>Do not check the <code>.dart_tool/</code> directory into source control. Instead, keep <code>.dart_tool/</code> in <code>.gitignore</code>.</p></div></aside><p>The <code>.dart_tool/</code> directory is created when you run <code>dart pub get</code> and might be deleted at any time. Various tools use this directory for caching files specific to your project and/or local machine. The <code>.dart_tool/</code> directory should never be checked into source control, or copied between machines.</p><p>It is also generally safe to delete the <code>.dart_tool/</code> directory, though some tools might need recompute the cached information.</p><p><strong>Example:</strong> The <a href="/tools/pub/cmd/pub-get"><code>dart pub get</code></a> tool will download and extract dependencies to a global <code>$PUB_CACHE</code> directory, and then write a <code>.dart_tool/package_config.json</code> file mapping <em>package names</em> to directories in the global <code>$PUB_CACHE</code> directory. The <code>.dart_tool/package_config.json</code> file is used by other tools, such as the analyzer and compilers when they need to resolve statements such as <code>import 'package:foo/foo.dart'</code>.</p><p>When developing a tool that needs project-specific caching, you might consider using the <code>.dart_tool/</code> directory because most users already ignore it with <code>.gitignore</code>. When caching files for your tool in a user's <code>.dart_tool/</code> directory, you should use a unique subdirectory. To avoid collisions, subdirectories of the form <code>.dart_tool/<tool_package_name>/</code> are reserved for the package named <code><tool_package_name></code>. If your tool isn't distributed through the <a href="https://pub.dev">pub.dev site,</a> you might consider publishing a placeholder package in order to reserve the unique name.</p><p><strong>Example:</strong> <a href="https://pub.dev/packages/build"><code>package:build</code></a> provides a framework for writing code generation steps. When running these build steps, files are cached in <code>.dart_tool/build/</code>. This helps speed-up future re-runs of the build steps.</p><aside class="alert alert-warning"><div class="alert-header"><i class="material-symbols" aria-hidden="true">warning</i> <span>Warning</span></div><div class="alert-content"><p>When developing a tool that wants to cache files in <code>.dart_tool/</code>, ensure the following:</p><ul><li>You are using a subdirectory named after a package you own (<code>.dart_tool/<my_tool_package_name>/</code>)</li><li>Your files don't belong under source control, as <code>.dart_tool/</code> is generally listed in <code>.gitignore</code></li></ul></div></aside><p id="page-github-links"><span>Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-11-18.</span> <a href="https://github.com/dart-lang/site-www/tree/main/src/content/tools/pub/package-layout.md" target="_blank" rel="noopener">View source</a> <span>or </span><a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/tools/pub/package-layout/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/tools/pub/package-layout.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</p></div></article></main><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Medium blog"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="GitHub"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="X (Twitter)"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></body></html>