Developing an R package

Package content

First, create a new empty RStudio project. Let’s called it pkg. To create a new package structure, run rcompendium::new_package().

By default, the following content is created:

pkg/                              # Root of the package
│
├── pkg.Rproj                     # RStudio project (created by user, optional)
│
├── .git/                         # GIT tracking folder
├── .gitignore                    # List of files/folders to be ignored by GIT
|                                 # (specific to R language)
|
├── .github/                      # (optional) GitHub Actions settings
│   └── workflows/
│       ├── pkgdown.yaml          # Configuration file to build & deploy website
│       ├── R-CMD-check.yaml      # Configuration file to check & test package
│       ├── render-README.yaml    # Configuration file to render the README.md
│       └── test-coverage.yaml    # Configuration file to report code coverage
│
├── _pkgdown.yaml                 # (optional) User website settings
│
├── R/                            # R functions location
│   ├── fun-demo.R                # Example of an R function (to remove)
│   └── pkg-package.R             # Dummy R file for package-level documentation
│
├── man/                          # R functions helps (automatically updated)
│   ├── print_msg.Rd              # Documentation of the demo R function
│   ├── pkg-package.Rd            # Package-level documentation
│   └── figures/                  # Figures for the README 
│       └── package-sticker.png   # Package sticker template
│
├── tests/                        # (optional) Units tests location
│   ├── testthat.R                # Units tests settings
│   └── testthat/                 # Units tests location
│       └── test-demo.R           # Units tests for the demo function (to remove)
|
├── vignettes/                    # (optional) Vignettes location
│   └── pkg.Rmd                   # Get started tutorial                          [*]
│
├── DESCRIPTION                   # Project metadata                              [*]
├── LICENSE.md                    # Content of the GPL (>= 2) license (default)
├── NAMESPACE                     # Automatically generated
├── .Rbuildignore                 # List of files/folders to be ignored while 
│                                 # checking/installing the package
├── inst/
│   ├── CITATION                  # BiBTeX entry to cite the package              [*]
│   └── package-sticker/
│       ├── package-sticker.R     # Code to generate package sticker
│       └── r_logo.png            # R logo
│
├── README.md                     # GitHub README (automatically generated)
└── README.Rmd                    # GitHub README                                 [*]


[*] These files are automatically created but user needs to manually add 
    some information.

In addition, a new GitHub repository will be created directly from R. It will be available at: https://github.com/{{account}}/pkg/ (where {{account}} is either your GitHub account or a GitHub organization). A few minutes later, the website (pkgdown) will be deployed at: https://{{account}}.github.io/pkg/.

Package metadata

Package: pkg
Type: Package
Title: The Title of the Project                                              [*]
Version: 0.0.0.9000
Authors@R: c(
    person(given   = "John",
           family  = "Doe",
           role    = c("aut", "cre", "cph"),
           email   = "john.doe@domain.com",
           comment = c(ORCID = "9999-9999-9999-9999")))
Description: A paragraph providing a full description of the project (on     [*] 
    several lines...)
URL: https://github.com/jdoe/pkg
BugReports: https://github.com/jdoe/pkg/issues
License: GPL (>= 2)
Encoding: UTF-8
Roxygen: list(markdown = TRUE)
RoxygenNote: 7.1.2
VignetteBuilder: knitr
Suggests: 
    knitr,
    rmarkdown,
    testthat (>= 3.0.0)
Config/testthat/edition: 3


[*] Title and Description must be adapted by user.

Recommended workflow

The recommended workflow is:

1. Implement new function in R/
2. Document function using the roxygen syntax
3. Update functions doc (man/) and NAMESPACE with devtools::document()
4. Update list of required packages in DESCRIPTION with rcompendium::add_dependencies()
5. Implement units tests using testthat
6. Edit vignette to illustrate the new feature
7. Check and test the package with devtools::check()

You can also provide data with your package. See ?usethis::use_data.

We strongly recommend that you read the book R packages by Hadley Wickham and Jenny Bryan.

Resources

• R packages by Hadley Wickham and Jenny Bryan
• Writing R extensions by the R Development Core Team
• Extending R by John M. Chambers