R project template

This is an attempt to make an R project template, that is not an R package, and that uses some of the recent tools that have been created in the R ecosystem. The template is inspired by the python-project-template by Gemma Danks.

The project features uvr for project/package management and R version installation, jarl for linting, air for formatting, ry for static type checking, justfile, testthat testing, a Quarto documentation site, .editorconfig, .devcontainer, GitHub Actions CI, and automated semantic releases.

While the template can help you start writing code immediately without having to spend time deciding what tools or conventions to use, the tools and conventions that it introduces are not the default way of doing things in the R world, and there is a question mark if they get adopted in the future or not.

How to use this template

1. 🌱 Create a New Repository on GitHub
   1. Click "Use this template".
   2. Choose “Create a new repository”.
   3. Pick a name for your new project (for example, my-awesome-package).
   4. Clone your new repo locally
2. 🏡 Customise the repository
   1. Rename your package directory cd src; mv package_name my_package
   2. Update uvr.toml with your package name, author, and description, and preferred repository.
   3. Update all references to package_name in:
      • scripts/ (run-tests.R, gen-rd.R)
      • docs/ (_quarto.yml)
      • notebooks/demo.qmd
      • release-please-config.json
      • docs GitHub Actions workflow
      • This README (including badge links)
   4. Update the "package-name" field in release-please-config.json with your package name for automatically bumping the version number in uvr.toml (see release-please issue #2561).
   5. Customise this README with a description of your project and planned features.
   6. Clear the NEWS.md.
   7. Enable automated releases by permitting GitHub Actions to open PRs (Settings -> Actions -> Workflow permissions) and add an initial commit hash to bootstrap the release-please in .release-please-manifest.json.
   8. Enable publishing to GitHub Pages (Settings -> Pages).

🚀 Features

• Modular project directory structure using box.
• README template with badges.
• Packaging, dependency management, and R version installation via uvr: uvr.toml.
• Linting via Jarl.
• Formatting via Air.
• Static type and scope checking via ry.
• Testing framework using testthat.
• Git hooks via prek (formatting, linting and static checking).
• Editor setup for VS Code / Positron: recommended extensions for air, jarl, ry and Quarto (.vscode/extensions.json), format on save (.vscode/settings.json).
• CI using GitHub Actions: .github/workflows/ci.yml.
• Docs generated with box's own roxygen parser + rd2qmd and rendered as a single Quarto website, deployed to GitHub Pages via GitHub action: .github/workflows/generate-docs.yml.
• Templates for GitHub issues: bug report (01-bug.yml) and feature request (02-feature.yml).
• Template for GitHub pull request: .github/pull_request_template.md.
• Template for documenting architectural decisions: docs/architecture/adr/template.md.
  • ADR to explain the rationale for using ADRs: docs/architecture/adr/001-use-architectural-decision-records.md.
• Dependabot weekly updates for GitHub Actions: .github/dependabot.yml.
• Release automation via GitHub action from release-please: release-please-config.json.
• Citation metadata, automatically updated for each new release: CITATION.cff.
• EditorConfig configuration for consistent coding style across editors: .editorconfig.

‼️ Limitations

• Test coverage cannot be registered with codecov because it seems the R package covr does not work in this type of project structure.
• pkgdown cannot be used for documentation for the same reason as above.
• devtools::check() does not work because it expects a package structure with a DESCRIPTION file and an R/ directory for source code, which this template does not have.
• ry does not resolve box::use() imports. Referencing a box-imported module or name (hello$say_hello(), lapply(x, say_hello)) reports a false RY010 (unbound variable), and box::use(dplyr[filter]) is treated as stats::filter. Suppress with # ry: ignore[RY010] or list the names under globals in ry.toml.

📦 Installation

Working in a development container

A Dockerfile and configuration in .devcontainer can be used in VSCode or GitHub Codespaces to work in a pre-configured development environment. It uses a minimal Debian base image and installs Quarto, uvr (which then installs R itself), air, jarl, ry, prek, rd2qmd, and just.

To open the project in the container VSCode, you will need to add the Dev Containers extension and download Docker (or Podman -- and configure VSCode to use podman instead of Docker) -- see the VSCode tutorial on devcontainers for more details on using devcontainers. Then run:

Dev Containers: Reopen in Container

Manual installation

1. Install uvr
2. Install air, jarl and ry (the git hooks run the installed binaries)
3. optional, if you want to use shortcut commands, install just
4. optional, if you want to use pre-commit hooks, install prek
5. optional, if you want to build the docs site locally, install Quarto and rd2qmd
6. Clone and install the project using uvr:

git clone https://github.com/novica/r-project-template
cd r-project-template
uvr r install $(cat .r-version)
uvr sync

1. Install pre-commit hooks (only needs to be done once): just pre-commit-install

Day-to-day: is uvr how you run things?

No — uvr only installs R itself and syncs .uvr/library; .Rprofile then wires that library onto .libPaths() automatically. Once you've run uvr sync, write and run code in src/package_name/ and notebooks/ from your normal R session (RStudio/Positron/terminal R, or quarto render) — no uvr prefix needed. Reach for uvr again only when dependencies change (uvr sync/uvr update) or for headless script execution (uvr run <script>.R, used by just test/CI, since it also finds the right R binary).

🧪 Common Tasks

Several common tasks have been added as recipes to a justfile in the root of the repository:

    default             # Default recipe (shown when running plain `just`)
    install             # Install R (via uvr) and dependencies (uvr sync)
    update              # Upgrade packages to the latest versions available (uvr update)
    lint                # Lint (Jarl check)
    format              # Format (Air format)
    typecheck           # Static type/scope check (ry)
    test                # Run testthat
    docs-build          # Build docs (box + rd2qmd generate reference md, Quarto renders the site)
    pre-commit-install  # Install git hooks (via prek)
    pre-commit          # Run all git hooks (via prek)

📚 Documentation

• Generated with box's own roxygen parser + rd2qmd and rendered as a single Quarto website (just docs-build), combining this README, the architecture/ADR docs, and the generated API reference. See ADR-004.

🔄 Releases

Managed by release-please: conventional commits drive semantic versioning and an autogenerated NEWS.md.

• Configuration: release-please-config.json
• Version source: uvr.toml

📂 Project Structure

.
├── src/
│   └── package_name/              # Source package
│       ├── __init__.r
│       ├── hello.r                # Example module (replace with real code)
│       └── __tests__/             # Test suite for the example module
│           ├── __init__.r
│           ├── helper-module.r
│           └── test-hello.r
├── scripts/                       # Helper scripts run via `uvr run` (tests, API reference generation)
├── data-raw/                       # Raw data used in the project (if applicable)
├── docs/                           # Documentation site (Quarto website, see ADR-004)
│   ├── _quarto.yml                # Hand-authored Quarto website project
│   ├── index.qmd                  # Home page ({{< include _readme.md >}})
│   ├── architecture/               # Hand-written: architecture overview + ADRs
│   │   ├── index.md
│   │   └── adr/
│   ├── reference/                  # Generated by rd2qmd (gitignored, rebuilt by `just docs-build`)
│   └── html/                      # Rendered site output (gitignored; deployed to GitHub Pages)
├── notebooks/                     # Quarto notebooks
│   └── demo.qmd
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                # Lint / test / build
│   │   ├── generate-docs.yml     # Generate and deploy docs
│   │   ├── release-please.yml    # Automated releases
│   │   └── update-citaton-date-released.yml     # Update date-released in CITATION.cff on new release
│   ├── ISSUE_TEMPLATE/            # Bug report and feature request templates
│   ├── pull_request_template.md
│   └── dependabot.yml             # Weekly GitHub Actions updates
├── .devcontainer/                 # Dev container configuration
│   ├── devcontainer.json
│   └── Dockerfile
├── .vscode/                       # Recommended extensions and editor settings
├── uvr.toml                       # Project metadata + dependencies (uvr)
├── uvr.lock                       # Locked dependency versions (uvr)
├── .r-version                     # Pinned exact R version (uvr)
├── .Rprofile                      # Adds .uvr/library to .libPaths() in interactive sessions (uvr)
├── air.toml                       # Formatter configuration (air)
├── jarl.toml                      # Linter configuration (jarl)
├── ry.toml                        # Static checker configuration (ry)
├── README.md                      # Project overview (you are here)
├── CITATION.cff                   # Citation metadata
├── CONTRIBUTING.md                # Contribution guidelines
├── CODE_OF_CONDUCT.md             # Code of conduct
├── CLAUDE.md                      # Guidance for AI coding assistants
├── LICENSE                        # License
├── NEWS.md                        # Generated by release-please (post-release)
├── .pre-commit-config.yaml         # Git hooks configuration (run via prek)
├── .release-please-manifest.json  # Release-please state
├── release-please-config.json     # Release-please configuration
├── justfile                       # justfile containing recipes for common tasks
├── .editorconfig                  # Ensures consistent code style across editors
└── .gitignore

Note that while it is common practice to keep the config files at the root of the repository, and this is what I recommend, it is possible to customise the location of some of them if you prefer (e.g. the path to release-please-config.json [can be specified in the release-please.yml file for the GitHub action] (https://github.com/googleapis/release-please-action?tab=readme-ov-file#advanced-release-configuration).

🤝 Contributing

Use conventional commit messages (feat:, fix:, docs:, etc.). Ensure:

• Lint, format & ry check clean
• Tests pass
• Docs build without warnings
• ADR drafted for architecturally significant changes

Suggestions and improvements to this template are very welcome — feel free to open an issue or pull request if you spot something that could be refined, added or removed.

📖 Citation

If used in research, cite via CITATION.cff.

🛡 License

BSD-3-Clause – see LICENSE.

Happy coding! 🚀