Skip to contents

templ.rpkg

Overview

Artalytics R Package Template — Template repository for creating new Artalytics R packages.

This README is intentionally written as a high-quality template:

  • It documents the expectations for how Artalytics packages are structured, built, tested, and released.
  • It is designed to be copy/paste-adaptable to any new package created from this template.
  • When initializing a new package, replace placeholder tokens and remove “template-only” notes (see TEMPLATE_USAGE.md).

Template Initialization (First 10 Minutes)

If you created a new repo from this template, do this before writing code:

  1. Replace placeholder tokens:
    • templ.rpkg → your real package name
    • Artalytics R Package Template → your package title
    • Template repository for creating new Artalytics R packages. → your package description
  2. Rename placeholder files:
    • R/templ.rpkg-package.R → R/<package>-package.R
    • tests/testthat/test-templ.rpkg-package.R → tests/testthat/test-<package>-package.R
  3. Regenerate docs and ensure clean build:
    • Run devtools::document()
    • Run devtools::check()
  4. Delete template-only files when done:
    • TEMPLATE_USAGE.md
    • The pointer line in AGENTS.md (or delete AGENTS.md entirely if your repo does not use it)

See TEMPLATE_USAGE.md for a scripted (POSIX shell) option.

Where This Package Fits (Artalytics Ecosystem)

Artalytics follows a layered architecture with strict dependency boundaries:

┌─────────────────────────────────────────────────────────┐
│                     appPlatform                         │
│              (Main Shiny Application)                   │
├─────────────────────────────────────────────────────────┤
│   modArtist  │  modBrowse  │  modUpload  │  modGallery  │
│                    (Shiny Modules)                      │
├─────────────────────────────────────────────────────────┤
│  artopenai  │  artgemini  │ artpixeltrace │ artcurator  │
│               (API & Domain Packages)                   │
├─────────────────────────────────────────────────────────┤
│                       artutils                          │
│           (High-level utilities & data access)          │
├─────────────────────────────────────────────────────────┤
│                        artcore                          │
│     (Low-level: DB connections, CDN interfaces)         │
└─────────────────────────────────────────────────────────┘

Dependency rules (internal Artalytics packages):

  • artcore: must not depend on any other Artalytics package
  • artutils: may depend only on artcore
  • API/domain packages (artopenai, artgemini, etc.): may depend on artcore and/or artutils
  • Shiny module packages (mod*): may depend on artutils (and thus artcore), but never on other modules
  • appPlatform: may depend on modules + utilities as needed

If your package violates these boundaries, it will create circular dependencies and break deploy/install flows.

Installation

Install from GitHub (internal Artalytics packages)

Use pak for fast, reliable installs:

install.packages("pak")
pak::pkg_install("artalytics/templ.rpkg")

If your package depends on private repos, you will need a GitHub PAT available as GITHUB_PAT.

Install dependencies (development) 

install.packages("pak")
pak::pkg_install(c("devtools", "roxygen2", "testthat", "lintr", "covr"))

Usage

Artalytics codebases require explicit namespacing:

# Prefer this:
templ.rpkg::some_function(...)

# Avoid this:
library(templ.rpkg)
some_function(...)

If you add user-facing functions, document them with roxygen2 and include examples that can run during R CMD check.

API (Fill This In)

When you turn this template into a real package, document the public surface area here (exported functions only).

Example format:

Function What it does
templ.rpkg::some_function() One-line description of behavior and when to use it
templ.rpkg::another_function() One-line description

Guidelines:

  • Prefer a small number of well-named exported functions.
  • Keep internal helpers unexported (and test them through exported behavior).
  • Keep function names descriptive and consistent (snake_case).

Configuration (Environment Variables)

All secrets and environment-specific values must be provided via environment variables (never hardcode secrets).

Document required/optional variables here. Keep the list explicit and narrow:

# Example only — replace with your package’s actual variables.
# Put these in ~/.Renviron for local dev (never commit).
ART_EXAMPLE_KEY="..."
ART_EXAMPLE_MODE="dev"

Documentation

Artalytics expects documentation to be “production-grade” from day one:

  • Roxygen2 for exported functions and user-facing objects
  • Optional vignettes for tutorials / deep guides

Local commands:

devtools::document()
devtools::build_vignettes()

If this package has a website, configure pkgdown in _pkgdown.yml and build locally:

pkgdown::build_site()

Package Layout (Standard)

Artalytics packages follow the standard R package structure:

  • R/ — R source code (functions, module definitions, internal helpers)
  • man/ — generated .Rd docs (via roxygen2)
  • tests/testthat/ — unit tests (testthat, edition 3)
  • inst/ — installed assets (data, templates, JS/CSS, etc.)
  • vignettes/ — optional long-form docs (Rmd/Quarto)
  • .github/workflows/ — CI: R CMD check, lint, coverage, etc.

Keep “source of truth” logic in R/. Anything in man/ should be treated as generated output.

Coding Standards (Artalytics Defaults)

These are the platform expectations for all packages:

  • data.table-first: use data.table for tabular data (avoid tibbles/dplyr).
  • Native pipe: use base R |> (avoid magrittr %>%).
  • String ops: prefer stringr::str_* functions over base gsub/grepl/... (except paste0() for concatenation).
  • Explicit namespaces: prefer pkg::fn() throughout (avoid attaching many packages).
  • snake_case: for function and variable names.
  • Compact code: optimize for readability + fewer lines, especially in Shiny/module code.

For sensitive operations, ensure you follow:

  • Env vars for secrets: never commit keys/tokens; use .Renviron locally and CI secrets in workflows.

Database & CDN Access (Platform Patterns)

If your package touches the database or CDN:

  • Database connections must use artcore::..dbc() and artcore::..dbd()
  • Prefer querying through artutils when possible (higher-level data access)
  • CDN URLs should be produced via artcore/artutils helper functions (no ad-hoc URL building)

If this package is artcore, it must remain dependency-free (internally) and should not reach “up” into higher layers.

Testing

All packages should have tests for exported functions.

Unit tests (testthat)

Run tests:

devtools::test()

Coverage

Mocking policy (high-level)

  • Allowed: httptest2 (external HTTP APIs only), shinytest2 (Shiny apps/modules)
  • Never mock: database connections, CDN assets, internal platform infrastructure

Development Commands (Local)

The minimum local loop:

devtools::document()
lintr::lint_package()
devtools::test()
devtools::check()

R CMD check (CI parity)

devtools::check() is the closest to what CI runs; use it before PRs.

CI (GitHub Actions)

This template ships standard workflows under .github/workflows/:

  • R-CMD-check.yaml — build + test gate
  • lint.yaml — lintr::lint_package()
  • test-coverage.yaml — coverage reporting (if configured)

Secrets policy:

  • Put dev secrets in .Renviron (never commit)
  • Put CI secrets in GitHub Actions secrets (e.g., GITHUB_PAT, CODECOV_TOKEN)

Release Process (Suggested)

  1. Update NEWS.md with user-visible changes.
  2. Bump version in DESCRIPTION (prefer semver-like discipline).
  3. Ensure devtools::check() passes locally.
  4. Merge to main.
  5. Tag a release if the package is consumed by pinned dependencies.

Support / Ownership

  • File bugs via the repo issue tracker (BugReports in DESCRIPTION).
  • For security concerns, do not open public issues—follow the internal reporting process.