Packages have become very important in the development world. With npm, pip and RubyGems, they have become essential in the life of programmers. Packages help us develop more complex solutions in a shorter amount of time and also help us become known as developers by the packages we create.
Dart is a language that is gaining popularity thanks to mobile development with Flutter. Dart offers us a package manager:
pub, and the opportunity to contribute to the community by creating our package.
Here, I am going to explain what packages are in Dart, their structure, and how to publish one getting the maximum score in the system that
pub has to rate all packages.
Dart also has a package manager with which you can load Dart packages developed by the community. Similarly, there are different packages for all uses given to the language.
All packages are open source, so anyone can contribute to existing ones or create a new one. We can find all packages at https://pub.dev/.
According to the functionalities to be carried out, we can have two types of packages:
Dart packages: These are packages written entirely in Dart and depending on the dependencies they can work only for Flutter or for any use of the language.
If you look for any package you can see that they all have elements in common, such as the Readme, the Changelog, the example, the installation method, the versions and the scores.
Within the scores, what matters most to us at first are the pub points. These points are given automatically according to your package, its elements and its code. They comply with certain parameters. The highest score is 110 and in this tutorial, we are going to see how to create a Dart package, how to reach the maximum points and the whole process of uploading the package.
There are two ways to create all the initial files for your package:
Manually create the necessary folders and files according to the package structure, which you can find in the following documentation: https://dart.dev/guides/libraries/create-library-packages
Use Flutter to create a template of an empty package. Of course, to perform this, you need to have Flutter installed. You can follow the
Developing Dart packages section to create the template with Flutter from the following documentation: https://flutter.dev/docs/development/packages-and-plugins/developing-packages#dart
In this tutorial, I have used the second option, because it is faster and I am going to show an example of a developer package to use with Flutter.
The following files and directories are the main ones that we can find in a Dart package:
lib: It is the folder where all the functionalities of our package go.
pubspect.yaml: Inside this file is placed essential information about our package: name, version, author, repository URL, etc. Filling in these fields gives us more pub points. In addition, all the dependencies (packages) that our package will use are placed here. Keeping all these dependencies updated also gives us pub points.
example: It is the Dart script or Flutter project that will help us to test our package and give the community an example of how to use the package.
test: Here are all the tests of our package. It is very important to run tests to have a good continuous integration in the future when other people contribute to our package. I am not going to delve into this part too much because the tests do not influence the pub points.
README.md: Present in all open source repositories. This file explains what it is, how to use it, and what the benefits are of using our package.
CHANGELOG.md: This file shows us the update history and the changes in each of the updates. This file is important, as having it adds pub points to our package. In addition, this file is widely used by developers when it comes to seeing updates or managing the versions of their dependencies.
LICENSE: The license that the package will have is placed here. It is very important that all open source software is licensed. It is recommended not to leave this file blank.
After having the initial structure of our package, the following is the hardest thing to do: Develop it!
And this part is totally yours. Some recommendations:
That the names of all variables and functions are understandable.
Follow a good language style as much as you can: https://dart.dev/guides/language/effective-dart/style
Have all your functions well documented. This is very important as it influences your pub points: https://dart.dev/guides/language/effective-dart/documentation
For this tutorial, I have chosen one of my packages paulonia_cache_image. I have added new functionality and fixed a few bugs.
After you finish developing your package and it is ready to be used, first verify how many pub points the package would have if it was uploaded as-is at this moment. Fortunately, the tool used to rate the packages when uploading them is open source and we can use it to verify our score before uploading our package. I’m talking about [pana] (https://pub.dev/packages/pana).
To install it with Flutter use:
> flutter pub global activate pana
It is advisable to make a copy of the package since
pana adds some files after the evaluation, which we surely do not want to be uploaded to our repository. Then we can run the command:
> flutter pub global run pana paulonia_cache_image_copy
pana generates a report of the analysis of our package and tells us how many points our package would have.
As you can see in the image, the new version of my package does not reach the maximum pub points. We go to the beginning of the report and look section by section to see the points we have and the points we are missing.
Provide a valid
pubspec.yaml: This refers to filling in the basic information of the application: the name, the description, the version, the homepage, and the link of the repository.
Provide a valid
README.md: This refers to not having an empty Readme or having the basic Readme that is generated when creating the package.
Provide a valid
CHANGELOG.md: Like the Readme, this refers to not having an empty Changelog.
Package has an example: This refers to having the example developed.
20% or more of the public API has dartdoc comments: This refers to the code being documented. This part does not appear in the
pana report, but as long as all the functions of the package are documented, these points can be reached.
Support multiple platforms: This refers to the number of platforms that the package supports. To have all the points in this section, it is necessary that the package can be used on Android, iOS and Web. To achieve this, it must be taken into account that all functionalities can be used on both the Web and mobile. If the package is written entirely in the native Dart, then there is not much problem. If the package uses functionality for Flutter, you have to make sure that it works on Mobile and Web. The second thing to keep in mind is that the functionalities of the dependencies that are used also work on the three platforms.
Code has no errors, warnings, lints, or formatting issues: This refers to the package having no errors or warnings. In addition, all files must be correctly formatted according to Dart guidelines. Fortunately, with the
dartfmt tool you can give the correct format to the files:
> dartfmt - w lib / main.dart
All of the package dependencies are supported in the latest version: This refers to the package using the latest versions in all its dependencies. For this reason, it is important to update your package once in a while since, once the package is uploaded, from time to time
pana is run again and your package’s score may drop.
Package supports latest stable Dart and Flutter SDKs: This refers to the package working well with the latest versions of Dart and Flutter.
The great thing about this report is that it shows us the necessary steps to improve the pack’s score.
As you can see, we reached 100 out of 100, not 110. In this pana report it is necessary to calculate the score that is given by the documentation that, as I mentioned before, once you have documented all the functions of the package, you can get those points without problems.
To upload a package you need to have an account at https://pub.dev/. After creating it, we will give the last check that our package does not have any alerts. For this, we use the same
pub package manager. We execute the following command in the root of our package:
> pub publish--dry - run
We resolve any alerts that the administrator may throw at us and proceed to upload the package:
> pub publish
At this point, it asks us for confirmation to publish our package, since it tells us that this action is forever. This means that once the package is uploaded, there is no way to remove it. Then we are asked to open a link to log in and give our authorization.
From here our package has been uploaded successfully. Verification and package creation takes 30-60 minutes, so don’t worry if you can’t find anything on your profile.
And ready! Enjoy your first package, share it and never stop updating it.
Packages help the community to develop more complex things in less time: “Do not invent the wheel twice.” Also having a good score translates into a good package that meets Dart standards, and this together with a good README and good functionality, helps encourage people to use your package.