name: developing-packages-r description: | Building robust R packages with modern tidyverse patterns. Use this skill when creating or maintaining R packages, designing APIs, choosing dependencies, implementing input validation, writing error messages, or deciding between internal and exported functions. Covers dependency strategy, tidyverse API design patterns, validation approaches, error handling with cli/rlang, testing levels, and documentation priorities.

Developing Packages R

This skill covers building robust R packages with modern patterns and best practices.

Dependency Strategy

When to Add Dependencies vs Base R

Add dependency when:

• Significant functionality gain
• Maintenance burden reduction
• User experience improvement
• Complex implementation (regex, dates, web)

Use base R when:

• Simple utility functions
• Package will be widely used (minimize deps)
• Dependency is large for small benefit
• Base R solution is straightforward

See dependency-decisions.md for example decisions.

Tidyverse Dependency Guidelines

API Design Patterns

Modern Tidyverse API

See api-design.md for:

1. Use .by for per-operation grouping
2. Use {{ }} for user-provided columns
3. Use ... for flexible arguments
4. Return consistent types (tibbles, not data.frames)

Input Validation Strategy

Validation level depends on function type:

See validation-patterns.md for examples.

Error Handling Patterns

Good error messages are:

• Specific - say what went wrong
• Actionable - say how to fix it
• Traceable - include function context

See error-handling.md for:

• cli package for user-friendly messages
• rlang for developer tools
• Including function name in errors

Internal vs Exported Functions

Export Function When:

• Users will call it directly
• Other packages might want to extend it
• Part of the core package functionality
• Stable API that won't change often

Keep Function Internal When:

• Implementation detail that may change
• Only used within package
• Complex implementation helpers
• Would clutter user-facing API

See internal-vs-exported.md for examples.

Testing Strategy

Testing Levels

See testing-patterns.md for examples.

Documentation Priorities

Must Document:

• All exported functions
• Complex algorithms or formulas
• Non-obvious parameter interactions
• Examples of typical usage

Can Skip Documentation:

• Simple internal helpers
• Obvious parameter meanings
• Functions that just call other functions

source: Sarah Johnson's gist https://gist.github.com/sj-io/3828d64d0969f2a0f05297e59e6c15ad