r-package-dev

name	r-package-dev
description	Develop and maintain R packages with package-aware scaffolding, testing, checks, changelogs, contributor environments, and release hygiene. Use for R package feature work, fixes, PR prep, and release tasks.
argument-hint	["task or package area"]
paths	["**/DESCRIPTION","**/NAMESPACE","**/R/**/*.R","**/tests/testthat/**/*.R","**/man/**/*.Rd","**/vignettes/**/*.Rmd","**/vignettes/**/*.qmd"]

R Package Dev

Work in package repos with explicit versioning, paired tests, and a clean path from code change to release surface.

Quick start

1. Inspect DESCRIPTION, NAMESPACE, CHANGELOG.md, R/, tests/, and any CI config before coding.
2. Read references/usethis-testthat-workflow.md.
3. Read references/package-workflow.md.
4. Read references/model-class-support.md when the package exposes model-specific methods or reporting helpers.
5. Read references/tidymodels-package-surfaces.md when the package exports parsnip specs, recipes, workflows, resampling/tuning helpers, or yardstick metric wrappers.
6. Read references/marginaleffects-package-extension.md when the package must support marginaleffects, expose post-estimation helpers, or compare its approach with emmeans support.
7. Read references/shiny-html-css-package-components.md when the package exports Shiny UI helpers, custom inputs, htmlDependency() assets, theme-aware bslib components, accessibility-sensitive Shiny components, or reusable motion/responsive layout helpers.
8. Read references/shinytest2-package-testing.md when the package owns a Shiny app, demo app, browser-level app contract, or package-hosted app tests under tests/testthat/.
9. Read references/performance-benchmarking-package-surfaces.md when the package change has a performance motivation, needs profvis or bench::mark() evidence, or owns a Shiny app that needs profiling or shinyloadtest.
10. Read references/reusable-analytical-figure-components.md when the package exports canonical ggplot helpers, plotly or ggiraph wrappers, Shiny analytical-figure modules, or shared figure components that should work in both static and interactive surfaces.
11. Read references/reusable-interactive-table-components.md when the package exports reactable or DT wrappers, Shiny table modules, linked table/plot components, or reusable analytical table dependencies.
12. Read references/renv-package-workflows.md when the repo carries renv.lock, needs a stable contributor or CI package environment, or mixes package work with vignettes, Quarto, or app surfaces that need reproducible dependencies.
13. Read references/future-furrr-package-surfaces.md when the package exports parallel helpers, future/furrr wrappers, or async Shiny helpers that rely on background workers.
14. Read references/httr2-api-package-surfaces.md when the package wraps APIs, exposes request helpers, parses JSON responses, or manages authentication, retry, or throttling posture.
15. Read references/vetiver-plumber-service-packages.md when the package repo owns pinned model artifacts, a Plumber router, or a vetiver prediction API surface.
16. Create a feature/<topic> branch when branch work is requested.
17. Let usethis::use_*() manage package scaffolding and file-pair creation whenever the task changes package structure.
18. Keep functional changes paired with testthat coverage, roxygen updates, and the required changelog/version surfaces.

Workflow

1. Reconfirm the package contract

• Identify the public user-facing function, method, or file surface being changed.
• Check the package’s existing style, naming, dependency posture, and current testthat edition.
• Keep the write set small unless the user asks for a broader refactor.

2. Let usethis manage package structure

• Work from the active package project.
• Use usethis::use_testthat() when test infrastructure is missing or being modernized.
• Use usethis::use_r() and usethis::use_test() to keep R/ and tests/testthat/ file pairs aligned.
• Use usethis::use_test_helper() for shared helper functions or custom expectations.
• Use usethis::use_package(), use_package_doc(), and use_roxygen_md() when dependency or documentation surfaces need structured updates.

2b. Package Shiny UI assets deliberately

• When package code exports reusable Shiny UI components, keep CSS and JavaScript in formal dependency objects instead of scattering repeated tags$link() and tags$script() calls across helpers.
• Keep htmltools::htmlDependency() creation at runtime so built binaries do not capture the wrong machine path.
• When the component should react to bs_theme() or runtime theme updates, move from static dependencies toward bslib::bs_dependency() or bs_dependency_defer().
• Keep app-local singleton(tags$head(...)) patterns for examples, prototypes, or package demo apps; for exported components, dependency objects are usually the steadier contract.

2b2. Keep package-owned Shiny browser tests deliberate

• Current use_shinytest2() documentation says it can initialize the package-side browser-test infrastructure, including tests/testthat.R, setup helpers, ignore entries for new debug screenshots, and a Suggests entry. Keep that setup explicit when a package starts owning app-level browser contracts.
• Current use_shinytest2_test() and record_test() documentation positions recorded browser tests as scaffolding. Keep the recorded test file, then trim it into the smallest contract that matters for the package-owned app.
• Current package guidance says directory-backed apps can live under inst/ or tests/testthat/apps/, while small inline shinyApp() objects are also possible inside tests. Keep the app location explicit in AppDriver$new() so the browser boundary stays readable.
• Current package guidance also points to load_app_support(), local_app_support(), and with_app_support() when an app carries its own ./R support files. Keep that support loading visible instead of assuming the package namespace already covers it.
• Keep module and server logic covered with ordinary testthat expectations and testServer(), then let shinytest2 own the browser contract: navigation, downloads, uploads, rendered HTML, screenshots, and exported values.
• Current package guidance says AppDriver creation calls skip_on_cran() during CRAN testing. Keep CI and CRAN posture deliberate so browser tests continue to protect the package even when CRAN skips them.

2b3. Keep performance diagnostics evidence-based

• Current profvis documentation fits representative workflow profiling, while current bench::mark() documentation fits narrow implementation comparisons. Keep those surfaces separate so package contributors can tell whether they are finding a hot path or comparing candidate fixes.
• Keep benchmark equivalence checks visible through check = TRUE when exported helpers are being compared.
• Team doctrine: benchmarking scripts and profiling helpers belong in clearly labeled diagnostics, examples, or developer tooling rather than brittle unit tests with machine-specific runtime thresholds.
• When the package owns a Shiny app, keep shinytest2, profvis, and shinyloadtest as three different signals: browser behavior, single-session hot paths, and concurrent-user capacity.

2c. Package analytical figure components in layers

• When a package exports analytical figures, keep the canonical static plot helper separate from any Shiny or htmlwidget wrapper. A strong default split is: data-prep helper, ggplot helper, optional Shiny output/render wrapper, and optional ggplotly() or girafe() adapter.
• Keep the static ggplot surface as the stable contract for examples, tests, exports, and downstream reuse; let the interactive layer wrap that object at the boundary where the app actually needs widget behavior.
• If the package exports a figure module, keep the module server on moduleServer() so the reactive behavior remains testable with testServer().
• When a figure component carries selection, tooltip, or linked-view state, expose the contract explicitly through names such as source, key columns, data_id, or tooltip fields instead of hiding that logic in untracked side effects.
• Keep output/render pairs aligned for the chosen surface: plotOutput() / renderPlot(), plotlyOutput() / renderPlotly(), and girafeOutput() / renderGirafe(). Keep width, height, and fill posture visible in the exported API so package consumers can place the component predictably.

2d. Package interactive table components in layers

• Keep the canonical reporting or analytical tibble separate from any widget wrapper. A steady default split is: data-prep helper, normalized table tibble, optional static reporting helper, and optional reactable or DT wrapper.
• Keep the state contract explicit in the exported API: key column, selected-row semantics, filtered-row semantics, sort/page persistence, and whether search or column filters are purely display state or part of a documented export contract.
• For reactable components, keep state and update hooks visible through reactableOutput() / renderReactable(), getReactableState(), and updateReactable() when the component expects Shiny-driven refreshes.
• For DT components, keep the Shiny wrapper and proxy/update surface visible through DTOutput() / renderDT() and the documented proxy or replace-data flow when the table is expected to refresh without a full re-render.
• Keep engine-specific styling close to the table helper: reactableTheme() and colDef() for reactable, documented options and callbacks for DT. Package-level CSS and dependencies should refine a clear widget contract rather than substitute for one.
• If the package exports a linked table/plot module, keep the shared keys and selected-row contract explicit and testable with moduleServer() / testServer().

2d2. Keep tidymodels package surfaces inspectable

• When a package exports modeling constructors, keep the public contract explicit: model spec constructor, recipe constructor, workflow constructor, tuning helper, and finalized fit helper do not all need to be the same function.
• Current workflows documentation describes workflows as containers for preprocessing and model information. For package APIs, a strong default is often to export unfitted workflow constructors and test them separately from final fit helpers. This is a team inference grounded in the current tidymodels layer design.
• Current recipes documentation says prep() estimates preprocessing parameters from training data and bake() applies them later. Package examples and tests should respect that training/new-data boundary rather than precomputing preprocessing globally in a hidden package constant.
• Current tune documentation keeps tuning, finalization, and final held-out evaluation as separate stages. Package helpers should keep those stages visible enough that tests can verify each one deterministically on small fixtures.
• When the package wraps binary classification metrics through yardstick, keep the event-level contract explicit so downstream users can tell which class is treated as positive.

2e. Keep renv deliberate in package repos

• In package repositories, keep the package contract visible: DESCRIPTION, NAMESPACE, tests, and CI still define what the package needs to build and check. When the repo also carries renv, treat the lockfile as the contributor and operational environment surface that supports development tools, examples, vignettes, apps, and reproducible local or CI runs.
• Current renv::snapshot() documentation says explicit snapshot mode records packages from DESCRIPTION, while implicit follows dependencies(). A strong default for package repositories is often settings$snapshot.type("explicit") so the lockfile stays centered on the declared package contract; this is a team doctrine / inference built from the official snapshot-type definitions.
• After adding or changing package dependencies, testing helpers, vignette/report dependencies, or app/demo dependencies that the repo genuinely relies on, refresh the lockfile with renv::snapshot().
• Run renv::status() before release-sensitive work or when CI and local behavior diverge. Current documentation recommends resolving any reported issues before further work.
• Keep package sources restorable. Current renv package-source guidance says the lockfile learns source information from installed metadata such as RemoteType and Repository, with the cellar available as an escape hatch for packages without a standard remote source.
• If the package repo uses renv in CI, current renv CI guidance centers on restoring from renv.lock and caching the project library plus global renv cache when that environment is part of the build contract.
• When the same repository carries materially different modes, such as package development plus a Shiny demo app, renv project profiles can separate those environments. Keep that split intentional and small.
• Current renv Docker guidance notes that system libraries, compilers, and the operating system still affect runtime behavior. If package examples, compiled dependencies, or deployment targets are system-sensitive, capture that layer too.

2f. Keep API-client package surfaces layered and inspectable

• Current httr2 wrapping-APIs guidance is organized around a core request function, endpoint wrappers, error handling, authentication, and rate limiting. Package APIs become easier to maintain when those layers remain visible instead of collapsing request construction, performance, and parsing into one monolithic helper.
• Keep one request-constructor layer that knows the base URL, common headers, authentication posture, and shared retry/throttle settings. Then keep endpoint helpers narrow so they mostly add path pieces, query parameters, or request bodies.
• Keep response checking and response parsing explicit. resp_body_json() and jsonlite flattening choices should be visible enough that tests can pin the parse contract to small fixtures.
• Current req_headers() documentation notes that Authorization is always redacted in printed output. Team doctrine: keep debug surfaces inspectable and safe by leaning on request-object printing rather than hand-logging raw credential-bearing headers.
• When packages expose polling or refresh helpers for Shiny consumers, keep the freshness contract explicit so downstream apps can choose between reactivePoll()-style checks and simpler timed invalidation.

2f2. Keep service packages layered when they publish models or artifacts

• Current pins documentation keeps board choice, artifact metadata, and versioning explicit through pin_write(), pin_read(), and pin_versions(). Keep those artifact surfaces visible in package helpers instead of hiding them in package startup code.
• Current vetiver_pin_write() documentation says check_renv = TRUE can record training-time package information and later compare it on read. Keep that environment-compatibility surface deliberate when the same repo owns both training and serving responsibilities.
• Current vetiver_api() documentation says deployable model objects are attached to a Plumber router with an explicit prediction path and prototype checks. Keep router factories narrow so the route path, prediction options, and prototype checking remain inspectable.
• Current plumber routing documentation keeps verb and path declarations explicit, and current rendering-output documentation keeps serializers explicit. Keep route definition and response-format choices close to the helper that assembles the router.
• Team doctrine: keep training code, artifact pinning, and router assembly in separate helpers whenever a package repo owns a model service.

2g. Keep future plans and worker assumptions under caller control

• Current future package-developer guidance says to refrain from setting plan() inside a function. Package users may already have a parallel strategy in place, and changing it inside package code can disrupt later work.
• The same guidance says well-written future code should not assume where or when futures are resolved. Keep package APIs backend-agnostic unless the contract truly depends on one runtime.
• If package code genuinely must set a plan for an example, demo app, or tightly scoped helper, current guidance says to restore the old plan when the function exits, including on error.
• When a package exports furrr helpers, keep furrr_options()-level controls inspectable whenever seeds, globals, packages, or chunking materially affect correctness or performance.
• Team doctrine: in package tests and examples, keep the parallel contract visible and small. Constructor logic, sequential fallbacks, and parallel behavior are easier to trust when they are testable in isolation.

3. Implement code and tests together

• Add or update tests in the same pass as the code change.
• Keep pkg::fn() calls explicit unless the package already has a different house style.
• Prefer current testthat edition-3 expectations and fixtures for new work.
• Use snapshot tests or explicit warning/message expectations when output is part of the contract.
• When adding marginaleffects support for a new model class, keep the extension contract and its tests visible: coefficients, replacement coefficients, variance-covariance extraction, predictions, and post-estimation smoke tests should all move together.

4. Keep versioning and release surfaces aligned

• Add the required CHANGELOG.md entry before any git workflow that ends in commit, push, or PR.
• Reflect version bumps consistently in DESCRIPTION and any other package-facing version surfaces when the repo expects versioned releases.
• Keep release notes aligned with the changelog when tags or GitHub releases are part of the workflow.

5. Validate in layers

• Start with targeted testthat::test_file() runs for the changed surface.
• When the package exports HTML/CSS/Shiny components, inspect the rendered tags and dependency list with htmltools::renderTags() inside tests or development checks so duplicated assets and missing head content surface early.
• When the package exports analytical-figure helpers, test the static surface first: assert that the helper returns the expected ggplot or structured data contract before testing plotly, ggiraph, or module wrappers around it.
• Run devtools::document() when roxygen output changes.
• Run devtools::test() and devtools::check() when the scope warrants package-level verification.
• Enable parallel testing only when test files are isolated enough for it to be deterministic.

6. Finish the repo workflow cleanly

• Prefer gh when available for PR work.
• Review the staged diff before commit.
• Keep changelog/version updates in the staged diff whenever the workflow requires them.
• Prefer current usethis::use_github_action() patterns over deprecated GitHub Action helpers when CI scaffolding changes.

Coordination notes

• Reach for the a repo-local package-management or release-governance skill when the task is specific to that package’s release and security rules.
• Reach for /r-model-builder when package work is mainly about model helpers rather than package workflow.
• Reach for /r-stats when the main challenge is statistical method choice or reusable analytical helper behavior.

Resources

• references/usethis-testthat-workflow.md
• references/package-workflow.md
• references/model-class-support.md
• references/tidymodels-package-surfaces.md
• references/marginaleffects-package-extension.md
• references/shiny-html-css-package-components.md
• references/shinytest2-package-testing.md
• references/performance-benchmarking-package-surfaces.md
• references/reusable-analytical-figure-components.md
• references/reusable-interactive-table-components.md
• references/renv-package-workflows.md
• references/future-furrr-package-surfaces.md
• references/httr2-api-package-surfaces.md
• references/vetiver-plumber-service-packages.md