docs: Add developing modules tutorial #4155

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

jfy133 merged 11 commits into main from chris-module-guide

Apr 22, 2026

0 ...ning/nf-core-module-file-relationship.png → ...ules/nf-core-module-file-relationship.png

File renamed without changes

...src/content/docs/developing/tutorials/writing-nf-core-modules/1-introduction.md

-Original file line number
+Diff line change
@@ -0,0 +1,59 @@
+    ---
+    title: "Chapter 1: Introduction"
+    subtitle: "Learn to write nf-core modules"
+    shortTitle: "Chapter 1: Introduction"
+    ---
+    :::tip{title="Last updated"}
+    Material originally written for the **A practical introduction to nf-core components for Nextflow developers** training at the nf-core Hackathon March 2025, Berlin local site _(see [event](https://nf-co.re/events/2025/hackathon-march-2025/robert-koch-institute))_.
+    Duration: **4hr**
+    Original author: James A. Fellows Yates (@jfy133), with corrections and improvements from Niklas Schandry (@nschan) and Alexandru Mizeranschi (@amizeranschi).
+    Refreshed style by: Chris Hakkaart (@christopher-hakkaart )
+    :::
+    An nf-core module is an atomic, standardised, reproducible, and tested [Nextflow DSL2 module](https://www.nextflow.io/docs/latest/module.html).
+    You can install an nf-core module into any Nextflow pipeline with a single command, then efficiently integrate it into your workflow thanks to its consistent internal structure.
+    ## Why use nf-core modules
+    - **Efficiency**: reuse community modules instead of writing your own.
+    - **Consistency**: every module follows the same structure, so modules connect together predictably.
+    - **Documentation**: each module ships with metadata and descriptions.
+    - **Future-proofing**: modules cover all inputs and outputs from the start, so you avoid rewrites when requirements change.
+    - **Automation**: standardisation enables future automated workflow development.
+    ## Scope
+    This training covers:
+    - Writing nf-core modules.
+    - Using nf-core modules in official nf-core pipelines and custom Nextflow pipelines.
+    ## Learning objectives
+    By the end of this training, you will be able to:
+    - Identify the file components of an nf-core module.
+    - Apply the nf-core module specifications.
+    - Locate documentation for developing an nf-core module.
+    - Write an nf-core module.
+    - Write nf-test unit tests for an nf-core module.
+    - Follow the workflow for contributing modules to the community repository.
+    - Use an nf-core module in any Nextflow pipeline.
+    ## Chapters
+    - Chapter 1: [Introduction](/docs/developing/tutorials/writing-nf-core-modules/1-introduction)
+    - Chapter 2: [Getting started](/docs/developing/tutorials/writing-nf-core-modules/2-getting-started)
+    - Chapter 3: [What is an nf-core module?](/docs/developing/tutorials/writing-nf-core-modules/3-what-is-a-module)
+    - Chapter 4: [Generating boilerplate files](/docs/developing/tutorials/writing-nf-core-modules/4-boilerplate)
+    - Chapter 5: [Writing an nf-core module](/docs/developing/tutorials/writing-nf-core-modules/5-writing-modules)
+    - Chapter 6: [Testing an nf-core module](/docs/developing/tutorials/writing-nf-core-modules/6-testing)
+    - Chapter 7: [Development workflow](/docs/developing/tutorials/writing-nf-core-modules/7-development)
+    - Chapter 8: [Using nf-core modules in pipelines](/docs/developing/tutorials/writing-nf-core-modules/8-using)
+    :::tip
+    Read chapters [2](./2-getting-started)–[7](./7-development) through once before starting development. When you reach [chapter 7](./7-development), return to [chapter 2](./2-getting-started) to begin writing the module itself.
+    :::

.../content/docs/developing/tutorials/writing-nf-core-modules/2-getting-started.md

-Original file line number
+Diff line change
@@ -0,0 +1,41 @@
+    ---
+    title: "Chapter 2: Getting started"
+    subtitle: "What you need before starting"
+    shortTitle: "Chapter 2: Getting started"
+    ---
+    This chapter lists what you need before starting the training.
+    ## Prerequisite knowledge
+    You should already be familiar with:
+    - Writing Nextflow pipelines (see the [Nextflow training](https://training.nextflow.io/)).
+    - How Nextflow modules and processes work (see the [Nextflow modules documentation](https://nextflow.io/docs/latest/module.html)).
+    - Git and GitHub basics (see the [git tutorial](https://git-scm.com/docs/gittutorial) and [GitHub Skills](https://skills.github.com/)).
+    ## Required software and accounts
+    You need the following installed or set up:
+    - [Nextflow](https://www.nextflow.io/docs/latest/install.html).
+    - [nf-core tools](https://nf-co.re/docs/nf-core-tools/installation).
+    - A Nextflow-supported software management system, one of:
+      - [Conda](https://conda-forge.org/download/)
+      - [Docker](https://docs.docker.com/manuals/)
+      - [Apptainer](https://apptainer.org/docs/user/latest/quick_start.html#installation)
+    - A [GitHub account](https://github.com).
+    - A fork and local clone of the [nf-core/modules repository](https://github.com/nf-core/modules).
+    ## Tool assumptions
+    This training assumes you have:
+    - A command-line tool in mind to wrap as an nf-core module.
+    - A [Bioconda](https://bioconda.github.io/conda-package_index.html) recipe for that tool.
+    :::note
+    This training was written and tested with nf-core/tools 3.2.0 and Nextflow 24.10.4.
+    :::
+    The [next chapter](./3-what-is-a-module) introduces what defines an nf-core module.

...content/docs/developing/tutorials/writing-nf-core-modules/3-what-is-a-module.md

-Original file line number
+Diff line change
@@ -0,0 +1,68 @@
+    ---
+    title: "Chapter 3: What is an nf-core module?"
+    subtitle: "What defines an nf-core module"
+    shortTitle: "Chapter 3: What is a module?"
+    ---
+    An nf-core module is an opinionated, open-source Nextflow wrapper around a single command-line tool or script. The [central community repository](https://github.com/nf-core/modules) holds more than [1800 modules](https://nf-co.re/modules) that you can reuse in your own pipelines.
+    This page describes what an nf-core module is and what distinguishes it from a standard Nextflow process.
+    ## Contents of an nf-core module
+    An nf-core module usually wraps one tool command, or one tool with a single subcommand.
+    :::info{collapse title="Comparison with Nextflow modules"}
+    A Nextflow process or module has no restrictions on the number of tools or subcommands it can execute.
+    An nf-core module aims for a single analysis command per module.
+    This atomic design supports lego-block construction of pipelines and makes modules easier to understand, share, and test, although it is not always the most resource-efficient approach.
+    :::
+    Each nf-core module follows strict [specifications](../../../specifications/components/overview) agreed by community consensus. The specifications cover:
+    - [Naming](../../../specifications/components/modules/naming-conventions) and [formatting](../../../specifications/components/modules/formatting) conventions.
+    - [Software environments](../../../specifications/components/modules/software-requirements).
+    - [Standardised tags](../../../specifications/components/modules/testing#tags).
+    - [Input and output channels](../../../specifications/components/modules/input-output-options).
+    - [Tool parameters](../../../specifications/components/modules/module-parameters) configurable by pipeline developers.
+    - Use of [meta maps](../../../specifications/components/modules/general#use-of-meta-maps).
+    - Use of [stubs](../../../specifications/components/modules/general#stubs).
+    The specifications also expand the minimum required single file from a single Nextflow `.nf` script to five required files.
+    This reflects the nf-core focus on standardisation, reproducibility, and high-quality documentation.
+    A complete nf-core module directory can contain up to six files:
+    ```tree
+    ├── environment.yml
+    ├── main.nf
+    ├── meta.yml
+    └── tests/
+        ├── main.nf.test
+        ├── main.nf.test.snap
+        └── nextflow.config ## optional!
+    ```
+    These files fall into three categories:
+    - Module execution
+    - Module documentation
+    - Module testing
+    The following diagram shows how these files relate to each other:
+    <img width=80% alt="Diagram showing how the execution, documentation, and testing files in an nf-core module relate to each other." src="/images/developing/tutorials/writing-nfcore-modules/nf-core-module-file-relationship.png">
+    _Schematic diagram showing the relationship between the three main categories of files in an nf-core module._
+    - `main.nf` defines the Nextflow process that the module executes.
+    - `environment.yml` is a Conda environment file loaded by `main.nf`. It specifies the software dependencies used when a pipeline runs with `-profile conda`.
+    - `meta.yml` documents the contents of `main.nf`, including tool metadata and input and output specifications.
+    - `main.nf.test` describes an nf-test unit test for the `main.nf` process.
+    - `main.nf.test.snap` is a snapshot file generated by nf-test. It compares the output of one test run with another to confirm reproducibility.
+    - `nextflow.config` is an optional Nextflow configuration file used when `main.nf.test` executes.
+    Writing an nf-core module means creating these files and populating them with content that follows the nf-core specifications.
+    The [next chapter](./4-boilerplate) goes into more detail about the contents of each file.

.../src/content/docs/developing/tutorials/writing-nf-core-modules/4-boilerplate.md

-Original file line number
+Diff line change
@@ -0,0 +1,89 @@
+    ---
+    title: "Chapter 4: Generating boilerplate files"
+    subtitle: "How to generate the module file skeleton"
+    shortTitle: "Chapter 4: Boilerplate files"
+    ---
+    This chapter explains how to generate an nf-core module template and what each file contains.
+    ## Preparation
+    Fork and clone the [nf-core/modules GitHub repository](https://github.com/nf-core/modules) to your working environment, then create a new branch for your module:
+    ```bash
+    git switch master ## ensure you have the latest state of the repository
+    git switch -c <MY_NEW_MODULE_BRANCH>
+    ```
+    ## Generate the boilerplate files
+    From the root of the repository, run:
+    ```bash
+    nf-core modules create <toolname>/<subcommand>
+    ```
+    :::note
+    If your module does not have subcommands, use `<toolname>`
+    :::
+    ### Naming conventions
+    - All parts of the module name must be lowercase, alphanumeric, with no punctuation or special characters.
+    - Single-command tools use the tool name only. For example, for a tool executed with `fastp -i <input> -o <output>`, run `nf-core modules create fastp`.
+    - Tools with subcommands use `<tool>/<subcommand>`, even if you only plan to wrap one subcommand. For example, `samtools view`, run `nf-core modules create samtools/view`.
+    - For a third level of subcommand, append it to the subcommand name. For `samtools view flagstats`, run `nf-core modules create samtools/viewflagstat`.
+    For example, to create a module for the tool `drep` with the subcommand `compare`:
+    ```bash
+    nf-core modules create drep/compare
+    ```
+    ### Prompts from `nf-core modules create`
+    The command tries to pre-fill the boilerplate.
+    It searches [Bioconda](https://bioconda.github.io/) and [biocontainers](https://biocontainers.pro/) for the latest version of your tool and adds the container definitions automatically.
+    You will then be prompted for:
+    - **Your GitHub username.**
+    - **A process resource label.** These standardised tags map to default memory, CPU, and wall time. Choose the label that best matches your tool's typical requirements. The defaults for each label are defined in the pipeline template [base.config](https://github.com/nf-core/tools/blob/52e810986e382972ffad0aab28e94f828ffd509b/nf_core/pipeline-template/conf/base.config#L29-L54). Pipelines can override these values.
+    - **Whether the module should use a [meta map](https://nf-co.re/docs/developing/components/meta-map).** Answer yes in most cases. Meta maps carry sample metadata alongside files, which pipelines use to drive downstream processing decisions.
+    :::tip
+    You can pass any of these values as command-line flags to skip the prompts.
+    :::
+    ## Output
+    After the command completes, you will see the following files and directories:
+    ```tree {8-13}
+    modules/nf-core/drep/compare/
+    ├── environment.yml
+    ├── main.nf
+    ├── meta.yml
+    └── tests
+        └── main.nf.test
+    ```
+    If you later create a second subcommand (`dereplicate`), the directory structure becomes:
+    ```tree {8-13}
+    modules/nf-core/drep/
+    ├── compare
+    │   ├── environment.yml
+    │   ├── main.nf
+    │   ├── meta.yml
+    │   └── tests
+    │       └── main.nf.test
+    └── dereplicate
+        ├── environment.yml
+        ├── main.nf
+        ├── meta.yml
+        └── tests
+            └── main.nf.test
+    ```
+    The [next chapter](./5-writing-modules) walks through each generated file and explains what to change.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add developing modules tutorial #4155

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!