How to Publish your Dart Package

In this tutorial, I'll be making a Dart Package from scratch. I'll be going over all the steps for creating a package from coding till publishing.

The Package

For this tutorial, I made a package that provides commonly used regex patterns. Let's go over how the library works before building it.

Installation

# pubspec.yaml
dependencies:
  regex_toolkit: ^1.0.0

$ pub get

Usage

import 'package:regex_toolkit/regex_toolkit.dart';

void main() {
  var email = 'john@doe.com';

  if (RegexToolkit.emailId.hasMatch(email)) {
    print('Valid Email');
  } else {
    print('Invalid Email');
  }
}

$ dart main.dart
Email Valid

Building

Let's build our package now.

1. Setup

We'll use stagehand to bootstrap a starter template.

$ pub global activate stagehand
$ mkdir <project_name>
$ cd <project-name>
$ stagehand package-simple

This sets us up with a boiler template of a simple Dart package.

.
├── analysis_options.yaml
├── CHANGELOG.md
├── example
│   └── <project-name>_example.dart
├── lib
│   ├── <project-name>.dart
│   └── src
│       └── <project-name>_base.dart
├── .gitignore
├── pubspec.lock
├── pubspec.yaml
├── README.md
└── test
    └── <project-name>_test.dart

2. Code

Next up is the actual coding part. Dart package convention is to write all of your code in lib/src directory and export required code through in src/<project-name>.dart file:

// lib/src/regex_toolkit_base.dart
/// Base class containing all the [RegExp] instances
class RegexToolkit {
    // All the code
}

// lib/regex_toolkit.dart
/// A collection of commonly used regular expressions.
library regex_toolkit;

export 'src/regex_toolkit_base.dart';

3. Test

Tests are written in test/ directory. Each test-suite comprises of a group which consists of several tests. Each test test one specific functionality. Assertions are done using the expect function, which takes in two arguments: actual and expected. If both of them match, then the test passes.

group('Common regualer expressions', () {
  setUp(() {
    // Add setup code if any
  });

  test('adds two numbers', () {
    expect(1 + 1, 2);
  });

  // More tests...
});

4. Documentation

When it comes to documentation, there are three places you need to write documentation in: README.md, example and comments.

README.md is reasonably apparent, every GitHub repo has that. The example directory should some code showing a sample use of the package. Here's how I have done in my package:

// example/main.dart
import 'package:regex_toolkit/regex_toolkit.dart';

void main() {
  var email = 'john@doe.com';

  if (RegexToolkit.emailId.hasMatch(email)) {
    print('Valid Email');
  } else {
    print('Invalid Email');
  }
}

You might have noticed that comments with three forward slashes: ///. These are used by Dart to form the package documentation.

/// Description of what this function does
void foo() {
  // code
}

This documentation is what is shown in the API Reference of your package once published. To get a preview, run dartdoc in your project directory. dartdoc will create the documentation preview in doc/api directory. You can open up the doc/api/index.html to preview the generated documentation.

5. Publish

Once you are confident enough with your code, tests and documentation, it's time to publish your code to pub.dev. Before publishing, it's a good practice to check for the following things:

• Make sure all tests pass
• Run dartanalyzer and fix errors is any
• Run dartdoc and verify the docs
• Make sure that README.md, CAHNGELOG.md and pubspec.yaml are updated

Before you can publish, you need to sign in with your Google account on pub.dev. Once that is done, run the following command to test your build:

$ pub publish --dry-run

If you get no errors, run:

$ pub publish

The CLI will ask you to login again, which is trivial.

And there you have it. That's how you make your own dart package. As mentioned above, I made my own package which is a collection of common regex patterns. If you are getting started with Open Source, contributing to this package will be a good starting point. You can add any of the regex patterns which you feel are missing. One major regex which is missing is the time pattern. Hope someone sends a pull request for add that 😄.

🌟 I made some Cheat-Sheets
🚀 Find me on Instagram | Github | Twitter | Website
😄 Have a wonderful day!