All Dart projects that are meant to be used in a production environment should follow best software engineering practices and hence, must contain a particular structure of folders. A well-structured project breathes professionalism and gives developers a sense of recognition; it is much easier to find your way in a standardized structure. Moreover, it is also necessary if you want to use a bunch of application-specific libraries in your app, as we will see in the next recipe.
An app that is meant to run on its own, either as a command-line application or a web application, is an application package; it needs a main() entry point. A library package will be used as a dependency in other apps. All Dart projects depend on the configuration file pubspec.yaml, which describes the app and its dependencies, together with the pubspec.lock file. This dictates which libraries will be contained in the top-level packages folder. This file and the packages folder are generated by the pub tool (more specifically, the pub get and pub upgrade commands) and should not be edited.
If you develop an application in Dart Editor when starting up a new project, you will need to choose a project template to begin with, as shown in the following table:
|
Project type |
Template |
Project folder |
|---|---|---|
|
Client or server app to be run standalone |
Command line |
|
|
Web or Polymer app |
Web application or web application using Polymer, or project |
|
|
Chrome app |
Chrome-packaged application |
|
|
Library |
Package |
|
The bin folder contains a startup script with a main() function. It can also contain shell scripts, for example, a script to start a server. In the web folder, you will typically have index.html and a main.dart file, or in general, the app.html and app.dart files. Other resource files such as CSS, JavaScript files, and images can be contained in their own folders css, js, and images. A Polymer project will typically contain a webcomponent subfolder. Don't place any scripts with main() in a lib folder.
Then, you will want to enhance the structure of the project as follows:
|
Folder |
Project type |
Files |
|---|---|---|
|
|
All |
|
|
|
All |
|
|
|
All |
Example scripts showing how to use the app |
|
|
Web |
Folders for |
|
|
Server |
Folders for |
|
|
All |
Unit test scripts |
The templates from Dart Editor provide you with a basic structure, but usually you'll want to add some folders as specified previously to provide a recognizable and professional structure where you can easily find what you want to look at, for example, which tests are included with the project. As we will see in the next recipe, in order to use application libraries, they have to be placed in the lib folder.
The README file (readme.md, which is in the markdown syntax; refer to http://en.wikipedia.org/wiki/Markdown) and the CHANGELOG file are shown in the pub repository on the page of your package, so their content is important.
Optional folders are as follows:
mock: This contains classes to simulate certain behaviors of your app in testing environments, for example, a text file instead of a real databasetool: This contains tooling scripts needed in the project such as a build script, test runners, and so onbenchmark: When the performance is critical, this folder can contain examples to test it
An alternative structure for an app with both client and server components can be placed on top of the previous structure:
clientservercore(orshared)
The https://www.dartlang.org/tools/pub/package-layout.html link on the Dart site contains some additional information.