Skip to contents

Quickstart

Source: vignettes/quickstart.qmd

This quickstart guide walks through the most common arthelpers tasks you’ll encounter during R package development.

Task 1: Brand a New Package

When starting a new R package, set up consistent Artalytics branding in under 30 seconds:

library(arthelpers)

# From your package root directory (where _pkgdown.yml exists)
setup_favicon()

What happens: 1. Detects that you’re working on a pkgdown site 2. Downloads the Artalytics logo to man/figures/logo.png 3. Generates favicon set to pkgdown/favicon/ via API 4. Creates: favicon.ico, favicon-16x16.png, favicon-32x32.png, apple-touch-icon.png, etc.

Verify the results:

# Check that logo was downloaded
fs::file_exists("man/figures/logo.png")
#> TRUE

# Check favicon files
fs::dir_ls("pkgdown/favicon")
#> pkgdown/favicon/android-chrome-192x192.png
#> pkgdown/favicon/apple-touch-icon.png
#> pkgdown/favicon/favicon-16x16.png
#> pkgdown/favicon/favicon-32x32.png
#> pkgdown/favicon/favicon.ico

Already have files?

# Force regeneration (overwrites existing)
setup_favicon(overwrite = TRUE)

Task 2: Debug Package Loading Issues

When a package isn’t loading correctly or dependencies are missing, diagnose with describe_env():

library(arthelpers)

# Print full environment summary
describe_env()

Example output:

=== Artalytics Environment Summary ===
Active package: arthelpers
Package version: 0.0.1

-- Non-sensitive environment variables --
R_HOME=/usr/lib/R
PATH=/usr/local/bin:/usr/bin
LANG=en_US.UTF-8

-- Direct GitHub dependencies (from Remotes) --
* artalytics/artcore  (installed: v0.7.1)

-- System info --
R.version: R version 4.3.1 (2023-06-16)
Platform: x86_64-pc-linux-gnu
OS: Linux
User: developer
Timezone: UTC

Programmatic use:

# Get specific info without printing
env <- describe_env(quiet = TRUE)

# Check if artcore is installed
if ("artcore" %in% names(env$deps_versions)) {
  message("artcore version: ", env$deps_versions["artcore"])
} else {
  warning("artcore not installed!")
}

# List all GitHub dependencies
cat("GitHub deps:", paste(env$deps_github, collapse = ", "), "\n")

Task 3: Screenshot Shiny Apps

Capture visual snapshots of Shiny apps for documentation, visual testing, or bug reports.

Basic Screenshot 

library(shiny)
library(arthelpers)

# Create a simple app
app <- shinyApp(
  ui = fluidPage(
    h1("Hello World"),
    plotOutput("plot")
  ),
  server = function(input, output) {
    output$plot <- renderPlot({
      plot(1:10)
    })
  }
)

# Take screenshot (saved to temp file by default)
path <- screenshot_app(app)
#> Screenshot saved to: /tmp/RtmpXXXXXX/fileXXXX.png

# Specify output file
screenshot_app(app, file = "docs/app-preview.png")

Choose Your Method

Use webshot2 (default) for static UI:

screenshot_app(app, method = "webshot2")
  • Fastest
  • Best for non-interactive screenshots
  • Requires Chrome/Chromium

Use shinytest2 for reactive apps:

screenshot_app(app, method = "shinytest2", wait_for_idle = TRUE)
  • Waits for Shiny reactivity to settle
  • Best when app has loading spinners or delayed rendering
  • Integrates with shinytest2 test framework

Use chromote for maximum control:

screenshot_app(app, method = "chromote", delay = 2)
  • Direct Chrome DevTools Protocol access
  • Best for complex wait logic or custom scenarios
  • Can specify port for debugging

Capture Specific Elements

Screenshot only the plot, not the entire page:

# Target specific element with CSS selector
screenshot_app(app, selector = "#plot", file = "plot-only.png")

# Capture sidebar panel only
screenshot_app(app, selector = ".sidebar", file = "sidebar.png")

Custom Viewport Sizes

Test responsive layouts at different screen sizes:

# Desktop
screenshot_app(app, vwidth = 1920, vheight = 1080, file = "desktop.png")

# Tablet
screenshot_app(app, vwidth = 768, vheight = 1024, file = "tablet.png")

# Mobile
screenshot_app(app, vwidth = 375, vheight = 667, file = "mobile.png")

Adjust Timing

For apps with slow-loading data or animations:

# Wait 3 seconds before screenshot
screenshot_app(app, delay = 3)

# Or use shinytest2's idle detection
screenshot_app(
  app,
  method = "shinytest2",
  wait_for_idle = TRUE,
  load_timeout = 15000  # 15 second timeout
)

Task 4: List Organization Repositories

Generate an up-to-date repository index for documentation:

library(arthelpers)

# Requires GITHUB_PAT environment variable
repos <- get_repo_index()

# View as data.table
print(repos)
#>        repo_name visibility                    description
#> 1:      artcore    private   Infrastructure layer for...
#> 2:     artutils    private   Data access utilities...
#> 3:    artgemini    private   Google Gemini API wrapper...

# Use markdown links in README
cat(repos$repo_md[1:3], sep = "\n")
#> [artcore](https://github.com/artalytics/artcore)
#> [artutils](https://github.com/artalytics/artutils)
#> [artgemini](https://github.com/artalytics/artgemini)

# Filter by visibility
private_repos <- repos[visibility == "private"]
public_repos <- repos[visibility == "public"]

Query different organizations:

# tidyverse repos
tidy <- get_repo_index(org = "tidyverse")

# rstudio repos
rstudio <- get_repo_index(org = "rstudio")

Task 5: Clean Up Test Data

Remove test artworks and artists from database and CDN:

Delete Single Artwork 

library(arthelpers)

# Delete from database only
delete_artwork(
  artwork = "99a61148-1234-5678-90ab-cdef12345678"
)
#> Deleted artwork 99a61148-1234-5678-90ab-cdef12345678 from database

# Delete from database AND CDN
delete_artwork(
  artwork = "99a61148-1234-5678-90ab-cdef12345678",
  delete_cdn = TRUE
)
#> Deleted artwork 99a61148-1234-5678-90ab-cdef12345678 from database
#> Deleted art-vault assets for 99a61148-1234-5678-90ab-cdef12345678
#> Deleted art-data assets for 99a61148-1234-5678-90ab-cdef12345678
#> Deleted thumbnail for 99a61148-1234-5678-90ab-cdef12345678

Delete Entire Artist

WARNING: This deletes the artist AND all their artworks via CASCADE.

# Delete artist and all artworks
delete_artist(
  artist = "746b8207-1234-5678-90ab-cdef12345678",
  delete_cdn = TRUE
)
#> Deleted artist 746b8207-1234-5678-90ab-cdef12345678 from database (cascade deleted 15 artworks)
#> Deleted art-vault assets for 99xxxxxx-...
#> Deleted art-data assets for 99xxxxxx-...
#> ...
#> Deleted artist thumbnail directory for 746b8207-1234-5678-90ab-cdef12345678

Batch Deletion

When deleting multiple records, reuse the database connection:

library(artcore)

# Create connection once
cn <- ..dbc()

# Delete multiple artworks
test_artworks <- c(
  "99a61148-1111-1111-1111-111111111111",
  "99a61148-2222-2222-2222-222222222222",
  "99a61148-3333-3333-3333-333333333333"
)

for (art in test_artworks) {
  delete_artwork(artwork = art, delete_cdn = TRUE, cn = cn)
}

# Close connection
..dbd(cn)

Troubleshooting

setup_favicon() fails

**Error: “No _pkgdown.yml or _quarto.yml found”**

Solution: Run from package root directory where config file exists:

setwd("/path/to/package")
setup_favicon()

Error: “Failed to download logo”

Solution: Check internet connection or try custom URL:

setup_favicon(url = "https://example.com/logo.png")

screenshot_app() blank/empty

Problem: Screenshot is blank or shows “loading…”

Solution: Increase delay or use wait_for_idle:

# Increase delay
screenshot_app(app, delay = 3)

# Or use shinytest2 with idle detection
screenshot_app(app, method = "shinytest2", wait_for_idle = TRUE)

delete_*() not finding records

Problem: “Artwork not found” warning

Solution: Verify UUID format and existence:

library(artcore)
cn <- ..dbc()

# Check if artwork exists
DBI::dbGetQuery(cn,
  "SELECT art_uuid FROM app.artwork_index WHERE art_uuid = '99xxxxxx-...'")

..dbd(cn)

get_repo_index() fails

Error: “Missing GITHUB_PAT”

Solution: Set environment variable:

# In R session
Sys.setenv(GITHUB_PAT = "ghp_xxxxxxxxxxxxxxxxxxxx")

# Or in .Renviron file
GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx

Next Steps