Dart Package Tutorial – Getting Started

Publishing Your Dart Package

Your package is almost ready. It only needs a few finishing touches before it goes live. First, you need to create basic documentation to tell developers what your package does and how they can use it.

For simplicity’s sake, change the package’s metadata name to my_genderizeio in pubspec.yaml.

Your pubspec.yaml should look like the screenshot below:

Now you’ll see that your example app and genderizeio_test.dart are throwing errors. This is because you changed the package name and it can’t find the GenderizeAPI class.

To fix this issue, change the import as follow in both files:

import 'package:my_genderizeio/genderizeio.dart';

Creating the Basic Documentation README.md

The documentation for the package shouldn’t be too long and can be straightforward since the package is basically a REST API wrapper. The Dart template fills in the README.md with some usual sections like Getting started and Usage. Go through the file and fill in the sections with information.

Fill in the Usage section with instructions on how developers can use your package:

# Usage
To use the `Genderize.io` package, you can simply import the `GenderizeAPI` class and call the `send` function:
```
final genderize = GenderizeAPI();
final result = await genderize.send('peter');
print('${result.name}: ${result.gender}');
```

README.md instructions are a very important part of the documentation. They tell developers how a package can help them and how to use it.

Next, edit your pubspec.yaml and add a new repository section. You can’t publish the library if it isn’t hosted in a public repository, like GitHub:

repository: https://github.com/your/repository

Your pubspec.yaml should look like this:

LICENSE

To successfully publish your package, you must include a license for your library. The license grants permission to other users and states how they can use the package and under whose name the package is registered. If you aren’t familiar with licenses, copy the MIT license and paste it into the LICENSE file.

Generating Package Documentation

Dart has a very helpful tool for generating documentation using forward slashs. You use three forwards slashes before the function /// and add information to your code. This information will be displayed when the user hovers their cursor over the function.

Comment your lib/src/genderizeio_base.dart to improve the quality of the code. Here’s an example of what it may look like:

Open Terminal and type the following command:

dart doc

Press Enter, and check the output:

$ dart doc
Documenting my_genderizeio...
Initialized dartdoc with 196 libraries
Generating docs for library genderizeio from package:my_genderizeio/genderizeio.dart...
no issues found
Documented 1 public library in 8.8 seconds
Success! Docs generated into genderizeio/doc/api

Check the project folder; it has a new directory named doc.

Open the index file doc/api/index.html in a browser, and navigate to the send method documentation.

You’ll now see the documentation for the send method with all comments you added to the code.

Importing Your Package Locally

In general, you add the package into your pubspec.yaml and run flutter pub get. This command fetches the package from the online repo and adds it to your project.

You may have noticed that you haven’t deployed your package anywhere online. For the project to fetch the package, you must give the package’s path, or where the package is located locally in your machine.

Go to flutter/pubspec.yaml, and import the package locally by adding the path of the adjacent genderizeio folder:

  my_genderizeio:
    path: ../genderizeio

Open Terminal, change the directory to your Flutter project, and run flutter pub get to verify the installation is correct. Then, check the output:

$ flutter pub get
Running "flutter pub get" in flutter...                            225ms

Go to flutter/main.dart and replace the _predictGender method with the following code:

void _predictGender() async {
  setState(() {
    _gender = _genderLoading;
  });

  final genderize = GenderizeAPI();
  final result = await genderize.send('peter');
  setState(() {
    _gender = 'is probably ${result.gender}';
  });
}

Import the genderizeio package when IDE shows you an error and suggests importing the library.

Build and run the project.

You just used your package in your app!

Publishing a Package Dry Run

Now that you’ve tested your package, it’s ready to go public.

Before you publish your Dart package, do a dry run to test whether everything goes according to plan. Open Terminal, go to the genderizeio folder, and type the following command:

dart pub publish --dry-run

Press Enter, and check the output. Your package should return a message:

$ dart pub publish --dry-run
Publishing my_genderizeio 1.0.0 to https://pub.dartlang.org:
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- analysis_options.yaml
|-- doc
|    -- api
|       |-- __404error.html
|       |-- categories.json
|       |-- genderizeio
|       |   |-- Genderize
|       |   |   |-- Genderize.fromJson.html
|       |   |   |-- Genderize.html
|       |   |   |-- count.html
|       |   |   |-- gender.html
|       |   |   |-- name.html
|       |   |   |-- probability.html
|       |   |-- Genderize-class.html
|       |   |-- GenderizeAPI
|       |   |   |-- GenderizeAPI.html
|       |   |    -- send.html
|       |   |-- GenderizeAPI-class.html
|       |    -- genderizeio-library.html
|       |-- index.html
|       |-- index.json
|       |-- static-assets
|           |-- favicon.png
|           |-- github.css
|           |-- highlight.pack.js
|           |-- play_button.svg
|           |-- readme.md
|           |-- script.js
|           |-- styles.css
|-- example
|    -- genderizeio_example.dart
|-- lib
|   |-- genderizeio.dart
|    -- src
|        -- genderizeio_base.dart
|-- pubspec.yaml
|-- test
     -- genderizeio_test.dart
NullSafetyCompliance.compliant

Package has 0 warnings.
The server may enforce additional checks.

The response looks good, meaning the package is ready to be published.

If your package is missing some files, like the license, it’ll throw an error. So, it’s important that the above command passes without any errors.

Publishing Dart Packages

Now, it’s time to try publishing it for real! Open Terminal, and type the following command:

dart pub publish

Press Enter, and check the output. If everything goes well, you’ll receive:

Publishing my_genderizeio 1.0.0 to https://pub.dartlang.org:
|-- CHANGELOG.md
|-- LICENSE
|-- README.md
|-- analysis_options.yaml
|-- example
|    -- genderizeio_example.dart
|-- doc ...
|-- lib
|   |-- genderizeio.dart
|   |-- src
|        -- genderizeio_base.dart
|-- pubspec.yaml
|-- test
    |-- genderizeio_test.dart
NullSafetyCompliance.compliant

Package has 0 warnings.
The server may enforce additional checks.

Great, you published your first package!