Packages

Wagtail benefits from a rich ecosystem of packages. Many Python and Django packages work with Wagtail out of the box, and there is a growing collection of Wagtail-specific packages for extending the CMS.

Finding existing packages

The official Wagtail third-party packages directory lists packages organized by category. Forms, migrations, media, integrations, SEO, and more. Awesome Wagtail offers a curated list of packages, articles, and resources.

Many general-purpose Django or Python packages also work directly, or can be integrated directly inside the CMS. Check out the Django Packages directory, or search directly on the Python Package Index (PyPI). You can use the classifier Framework :: Wagtail to find packages that explicitly target Wagtail compatibility.

See How to pick a good Wagtail package for more guidance on how to find and select packages.

Creating packages

We recommend the cookiecutter-wagtail-package template to scaffold a new package with a suitable structure, quality assurance tooling, and other important aspects of package authoring. We also provide guidelines for maintainers, to complement the official Python Packaging User Guide.

To tag your package as compatible with Wagtail, use our official classifier: Framework :: Wagtail. You can also add version-specific classifiers for all major versions, for example: Framework :: Wagtail :: 6.

Package maintenance guidelines

We recommend these guidelines for all packages in our ecosystem. They are particularly important for packages that are part of the first-party Wagtail packages and the Wagtail Nest organization for community-maintained packages.

To meet those guidelines, start your package with our official template: cookiecutter-wagtail-package.

Fundamentals

  • Consider naming your package with a wagtail- or django- prefix for ease of identification.

  • Use an OSI approved license, shared in a LICENSE file and with publication metadata. We recommend the 3-Clause BSD License.

Documentation

This is crucial to the success of your package.

  • We recommend writing all documentation in vanilla Markdown (CommonMark), with minimal to no use of platform-specific extensions.

  • Start with a README with basic information about all aspects of the package. Include:

    • Support targets for Python, Django, Wagtail.

    • Simple installation guide.

    • Links to all relevant resources about using or working on the package (documentation, support, security, changelog, etc.).

    • A screenshot of the package user interface, if applicable.

  • Create separate files for all aspects of the package to be documented. We recommend the Diátaxis documentation structure.

    • Produce reference documentation for all public APIs of the package.

    • Create how-to material for common usage scenarios.

    • Add a beginner tutorial for first-time users of the package.

    • Add a user guide if the package includes a user interface.

    • Create a CONTRIBUTING.md guide for contributors.

  • Consider publishing the package documentation as a website.

Demos

  • Include a demo project in the package repository to help contributors and potential new users.

  • Demonstrate functionality with freely-licensed content where possible.

Package metadata

Use the pyproject.toml format and standardized fields for as many aspects of the package as possible.

  • Dependency versions should be as wide as possible.

  • Use optional dependency groups for development dependencies.

  • Use classifiers for supported Python, Django, and Wagtail versions.

  • Use supported project URLs to link to resources about the package.

Support targets

We recommend broad support targets matching those of Wagtail.

Quality assurance

  • Set up linting and auto-formatting for Python code, Django templates, and other code where possible.

  • Use @wagtail/stylelint-config-wagtail for CSS linting, and @wagtail/eslint-config-wagtail for JS linting.

  • Write unit tests using Django’s built-in test framework.

  • Aim for unit test coverage above 90% (excluding migrations).

  • Set up continuous integration to automatically test every change to the package. Continuous integration should include:

    • Matrix testing across a representative range of supported Python / Django / Wagtail versions.

    • Security scanning of project code and dependencies.

    • Recommended: nightly testing of official plugins.

  • Set up automation to manage the project’s dependencies.

Releases

Collaborative maintenance