Using the Nextflow Gradle plugin

Nextflow provides a new plugin create command that simplifies the creation of Nextflow plugins. This command leverages the nf-plugin-template project, which uses the Nextflow Gradle plugin to streamline plugin development.

The Nextflow Gradle plugin configures default dependencies needed for Nextflow integration and defines Gradle tasks for building, testing, and publishing Nextflow plugins. The Gradle plugin is versioned and published to the Gradle Plugin Portal, allowing developers to manage it like any other dependency. As the plugin ecosystem evolves, the Gradle plugin will enable easier maintenance and adoption of improvements. This page introduces Nextflow Gradle plugin and how to use it.

Note

The Nextflow Gradle plugin and plugin registry are currently available as a public preview. See the Migrating to the Nextflow plugin registry for more information.

Creating a plugin

New in version 25.04.0.

The best way to create a plugin with the Nextflow Gradle plugin is to use the nextflow plugin create sub-command and create a plugin project based on the Nextflow plugin template. See Nextflow plugin template for more information about the Nextflow plugin template.

To create Nextflow plugins with the Gradle plugin:

  1. Run nextflow plugin create.

  2. Follow the prompts to add your plugin name, organization name, and project path.

  3. Develop your plugin extension points. See Extension points for more information.

  4. Develop your tests. See Testing a plugin for more information.

  5. In the plugin root directory, run make assemble.

Installing a plugin

Plugins can be installed locally without being published.

To install plugins locally:

  1. In the plugin root directory, run make install.

    Note

    Running make install will add your plugin to your $HOME/.nextflow/plugins directory.

  2. Run your pipeline:

    nextflow run main.nf -plugins <PLUGIN_NAME>@<VERSION>

    Replace <PLUGIN_NAME>@<VERSION> with your plugin name and version.

    Note

    Plugins can also be configured via Nextflow configuration files. See Using plugins for more information.

Testing a plugin

Testing your Nextflow plugin requires unit tests and end-to-end tests.

Unit tests

Unit tests are small, focused tests designed to verify the behavior of individual plugin components.

To run unit tests:

  1. Develop your unit tests. See MyObserverTest.groovy in the plugin template for an example unit test.

  2. In the plugin root directory, run make test.

End-to-end tests

End-to-end tests are comprehensive tests that verify the behavior of an entire plugin as it would be used in Nextflow pipelines.

End-to-end tests should be tailored to the needs of your plugin, but generally take the form of a small Nextflow pipeline. See the validation directory in the plugin template for an example end-to-end test.

Publishing a plugin

The Nextflow Gradle plugin allows you to publish plugins to the Nextflow plugin registry from the command line.

To publish plugins to the Nextflow plugin registry:

  1. Create a file named $HOME/.gradle/gradle.properties, where $HOME is your home directory.

  2. Add the following property:

    npr.apiKey=<API_KEY>

    Replace <API_KEY> with your plugin registry API key. See Creating an access token for more information about creating an API key.

  3. Run make release.

Additional resources

For additional Nextflow Gradle plugin configuration options, see the Nextflow Gradle plugin repository.