dart_package_template

GitHub template repository for Dart packages, ready for pub.dev publication.

dart pub get dart_package_template

💙 Use cases

• 🏝️ A weekend project: quickly start a new OSS Dart project with everything set up
• 📚 Learning: understand best practices for Dart package structure, linting, testing, and CI
• 💻 Production-ready boilerplate: complete starting point for a high-quality Dart package

✨ Features

• Unopinionated! A minimal example focused on compliance with Dart guidelines
• Ready for immediate package publication to pub.dev
• Pre-configured pubspec.yaml with recommended fields
• Multiple example projects in the example/ directory
• Linting setup with lints package for code quality, following the Effective Dart style guide
• (Recommended) MPL-2.0 License for open source projects
• Unit tests setup with test package
• GitHub Actions workflows for automated testing/QA jobs on push events and PRs

This repository is also published as a package on pub.dev to make sure it's always kept up to date on the most recent best practices 🫶

Coming up next:

• GitHub Issue/PR templates
• CLI utility for maintenance/updates (separate repo/package)

---

🔮 Usage Guide

Getting Started

1. Create a new repository
   • Click the "Use this template" button on the GitHub page for this repository.
   • Fill in the details for your new repository and create it.
     • 🛑✋ IMPORTANT! Make sure to name your new repository and package with underscore separators, just_like_this as required by Dart.
2. Clone your new repository

   git clone <your-repo-url>
   cd <your-repo-name>

3. Update pubspec.yaml
   • Change the name, description, homepage, repository, and issue_tracker fields to match your package
   • Update the environment SDK constraints if necessary
   • Update the same fields in example/**/pubspec.yaml
4. Rename the entrypoint file lib/dart_package_template.dart to lib/<your_package_name>.dart - this is required by Dart package conventions
5. Update README.md
   • We recommend you keep the sections, titles and the structure of this README as-is
   • Update the content to reflect your package's purpose, features, and usage
   • Update the badges at the top to reflect your repository and package details
6. Update LICENSE
   • We recommend the included MPL-2.0 License for open source packages, as it's business-friendly and allows for both open source and proprietary use
   • If you choose a different license, make sure to update the LICENSE file accordingly

Development & Maintenance

1. Make sure you have the following enabled in your IDE:

   • Dart SDK
   • Dart/Flutter Linting
   • "Format on Save"

2. Write your code! implement your package functionality in lib/, however you like 💙

   • Make sure there are no format/analysis issues reported by your IDE!

3. Update & run tests to ensure everything is working as expected:

   dart test

4. Commit & push your changes to your repository. We recommend using a standardized branching strategy (such as GitFlow) and maintaining a cohesive commit message/history style.

5. Create a Pull Request to merge your changes into the main branch.

   • Make sure all GitHub Actions checks pass before merging
   • Once approved, merge the PR into main

6. Review & Refine

   • Regularly review your codebase for improvements, refactoring, and updates to dependencies
   • Keep your documentation up to date in README.md and CHANGELOG.md

Publishing

1. Commit the version bump

   • Update the version in pubspec.yaml according to Semantic Versioning
   • Update the CHANGELOG.md with the changes made in this version
     • 🤫 psst! you can use git log command to help you with this, such as git log --oneline --decorate 1.0.0..HEAD to see all commits since version 1.0.0
   • Name the commit something like Bump version to x.y.z
   • Create a git tag for the new version: git tag x.y.z

2. Publish to pub.dev

   • IMPORTANT: Make sure you have an account on pub.dev and are logged in via the command line using dart pub login
   • First run dart pub publish --dry-run to ensure everything is ready for publication
   • If the above command reports any issues, address them before proceeding
   • When ready, run dart pub publish to publish your package

Next steps

• Share your work! Announce your package on social media, relevant forums, and communities to gain users and feedback.
• Invite collaborators! Open your repository to contributions from others to help improve and maintain the package.
• Keep learning and improving! Regularly update your package with new features, bug fixes, and improvements based on user feedback.

---

That's it! 🥳 Congratulations on starting the journey of creating your Dart package! 🎉🤗💙

The Dart/Flutter community is made better by contributions like yours. Make sure to reach out and engage with others in the community, share experiences with other devs, and keep building amazing things!

Our community is warm and welcoming, make sure to act within that spirit! 💖

---

📄 License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.

🔥 Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. Make sure to read the following guidelines before contributing:

• Code of Conduct
• CONTRIBUTING.md
• "Effective Dart" Style Guide
• pub.dev Package Publishing Guidelines

🙏 Credits & Acknowledgements

Contributors 🧑‍💻💙📝

This package is developed/maintained by the following rockstars! Your contributions make a difference! 💖

Sponsors 🫶✨🥳

Kind thanks to all our sponsors! Thank you for supporting the Dart/Flutter community, and keeping open source alive! 💙

---

Based on dart_package_template - a high-quality Dart package template with best practices, CI/CD, and more! 💙✨