Welcome to a new article about the Dart and Flutter universe! As you may already know, many developers around the world can contribute to Flutter’s growth by writing packages and publishing them at https://pub.dev. It’s a big public repository where you can find packages for any platform (web, mobile, or desktop). Are you looking for something not yet uploaded at pub.dev? Be the first one to publish it!
If you want to see an example of what we’re talking about here, take a look at the equations package. If you want to create the simplest package ever you should at least make sure to have the following content in your folder:
lib/ directory: it contains the Dart source code
pubspec.yaml file: it describes various aspects of the package such as the name, the version, the dependencies, supported platforms, and so on.
That’s really all you need to create a simple package. Of course it’s not enough for production because we also need to take care of testing, versioning, and licensing. Instead of manually creating all the required files by hand, the Flutter command line tools can create a template for us.
$ flutter create--template = package equations
This command will prepare the
equations package with all of the files and directories you need (including
As you may guess, throwing the entire code inside a single
.dart file is not a great idea. When creating packages there are a few guidelines recommended by the official documentation and you should really follow those. Here’s what you can find inside the
lib/ folder for the equations package:
The entire source code of the package lies inside the
src folder: the only Dart file in there has the same name as the package and it only exports the public API. This makes sure that our library usage will only require a single import statement. Here are the contents of
1 2 3 4 5 6 7 8 9 10 11 12 13
library equations; export 'package:fraction/fraction.dart'; export 'src/algebraic/algebraic.dart'; export 'src/algebraic/types/constant.dart'; export 'src/algebraic/types/cubic.dart'; export 'src/algebraic/types/laguerre.dart'; export 'src/algebraic/types/linear.dart'; export 'src/algebraic/types/quadratic.dart'; export 'src/algebraic/types/quartic.dart'; // more export statements...
This is like a “collector”: it grabs and exposes your sources altogether so that when it’s time to use the library, it can simply be referenced using a single
import statement. In practice, thanks to this approach, rather than importing multiple files…
1 2 3
import 'package:equations/src/algebraic/types/cubic.dart'; import 'package:equations/src/algebraic/types/quadratic.dart'; import 'package:equations/src/algebraic/types/quartic.dart';
… you can just
import a single file and all of the other files will be automatically imported too!
Write your code inside
lib/src and write tests inside the
test/ folder. I really encourage you to keep in mind these suggestions while writing your package:
Make sure to set up as many rules as possible in your
analysis_options.yaml file (see an example here)
Fully document your public API using triple slashes. Try to be as concise as possible and, if it’s the case, include some code examples too. The pub website will rely on your docstrings to generate the HTML documentation of your package.
Try to always use
flutter format . command (or
dart format .) to keep your indentation consistent with the standards.
Move to the root and add an
example/ directory where you demonstrate how to use your package. It could contain some simple Dart files or even a big Flutter project.
Once the code is written, tested, and documented, it’s ready to be published at pub.dev. Before submitting it you should dedicate some time to quality improvements:
Make sure you have a LICENSE file
pubspec.yaml file to make sure that version, description and dependencies are ok
README.md file to describe your package in detail. This is really important because the README will be your package’s home page at pub.dev so it should look good. The official Flutter documentation has a dedicated page about this, give it a look.
CHANGELOG.md file to reflect the main changes you’ve applied to the current version that is going to be published.
Once all of those files have been reviewed it’s finally time to publish the package. To make sure that everything will run smoothly run this command:
$ flutter pub publish--dry - run
It executes a “fake publishing” which doesn’t upload your package but simulates what would happen if you did so. It might be useful to look for any warning or problems before moving on. If no problems are reported, you can proceed with the real publishing:
Open the console, move to the root of your project (the same folder as the pubspec file) and run
flutter format . if you haven’t already.
flutter pub publish command.
Type ‘y’ when prompted and then open the link generated by the console to confirm and validate your package publish.
Wait a few minutes for pub to process the files and generate the HTML documentation from your docstrings. But… we’re not done yet! Any package has a score ranging from 0 to 130 and your goal is, of course, to to maximize it. This is the current score of the equations package at the time of writing the article:
There’s the possibility to calculate pub points before publishing the package using the pana analysis tool. Running pana locally will give you a preview of the points and the possible suggestions you’d get on the website. There are three main points for a package:
Likes: It indicates how many developers found this package useful.
Popularity: It indicates how many projects are using your package. A high percentage indicates that a kit of apps depends on your package.
Pub points: This value gives insights about the quality of your package.
Pub points are simply the sum of each score obtained from “Follow Dart file conventions”, “Provide documentation” and all the other metrics you see. If you don’t provide an
example/ folder, you’ll lose points so make sure to include one.
Certain publishers at pub.dev have a blue shield next to their name. Thanks to that, you can recognize packages uploaded by a publisher whose identity has been verified. The badge isn’t about the quality of the code but it’s related to the authenticity of the publisher and the authority of the product you’re using.
To become a verified pub publisher there are a few steps to follow. You need an active Google account which will be associated with both pub.dev and the Google Search Console (GSC).
Create a Google account (or use your existing one), login to the Google Search Console
Any verified publisher must have a domain to associate with their pub account. In my case the domain is fluttercompletereference.com.
Enter your domain in GSC and you’ll be asked to verify the identity via DNS. To do this, go to your domain provider settings and add a new TXT record in the DNS entries table. The GSC will give you the exact string to insert.
Once you’ve added your DNS entry, wait up to forty-eight hours for the propagation and then you’ll be able to validate the domain.
For reference, here’s the exact DNS entry you need to add:
IN TXT "google-site-verification=XXXXXXXXXXXX"
Once you’ve managed to verify your domain with success in the console, open pub.dev and login with your Google account. Go to the top-right corner and then click create publisher. Write the domain name you’ve verified in the box and click “CREATE PUBLISHER”. If you try to submit an unverified DNS domain, you’ll get an error.
In the next article, we will learn how to maintain the GitHub repository behind our package. In particular, we will schedule CI actions, prepare issue templates, and setup a GitHub page to host a potential demo for our package. It will be interesting so make sure to read the next article!