Contributing 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 standardized, reproducible analyses across research groups worldwide, reduce duplicated development effort, and accelerate scientific discovery.

Follow these steps to contribute modules and subworkflows to the nf-core/modules repository, making them available to all nf-core pipelines and the Nextflow community. The nf-core community strongly encourages all members to contribute their expertise and welcomes contributions of any scale.

Prerequisites

You will need the following to get started:

Tip

For detailed information about writing components, see Create Components.

Check if the component exists

Before starting, verify the component doesn’t already exist:

  1. Use the nf-core modules list command to search for existing modules:

    nf-core modules list

  2. Check the nf-core/modules repository for existing components.

  3. Review open pull requests to see if someone is already working on the component.

  4. Search open issues for related discussions.

Create an issue

To let others know you’re working on a new component:

  1. Create an issue in the nf-core/modules repository.
    • Use a clear title, e.g., “New module: fastqc”.
    • Describe what the component will do and how it will be used.
    • Add yourself to the Assignees to indicate you’re working on it.

This helps prevent duplicate work and allows the community to provide early feedback.

Fork and clone the repository

To set up your development environment:

  1. Fork the nf-core/modules repository to your GitHub account.

    • Go to the nf-core/modules repository and select Fork.

  2. Clone your fork locally and set up the upstream remote:

    git clone https://github.com/<github_username>/modules.git nf-core-modules
cd nf-core-modules
git remote add upstream https://github.com/nf-core/modules.git
git checkout -b <component_name>

  3. Install pre-commit hooks:

    pre-commit install
Note

The pre-commit install command sets up automatic code quality checks that will run when you commit changes. These checks help ensure your code meets nf-core standards.

Create your component

To create the component structure:

  1. Use nf-core/tools to generate the component files:

    • For modules:

      nf-core modules create

    • For subworkflows:

      nf-core subworkflows create

    This command creates the necessary files and directory structure with template code to guide you.

  2. Write your component following the Create Components guide.

    • Implement the tool command or workflow logic in main.nf.
    • Complete the metadata in meta.yml.
    • Write comprehensive tests in tests/main.nf.test.

Test your component

Before submitting, thoroughly test your component:

  1. Run the linting tool to check code quality:

    • For modules:

      nf-core modules lint <module_name>

    • For subworkflows:

      nf-core subworkflows lint <subworkflow_name>

    The linting checks ensure your component follows nf-core standards and includes all required files.

  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 submission.

Note

GitHub Actions automatically runs these tests when you submit a pull request, but running them locally first helps catch issues early and speeds up the review process.

Submit your component

To submit your component for review:

  1. Commit your changes with a clear message:

    git add .
git commit -m "Add new component: <component_name>"

  2. Sync your branch with upstream before pushing:

    git pull --rebase upstream master
git push origin <component_name>
Tip

Rebasing with upstream before creating a pull request applies your changes on top of the latest updates and helps prevent merge conflicts.

Create a pull request

To request review of your component:

  1. Go to the nf-core/modules repository on GitHub.

  2. Create a pull request from your branch.

    • Use the pull request template provided by the repository.
    • Reference the issue you created.
    • Describe what the component does and how you tested it.
    • Include example commands or screenshots if helpful.

  3. Add the “Ready for Review” label to indicate your component is ready for maintainer review.

  4. Request reviews from nf-core/modules-team.

Note

Components are tested via GitHub Actions CI using Docker, Singularity, and Conda to ensure they work across different environments. The automated tests must pass before your component can be merged.

Address review feedback

The nf-core maintainers will review your contribution:

  1. Wait for maintainer feedback on your pull request.

    Common feedback includes:

    • Code style improvements.
    • Additional tests or test scenarios.
    • Documentation clarifications.
    • Container or dependency updates.

  2. Make requested changes and push them to your branch:

    git add .
git commit -m "Address review feedback"
git push origin <component_name>

    The pull request will update automatically with your new changes.

  3. Respond to reviewer comments to discuss any questions or clarifications.

Complete the contribution

Once your pull request is approved:

  1. A maintainer will merge your pull request.

  2. Your component will be available in the nf-core/modules repository.

  3. All nf-core pipelines and Nextflow users can now use your component.

Congratulations on contributing to nf-core! Your work helps researchers worldwide conduct reproducible analyses.

Additional resources

If you need assistance during the contribution process:

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