Publishing Dart and Flutter packages at pub.dev - Part 1

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!

Setup

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.

1
$ flutter create--template = package equations

This command will prepare the equations package with all of the files and directories you need (including lib and pubspec.yaml).

Creating the package

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 equations.dart:

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!

1
import 'package:equations/equations.dart';

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:

1. Make sure to set up as many rules as possible in your analysis_options.yaml file (see an example here)

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

3. Try to always use flutter format . command (or dart format .) to keep your indentation consistent with the standards.

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

Reviewing and publishing

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

• Check your pubspec.yaml file to make sure that version, description and dependencies are ok

• Use the 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.

• Update the 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:

1
$ 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:

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

2. Run the flutter pub publish command.

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

Bonus!

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

1. Create a Google account (or use your existing one), login to the Google Search Console

2. Any verified publisher must have a domain to associate with their pub account. In my case the domain is fluttercompletereference.com.

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

4. 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:

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

What’s next

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!

References

• Flutter Complete Reference book.

• The official Dart Tour guide.

LOOKING FOR WORK?

CHECK OUT TOPCODER FLUTTER FREELANCE GIGS