One of the most useful skills for an intermediate Dart developer is learning how to create reusable packages.

Instead of writing the same functionality repeatedly across different projects, you can place common code inside a Dart package and reuse it whenever you need it. You can also publish your package so other developers can install it through the Dart package ecosystem.

Creating a Dart package is useful for:

• Reusable utilities
• API clients
• Validation libraries
• Developer tools
• Data models
• Authentication helpers
• Database utilities
• Flutter plugins
• Internal company libraries
• Open-source projects

In this guide, you will learn how to create, organize, test, document, and publish your own Dart package.

---

What Is a Dart Package?

A Dart package is a reusable collection of Dart code that can be included in other Dart or Flutter projects.

For example, imagine you create a package called:

string_utils

It could provide reusable functions such as:

String capitalize(String value) {
  if (value.isEmpty) return value;

  return value[0].toUpperCase() + value.substring(1);
}

Instead of copying this function into every application, you can put it inside your package.

Other projects can then import it:

import 'package:string_utils/string_utils.dart';

This makes your code more reusable and easier to maintain.

---

Dart Package vs Flutter Package

Before creating a package, it is important to understand the difference between Dart and Flutter packages.

Dart Package

A Dart package contains Dart code and does not depend on Flutter.

It can be used for:

• Utility functions
• API clients
• Data models
• Business logic
• Validation
• CLI tools

Flutter Package

A Flutter package can depend on Flutter and may contain:

• Widgets
• Themes
• UI components
• Flutter-specific utilities
• Platform-independent Flutter code

If your package only needs Dart functionality, creating a pure Dart package is usually the better choice.

---

Prerequisites

Before creating your first package, make sure Dart is installed.

You can check your Dart installation using:

dart --version

You should see information about your installed Dart SDK.

You should also be familiar with:

• Dart syntax
• Classes
• Functions
• Imports
• Null safety
• Futures
• Basic package management

If you are developing Flutter applications, Flutter already includes the Dart SDK.

You can check Flutter with:

flutter --version

---

Step 1: Create a New Dart Package

Open your terminal and navigate to the directory where you want to create the package.

Run:

dart create -t package my_package

Replace my_package with your preferred package name.

For example:

dart create -t package string_utils

Dart will generate the basic package structure for you.

---

Step 2: Understand the Package Structure

After creating the package, you will see a structure similar to:

string_utils/
├── CHANGELOG.md
├── LICENSE
├── README.md
├── analysis_options.yaml
├── pubspec.yaml
├── lib/
│   └── string_utils.dart
├── test/
│   └── string_utils_test.dart
└── example/
    └── string_utils_example.dart

Let’s understand what each file does.

---

pubspec.yaml

This is one of the most important files in a Dart package.

It contains package information and dependencies.

A basic file might look like:

name: string_utils

description: A collection of useful string utilities.

version: 1.0.0

environment:
  sdk: ^3.0.0

The pubspec.yaml file can contain:

• Package name
• Description
• Version
• SDK constraints
• Dependencies
• Development dependencies
• Repository information
• Documentation links
• License information

---

lib/ Directory

The lib directory contains the public package code.

For example:

lib/
├── string_utils.dart
├── src/
│   ├── capitalize.dart
│   └── validators.dart

A good package usually keeps internal implementation details inside lib/src.

---

test/ Directory

The test directory contains automated tests.

For example:

test/
├── capitalize_test.dart
└── validators_test.dart

Testing is extremely important when creating reusable packages because your code may be used by many different applications.

---

README.md

The README explains how developers can install and use your package.

It should contain:

• Package description
• Features
• Installation instructions
• Usage examples
• API information
• Requirements
• License information

A good README can significantly improve the usability of your package.

---

CHANGELOG.md

The changelog records changes between package versions.

For example:

## 1.1.0

- Added email validation.
- Added phone number validation.

## 1.0.0

- Initial release.

Maintaining a changelog helps users understand what changed between versions.

---

Step 3: Create Your Package Functionality

Let’s build a simple package called string_utils.

Inside:

lib/src/

create:

capitalize.dart

Add:

String capitalize(String value) {
  if (value.isEmpty) {
    return value;
  }

  return value[0].toUpperCase() + value.substring(1);
}

This function converts the first character of a string to uppercase.

---

Step 4: Create a Public API

You generally don’t want users to import internal files directly.

For example, avoid making users write:

import 'package:string_utils/src/capitalize.dart';

Instead, expose the functionality through your main library file.

Open:

lib/string_utils.dart

and add:

library string_utils;

export 'src/capitalize.dart';

Now users can simply write:

import 'package:string_utils/string_utils.dart';

This creates a clean public API.

---

Why Use lib/src?

The src directory is conventionally used for implementation details that aren’t intended to be imported directly by package users.

For example:

lib/
├── string_utils.dart
└── src/
    ├── capitalize.dart
    ├── validators.dart
    └── formatters.dart

The main library file acts as the public entry point.

This gives you more control over what your package exposes.

---

Step 5: Add More Functions

Let’s add another file:

lib/src/validators.dart

Add:

bool isValidEmail(String email) {
  return email.contains('@') && email.contains('.');
}

Then update the public API:

library string_utils;

export 'src/capitalize.dart';
export 'src/validators.dart';

Your package now provides:

capitalize()

and:

isValidEmail()

---

Step 6: Get Package Dependencies

If your package requires external dependencies, add them to pubspec.yaml.

For example:

dependencies:
  http: ^1.0.0

Then run:

dart pub get

Dart downloads and resolves the dependencies.

For packages required only while developing or testing your package, use:

dev_dependencies:
  test: ^1.0.0

---

Step 7: Write Tests

A professional package should have automated tests.

Create:

test/string_utils_test.dart

For example:

import 'package:string_utils/string_utils.dart';
import 'package:test/test.dart';

void main() {
  group('String Utils', () {
    test('capitalizes first character', () {
      expect(
        capitalize('hello'),
        equals('Hello'),
      );
    });

    test('returns empty string unchanged', () {
      expect(
        capitalize(''),
        equals(''),
      );
    });

    test('validates email', () {
      expect(
        isValidEmail('john@example.com'),
        isTrue,
      );
    });
  });
}

Run the tests:

dart test

If everything passes, you should see successful test results.

---

Step 8: Use Static Analysis

Run:

dart analyze

This checks your package for potential problems.

Static analysis can identify:

• Type errors
• Unused imports
• Invalid code
• Analyzer warnings
• Potential bugs
• Style problems

Fix analyzer issues before publishing your package.

---

Step 9: Format Your Code

Run:

dart format .

This automatically formats Dart files according to Dart’s standard formatting rules.

You can check formatting without changing files using:

dart format --output=none --set-exit-if-changed .

This can be useful in CI pipelines.

---

Step 10: Add Documentation Comments

Good documentation makes your package easier to use.

Instead of:

String capitalize(String value) {

write:

/// Converts the first character of [value] to uppercase.
///
/// Returns the original value if it is empty.
String capitalize(String value) {
  if (value.isEmpty) {
    return value;
  }

  return value[0].toUpperCase() + value.substring(1);
}

Documentation comments are especially important for public APIs.

---

Step 11: Create an Example

An example/ directory is useful because it shows users how to use your package.

For example:

example/
└── string_utils_example.dart

Add:

import 'package:string_utils/string_utils.dart';

void main() {
  print(capitalize('hello dart'));

  print(
    isValidEmail('john@example.com'),
  );
}

Users can understand your package quickly by looking at this example.

---

Step 12: Test the Example

Run:

dart run example/string_utils_example.dart

You should see output similar to:

Hello dart
true

This verifies that your public API works as expected.

---

Step 13: Check the Package Before Publishing

Dart provides a command that analyzes a package for publishing issues.

Run:

dart pub publish --dry-run

This does not publish the package.

Instead, it checks the package and reports potential issues.

This is an important step before publishing.

---

Step 14: Understand Semantic Versioning

Dart packages use version numbers such as:

1.0.0

This generally follows semantic versioning:

MAJOR.MINOR.PATCH

MAJOR

Used for breaking changes.

Example:

1.0.0 → 2.0.0

MINOR

Used for backward-compatible features.

Example:

1.0.0 → 1.1.0

PATCH

Used for backward-compatible bug fixes.

Example:

1.0.0 → 1.0.1

Choosing versions carefully helps users understand whether an update might require code changes.

---

Step 15: Choose a Good Package Name

Your package name is important because users will see it whenever they install or import your package.

Good examples:

http_client
date_formatter
json_helper
validation_utils
network_manager

Avoid unclear names such as:

my_package123
test_project
awesome_code
new_library

Choose a name that clearly describes what your package does.

---

Dart Package Naming Rules

Dart package names generally use lowercase words separated by underscores.

Good:

string_utils
api_client
date_formatter

Avoid:

StringUtils
string-utils
String Utils

A descriptive and conventional name makes your package easier to discover and use.

---

Step 16: Publish Your Package

Once your package is ready, you can publish it to the public Dart package repository.

First, make sure:

dart test

passes.

Then run:

dart analyze

Format the project:

dart format .

Finally, perform a dry run:

dart pub publish --dry-run

If everything looks correct, publish with:

dart pub publish

Dart will guide you through the publishing process.

---

How Users Install Your Package

Once published, another Dart or Flutter developer can add your package as a dependency.

For example:

dependencies:
  string_utils: ^1.0.0

Then run:

dart pub get

or, in a Flutter project:

flutter pub get

They can then import it:

import 'package:string_utils/string_utils.dart';

And use your functions:

final result = capitalize('hello');

print(result);

---

Creating a Local Dart Package

You don’t have to publish a package publicly.

You can create a package and use it locally.

For example:

projects/
├── my_app/
└── string_utils/

In your application’s pubspec.yaml, you can use a path dependency:

dependencies:
  string_utils:
    path: ../string_utils

Then run:

dart pub get

This is useful for:

• Company projects
• Shared internal libraries
• Testing packages
• Developing a package before publishing it

---

Using a Git Dependency

You can also use a package directly from a Git repository.

For example:

dependencies:
  string_utils:
    git:
      url: https://github.com/example/string_utils.git

This can be useful when a package is hosted in a private or public Git repository and isn’t being consumed from the public package repository.

---

Building a More Professional Package

A simple utility package is a good starting point, but professional packages should consider several additional areas.

1. Clean Architecture

Separate responsibilities:

lib/
├── package_name.dart
└── src/
    ├── models/
    ├── services/
    ├── utils/
    └── validators/

Don’t place your entire package inside one large file.

---

2. Public vs Private APIs

Only expose functionality that users actually need.

For example:

export 'src/validators.dart';

But keep internal implementation details inside src/.

This makes future refactoring easier.

---

3. Strong Type Safety

Prefer:

String formatName(String name)

instead of:

dynamic formatName(dynamic name)

Strong typing makes packages safer and easier to understand.

---

4. Comprehensive Testing

Test:

• Normal inputs
• Empty inputs
• Null-related cases where applicable
• Invalid inputs
• Boundary cases
• Error conditions

A reusable package should be reliable because other applications may depend on it.

---

Create a Dart API Client Package

One of the most useful real-world package projects is an API client.

For example:

api_client/
├── lib/
│   ├── api_client.dart
│   └── src/
│       ├── client.dart
│       ├── models/
│       └── services/
├── test/
└── example/

The package could provide:

final client = ApiClient();

final users = await client.getUsers();

You could gradually add:

• Authentication
• Request headers
• JSON serialization
• Error handling
• Retry logic
• Pagination
• Request interceptors
• Logging
• Caching

This would be an excellent intermediate-to-advanced Dart portfolio project.

---

Create a Validation Package

Another useful package idea is a validation library.

For example:

bool isValidEmail(String email) {
  // validation
}

bool isValidPhone(String phone) {
  // validation
}

bool isStrongPassword(String password) {
  // validation
}

You could organize it as:

validation_utils/
├── lib/
│   ├── validation_utils.dart
│   └── src/
│       ├── email_validator.dart
│       ├── phone_validator.dart
│       └── password_validator.dart
├── test/
└── example/

This is simple enough for beginners but can become a useful reusable library.

---

Dart Package Development Workflow

A professional package workflow can look like this:

Create Package
      ↓
Design API
      ↓
Write Implementation
      ↓
Write Tests
      ↓
Run dart analyze
      ↓
Run dart format
      ↓
Update README
      ↓
Run dart pub publish --dry-run
      ↓
Publish
      ↓
Maintain Versions

Following this workflow helps prevent many common package-development problems.

---

Common Mistakes When Creating Dart Packages

Mistake 1: No Tests

A package without tests can become difficult to maintain.

Always add tests for important functionality.

Mistake 2: Poor Documentation

If users don’t understand how to use your package, they may avoid it even if the implementation is excellent.

Mistake 3: Exposing Internal Files

Avoid forcing users to import implementation files from src.

Provide a clean public API.

Mistake 4: Using dynamic Everywhere

Use Dart’s type system whenever possible.

Mistake 5: Poor Package Naming

Choose a descriptive, conventional package name.

Mistake 6: No Versioning Strategy

Breaking changes should be communicated through appropriate version changes.

Mistake 7: Publishing Without a Dry Run

Always run:

dart pub publish --dry-run

before publishing.

---

Best Dart Package Ideas for Practice

If you want to practice package development, consider building:

Beginner-Friendly

1. String utilities
2. Date formatting
3. Number formatting
4. Validation helpers
5. Calculator utilities

Intermediate

6. REST API client
7. JSON utilities
8. Local storage helper
9. Authentication helper
10. Pagination utility

Advanced

11. Networking framework
12. Database abstraction package
13. Caching library
14. Logging framework
15. Dart CLI developer tool

Building these projects will teach you how reusable software libraries are designed.

---

Dart Package Development Checklist

Before publishing your package, check the following:

• Package has a clear name
• pubspec.yaml is correctly configured
• SDK constraints are defined
• Public APIs are documented
• Internal code is organized
• Unit tests are included
• dart test passes
• dart analyze passes
• Code is formatted
• README contains installation instructions
• README contains usage examples
• CHANGELOG is maintained
• Example code works
• Version number is correct
• dart pub publish --dry-run passes
• Package is ready for publication

---

Frequently Asked Questions

Can I create a Dart package without Flutter?

Yes. Dart packages can be created and used without Flutter. They are ideal for reusable business logic, utilities, API clients, CLI tools, and other Dart applications.

Can a Dart package be used in Flutter?

Yes. A pure Dart package can generally be used by Flutter applications as long as its dependencies and functionality are compatible with the Flutter environment.

Is it free to create a Dart package?

Creating a package is free. You can also develop and test packages locally without publishing them publicly.

Can I create private Dart packages?

Yes. Packages can be maintained privately, for example within a company’s internal repositories or private package infrastructure.

How do I test a Dart package?

Use the Dart testing framework and run:

dart test

You should also run static analysis:

dart analyze

How do I publish a Dart package?

First verify the package with:

dart pub publish --dry-run

Then publish it using:

dart pub publish

---

Final Thoughts

Creating your own Dart package is an excellent way to move from writing application code to designing reusable software components.

The process is straightforward:

Create → Organize → Implement → Test → Document → Analyze → Publish → Maintain

Start with a small package such as a string utility or validation library. Once you understand the package structure, move toward more advanced projects such as API clients, networking libraries, caching systems, or reusable business-logic packages.

A well-designed Dart package should not only work correctly. It should also have a clean public API, strong type safety, useful documentation, automated tests, sensible versioning, and a clear project structure.

These practices will help you become a better Dart developer and will also prepare you for building professional Flutter applications and reusable libraries.