Creating components

nf-core modules and subworkflows are reusable Nextflow components shared across pipelines. Modules are individual tool wrappers that represent single processes, while subworkflows combine multiple modules into cohesive analysis units. Shared components enable standardised, reproducible analyses across research groups worldwide, reduce duplicated development effort, and accelerate scientific discovery.

This guide explains how to write and develop modules and subworkflows for nf-core. Once your component is ready, see Contributing Components for instructions on contributing it to nf-core.

Prerequisites

You will need the following to get started:

Check if the component exists

nf-core has a modules repository of over 1000 modules. To verify it doesn’t already exist before creating a new component:

  1. Run the nf-core modules list command:

    nf-core modules list

  2. Check the nf-core/modules repository.

  3. Review open pull requests and issues.

If the component is new, create an issue with an appropriate title (e.g., “new module: fastqc”) and assign yourself to let others know you’re working on it.

Create the component structure

To create a new module or subworkflow:

  1. Create a new branch in your local repository:

    git checkout -b <component-name>

  2. Use nf-core/tools to generate the component structure:

    • For modules:

      nf-core modules create

    • For subworkflows:

      nf-core subworkflows create

    The create command generates three core files with a standard structure:

    • environment.yml: A Conda environment file used by environment and container engines.
    • main.nf: The main script containing the process or workflow definition with TODO statements to guide you through implementation.
    • meta.yml: Metadata file storing general information, author details, and input/output descriptions. This file is validated against a JSON schema to ensure consistency.
    • tests/main.nf.test: Test workflow to unit test the component outputs. All components must include tests.
    Note

    A complete nf-core module may consist of up to two additional files:

    • tests/main.nf.test.snap: A snapshot file that is generated by nf-test test and used to compare the output of one test run with another.
    • tests/nextflow.config: A Nextflow configuration file used by nf-test

Write your component

To implement your component:

  1. Follow the TODO statements in the generated main.nf file.

    • Implement the tool command or workflow logic.
    • Populate version channels using eval output qualifiers.
    • Ensure adherence to component specifications.
    Note

    Specifications are designed based on the consensus opinions of the wider nf-core community and span multiple areas. For example:

    • Naming and formatting conventions
    • What software environment to use
    • Use of standardised tags
    • What input and output channels are used
    • How to allow pipeline developers to use specific tool parameters
    • Use of ‘meta maps’
    • Use of stubs

  2. Complete the meta.yml file with comprehensive metadata.

    • Fill in all required metadata fields.
    • Document all inputs and outputs with descriptions.
    • Include tool references and version information.

  3. Write comprehensive tests in tests/main.nf.test.

    • Use minimal test data from tests/config/test_data.config when possible.
    • Follow test-data specifications to keep test datasets small and fast.
    • Create test snapshots to verify outputs match expected results.
    • Add multiple test scenarios if applicable (e.g., single-end and paired-end data).
    • For large datasets requiring stub tests, document alternative testing procedures.
    • See the Testing documentation for comprehensive guides on writing assertions and handling complex testing scenarios.
Note

All components require test workflows. Tests validate that your component works correctly and prevent regressions when changes are made.

Test your component

Before contributing your component, thoroughly test it to ensure it meets nf-core standards:

  1. Run the linting tool to check code quality and adherence to nf-core standards:

    • For modules:

      nf-core modules lint <module-name>

    • For subworkflows:

      nf-core subworkflows lint <subworkflow-name>

    The linting tool checks for common issues such as missing files, incorrect formatting, and invalid metadata.

  2. Run the component tests:

    • For modules:

      nf-core modules test <module-name>

    • For subworkflows:

      nf-core subworkflows test <subworkflow-name>

    All tests must pass before you can contribute your component.

Tip

GitHub Actions automatically runs these tests when you submit a pull request, but running them locally first helps catch issues early.

Next steps

Once your component is written and all tests pass, you can contribute it to nf-core:

  • Follow the Contributing components guide to submit your component to the nf-core/modules repository.
  • Your component will be reviewed by the nf-core community and, once approved, will be available to all nf-core pipelines and the Nextflow community.

Additional resources

If you need assistance while developing your component:

The nf-core community is here to help. Don’t hesitate to ask questions.
On this page