rpx documentation

Start a project

Create an R package or legacy project with the interactive rpx initializer.

Run the interactive initializer:

Terminal
rpx init

rpx guides you through creating a project, resolves its dependencies, and prepares its isolated library. Choose a new or empty directory for the project.

Project types

  • R package — Organizes your code into reusable functions that you can load from the project library. Suitable for libraries, applications, and analyses. rpx installs the package alongside its dependencies.
  • Legacy project — Supports existing project structures that are not R packages. rpx manages their dependencies without installing the project itself.

The project type is stored in DESCRIPTION. Legacy projects are marked with:

text
Config/rpx/type: project

Without this field, rpx treats the project as an R package. Both types declare dependencies in DESCRIPTION and record the resolved package set in rpx.lock.

Project setup

The initializer lets you configure:

  • Project location and metadata.
  • License.
  • Base package repository: rrepo or CRAN.
  • Development tools such as testthat, roxygen2, and devtools.
  • Git initialization when the project is not already inside a Git worktree. Git must be installed to use this option.
  • A GitHub Actions workflow to publish an R package source archive to rrepo and GitHub Releases.

Publishing a package

For R packages, select the optional publishing workflow in the wizard or pass --publish:

Terminal
rpx init mypkg --publish

This creates .github/workflows/release.yml. Push a tag such as v0.1.0 that matches the Version field in DESCRIPTION to build a source tarball, upload it to rrepo, and attach it to a GitHub Release. The workflow does not build binaries. Publishing is not available for legacy projects (--type project).

Before pushing a release tag, configure these GitHub Actions secrets:

  • RREPO_REPOSITORY_URL: the canonical URL https://rrepo.dev/<org-slug>/<repo-slug> (not a legacy subdomain URL).
  • RREPO_API_KEY: an API key with packages:write access.

See Publish packages for repository upload details.

Development tool setup

Select tools in the wizard, or pass --with once for each tool:

Terminal
rpx init mypkg --with testthat --with roxygen2

Supplying --with replaces the wizard's development-tool prompt. Supported values are testthat, roxygen2, and devtools; repeated selections are applied once. All selected tools are added to Suggests, resolved, and installed in the project library.

For R packages:

  • testthat creates tests/testthat.R and tests/testthat/test-example.R, configures edition 3 in DESCRIPTION, and requires testthat 3.0.0 or newer. Replace the starter test with tests for your package.
  • roxygen2 creates R/, enables Markdown documentation and UTF-8 encoding in DESCRIPTION, and initializes a roxygen-managed NAMESPACE.
  • devtools installs the development toolkit without additional setup files.

From the package directory, run tests or generate documentation with:

Terminal
rpx run Rscript -e 'testthat::test_local()'
rpx run Rscript -e 'roxygen2::roxygenise()'

The first documentation run records the roxygen2 version in DESCRIPTION (Config/roxygen2/version, or RoxygenNote with older roxygen2 releases).

For legacy projects (--type project), roxygen2 and devtools are available as dependencies only. Testthat is omitted from the wizard and --type project --with testthat is rejected because the generated runner requires an installed R package.

Ready to work

When setup finishes, the project files, lockfile, and library are ready. From the project directory, you can add packages or start R:

Terminal
rpx add digest
rpx run R