Chip’s Tips: Week Three

The In’s and Outs of Flutter Package Publishing

Welcome back to Chip’s Tips! This week I’m going to share some tips, tricks, and general know-how on publishing your Flutter package (or plugin) to pub.dev. Topics that will be covered are:

1. Writing a killer readme
2. Writing good documentation
3. Ensuring code quality with dart_code_metrics, pana, and GitHub Actions
4. Hosting your example app

As always, this article assumes the reader has a basic working knowledge of Flutter. This week, it is assumed the reader has rudimentary experience with publishing a Flutter package. That said, I do my best to write in a beginner-friendly manner. Let’s get started!

Writing a Killer Readme

The keys to writing a great readme are:

• Include gifs and images of your package in action. This is especially important for packages that involve UI in any way. Most of the time, developers are unlikely to have, or want to spend, the time pulling your package and running the example. Putting gifs and images in your readme is a great way to quickly demonstrate what your package does to potential users.
• Write usage instructions. This is very important for packages and plugins that involve setup of various kinds. And make them specific! Don’t leave any details out. If it seems obvious to you, assume it is not obvious to others. If you are making assumptions of knowledge and/or experience, add a disclaimer.
• If your readme is long, make shortcuts. Use a table of contents that link to sections of your readme or use the details/summary tags to allow for hiding and showing certain sections.
• Follow the recent guidance from the Dart team on writing good readme pages. Some of the tips written here are mentioned there, and it is an excellent resource for writing readme pages.

Writing Good Documentation

To be honest, writing is hard. Like most things, it’s a skill that comes naturally to some, and harder to others. However, documenting your code is one of the most important things you can do as a package author. The good news is that the more you do it, the better you get at it. A good place to start is the “Effective Dart: Documentation” page on dart.dev.

Some things to strive for when documenting your code are:

• Use accessible language. Using complicated terminology and language feels good to do; after all, you know what you’re talking about! But not everyone can follow such language, and not everyone who reads your code might be as technical as you are. If you need your readers to understand certain terminology, dedicate a place in your code, readme, or wiki page that defines your terminology and link to it from a place it is likely to be seen.
• Write easily digestible paragraphs. Some readers might be in a hurry; others might have a disorder like ADHD. Breaking up your documentation into brief, easy to read paragraphs can help ensure your readers don’t get overwhelmed.

While pub.dev generates and hosts your documentation for you when you publish your package, you can also use dartdoc to generate and view your documentation locally. It’s very handy to be able to see how your documentation will look before you publish it!

You might also consider hosting your documentation on your own. There are a few notable packages that do this, like FlutterFire, Riverpod, and FVM. A quick and easy way to do so is with GitHub pages.

Ensuring Code Quality with dart_code_metrics and GitHub Actions

dart_code_metrics is an excellent tool that helps improve code quality by providing extra lint rules, code analysis, and antipattern warnings like member ordering, avoid returning widgets, cyclomatic complexity, long method, and much more. (These are of course highly useful in apps as well.)

The rule that is most relevant to our topic, however, is prefer trailing comma. Since pub runs a pana analysis on your package to compute its score, any dangling trailing commas will result in your package not passing static analysis. This lint rule can help you catch any missing commas that will reduce your pub score.

Speaking of pana, you can also run it locally before publishing your package. You can then see the score your package would receive on pub if you published it as-is. You can then take the opportunity to address any warnings, and fix them before you publish so that you don’t have to republish!

To make things even better, you can run both dart_code_metrics and pana on pull requests for your package using GitHub Actions! You can use the Dart/Flutter Package Analyzer action for getting a nicely formatted package score report. You can also run dart_code_metrics in the same action, although at this time you won’t get a nicely formatted report unless you manipulate the output yourself. However, the folks who make dart_code_metrics are working on an Action of their own and are looking into generated a report like this.

Feel free to check out a working example of this over at the repository for the macos_ui package.

Hosting your example app

Another great thing you can do is to publish your example app on GitHub pages. This way, potential users can actually use your package and see if they like it. (There is a caveat, though — your package must support Flutter Web.) We do this automatically using GitHub Actions over at macos_ui. Check out how we do it here. You can also see our working demo here.

That’s all for this week! Thanks for reading and I hope you found this useful!