r-shiny

name	r-shiny
description	Design and implement production-style R Shiny apps with modules, shared data pipelines, background compute, polished dashboards, maps, tables, figures, and strong accessibility. Use when building or refactoring a Shiny app.
argument-hint	["app feature or module"]
paths	["**/app.R","**/global.R","**/server.R","**/ui.R","**/modules/**/*.R","**/mod_*.R"]

R Shiny

Build Shiny apps around a stable data layer, explicit module boundaries, predictable UI state, and a dashboard shell that is structurally sound before custom CSS polish.

Quick start

1. Read references/app-builder-patterns.md.
2. If the task includes beautiful dashboards, theming, custom HTML/CSS, or designer-provided markup, also read references/html-css-dashboard-design.md.
3. If the task includes dense analytical shells, shared sidebars, inspector panels, hierarchy controls, dataset maps, jobs feeds, or other expert-statistician workbench behavior, also read references/expert-analyst-workbench-patterns.md.
4. If the task includes semantic HTML, accessibility, focus behavior, keyboard operation, labels, skip links, or screen-reader-friendly custom markup, also read references/accessibility-semantic-html.md.
5. If the task includes motion, transitions, hover/focus reveal behavior, tooltips, popovers, notifications, or onboarding micro-interactions, also read references/micro-interactions-motion.md.
6. If the task includes mobile layouts, narrow viewports, breakpoints, reflow, dashboard stacking, or responsive card grids, also read references/responsive-mobile-dashboards.md.
7. If the task includes custom inputs, full HTML UI, reusable CSS/JS assets, theme-aware components, or packageable UI pieces, also read references/html-css-component-architecture.md.
8. If the app will read large, multi-file, or repeatedly filtered data, also read references/arrow-parquet-app-performance.md.
9. If the app will lean on large local in-memory tables through data.table, tidytable, or dtplyr, also read references/data-table-backed-shiny-performance.md.
10. If the app will read from or write to an API, poll for updates, parse JSON responses, or manage request rate limits, also read references/api-backed-shiny.md.
11. If the app will call a deployed model endpoint or read pinned model/data artifacts, also read references/model-api-backed-shiny.md.
12. If the app will read from or write to a database, also read references/database-backed-shiny.md.
13. If the app will use DuckDB over local files, Arrow objects, or a file-backed analytical database, also read references/duckdb-backed-shiny.md.
14. If the app includes leaflet, sf geometry layers, choropleths, polygons, markers, popups, legends, or map click workflows, also read references/leaflet-sf-shiny-maps.md.
15. If the app includes long-running jobs, bursty background requests, future_promise(), ExtendedTask, or furrr fan-out inside app code, also read references/nonblocking-compute-with-future-promises.md.
16. Read references/advanced-ggplot-interactive-figures.md when the task includes advanced ggplot construction, interactive figures, plot brushing/clicking, ggplotly(), girafe(), or linked analytical plots.
17. Read references/interactive-statistical-figure-patterns.md when the task includes adjusted predictions, comparisons, slopes, survival or cumulative-incidence figures, linked summary tables, or interactive inferential plots that must preserve one estimand.
18. Read references/interactive-tables-linked-views.md when the task includes reactable, DT, row selection, searchable analytical tables, linked table/plot views, or interactive table companions.
19. Read references/shinytest2-app-testing.md when the task includes automated browser tests, snapshot files, AppDriver, record_test(), CI-facing app regression coverage, or exportTestValues() contracts.
20. Read references/shiny-performance-profiling-load-testing.md when the task includes app slowness, profiling, profvis, bench::mark(), shinyloadtest, record_session(), shinycannon, or capacity questions under concurrent users.
21. Read references/shiny-extension-packages.md when the task includes package selection or broader UI polish.
22. Confirm the app contract: data source, required pages or panels, required controls, reset behavior, visual hierarchy, accessibility expectations, motion posture, responsive/mobile expectations, dense-workbench expectations, table/selection/export semantics, map-state semantics, API freshness semantics, and expected outputs.
23. Put reusable data and summary logic in src/ helpers before adding module complexity or custom UI shells.
24. Build the dashboard shell with bslib page, sidebar, card, value-box, and navigation primitives first; extend with custom tags, CSS, or dependencies only where the shell still needs last-mile polish.
25. Drive tables, plots, and KPIs from one filtered-data reactive per analysis surface.
26. Add the smallest useful app smoke test, testServer() coverage, shinytest2 browser test, or performance-diagnostic surface for the changed app contract.

Workflow

1. Build the data layer first

• Validate required columns early.
• Keep app server code thin by delegating data shaping and summaries into helpers.
• Make the dataset source explicit: file input, static data, Parquet/Arrow dataset, database query, or registry-based selection.
• For large analytical sources, prefer a prebuilt Parquet working layer and arrow::open_dataset()/Table objects ahead of eager full-memory reads at session start.
• For database-backed sources, create one deliberate connection or pool surface, then keep the query lazy in dbplyr until each output needs a small local slice.
• For DuckDB-backed analytical sources, keep one deliberate DuckDB connection per app process, use file or Arrow-backed lazy tables for shaping, and treat collection into R as the output boundary rather than the data-ingest boundary.

1b. Keep local high-performance tabular state explicit

• Current fread() documentation keeps ingest controls such as select, drop, nThread, and detected column classes explicit. For large local delimited sources, keep that ingest step in a deliberate startup or cache layer instead of rereading the full file inside reactive code.
• Current setDT() documentation says conversion to data.table happens by reference. Convert once near the source boundary when the same table will feed many app outputs.
• Current setkey() documentation says keys reorder rows by reference. Keep display-order expectations explicit when an app links row selection, table order, and plot labels.
• Current tidytable documentation keeps grouped mutate() and summarize() work available through .by, while current dtplyr documentation says lazy_dt() keeps dplyr-style work lazy until collection or conversion. Keep that engine choice inside helpers so the output layer still receives one clear plot-ready or table-ready object.
• Current reactiveVal() documentation says reactive state is read with no arguments and set with one argument, while current data.table reference-semantics documentation says := mutates by reference. Team doctrine: treat in-place data.table mutation as a real app-state boundary by either working on a deliberate copy or writing the updated object back through the reactive container so invalidation remains visible.

2. Compose the dashboard shell before writing custom CSS

• Choose the page structure from the information architecture: page_sidebar() for most analytical dashboards, page_navbar() when the app truly has top-level sections, and page_fillable() when the page behaves like a workbench or canvas.
• Keep page-level sidebars for global controls; place panel-local controls inside layout_sidebar() within a card().
• Group the main outputs in card() containers, give dense analytical surfaces full_screen = TRUE, and place KPI rows in layout_columns(fill = FALSE) with value_box().
• Use navset_card_*() when one panel needs multiple views without becoming a separate page.
• Tune fill behavior with fill, fillable, min_height, max_height, fillable_mobile, and mobile sidebar behavior before reaching for more CSS.
• Decide early whether the sidebar should collapse on mobile, stay above the main content, or remain persistently open in a constrained way.
• Make the narrow-screen stacking plan explicit with layout_columns() breakpoints or layout_column_wrap() width rules instead of hoping the layout will adapt on its own.

3. Design controls around one state model

• Generate dynamic choices from one helper or one registry layer.
• Keep reset behavior explicit.
• Reuse the same filtered dataset across tabs whenever the UX calls for shared scope.
• For expensive recalculation, pair bindCache() with bindEvent() or an explicit task button so the app does heavy work only when the user has finished selecting inputs.
• For database-backed filters, keep the filter logic close to the lazy remote table and collect only at the output boundary.
• For DuckDB-backed filters over Parquet, CSV, or Arrow-registered data, keep joins and grouped summaries inside DuckDB and collect only the display-sized or model-sized slice.

3b. Build interactive figures from one canonical ggplot spec

• Build one canonical ggplot object in a helper, then wrap it for the chosen interaction surface rather than maintaining separate static and interactive plotting code.
• Keep discrete scales and legends stable across reactive filters by making factor order and scale_*_manual(limits = ..., drop = ..., na.translate = ...) decisions explicit.
• Use coord_cartesian() when the app needs reactive zooming without changing the underlying data or computed statistics.
• Use after_stat(), after_scale(), and stage() when the plot really depends on computed variables or staged aesthetic evaluation.
• Use facet_grid() / facet_wrap() deliberately for dense analytical dashboards, keeping scales, space, axes, and axis.labels aligned with the reading task.
• Choose the interaction surface deliberately: static ggplot plus plotOutput() interactions for data-frame selection, ggplotly() for htmlwidget zoom/pan/events, and ggiraph::girafe() for ggplot-native interactive geoms with tooltips and selection state.
• Keep tooltips, source IDs, data_ids, and hover labels explicit so the server can tell which figure emitted which event.

3c. Keep interactive statistical figures tied to one analytical contract

• Separate analysis-defining controls from display-only controls. If the user changes an estimand, subgroup definition, model family, type, contrast definition, or event definition, treat that as an analytical change. If the user changes zoom, legend visibility, hover detail, or panel size, keep that as a display change.
• Drive the figure, linked summary table, tooltip fields, reference lines, and caption/footnote text from one plot-ready data object or one post-estimation result object. This prevents the plot and table from drifting onto different scales or different subgroup definitions.
• Keep estimand metadata explicit in the app layer: estimate label, scale label, null reference line, ratio-versus-difference posture, event definition, and whether a risk table or companion summary belongs with the figure.
• When the figure is built from marginaleffects, keep condition, by, and type choices visible in the controls or status text because the package docs make those arguments part of the analytical meaning of the plot.
• If point selection or brushing is meant to select estimates or subgroups, perform the selection on the plotted estimate data, not on the raw upstream dataset. With static plots, nearPoints() / brushedPoints() should operate on the same data frame that drove the figure.
• Use plotOutput() when the interaction is mostly analytical selection into a linked table or detail panel; use ggplotly() when zoom/pan and widget events add real analytical value; use ggiraph when hover/selection styling on estimate geoms is part of the UX.
• When an expensive fit or post-estimation computation drives the figure, gate recalculation deliberately with an explicit event and preserve a current-result signature so the app can tell users when the displayed figure no longer matches the current controls.
• For survival or cumulative-incidence figures, keep event definitions, time origin, and any risk-table or timepoint-summary companion visible outside the tooltip. Those quantities are too important to hide behind hover alone.

3d. Treat interactive tables as analytical views, not loose widgets

• Drive reactable or DT from one filtered or reporting-ready data object so the visible table, linked plot, KPI strip, and download surface stay synchronized.
• Keep analysis-defining filters separate from table display state. Search strings, column sort order, current page, expanded rows, and hover state usually belong to the display layer unless the app explicitly says they change the analytical slice.
• Choose the table surface deliberately. reactable fits curated analytical tables with details rows, rich theming, and Shiny state helpers; DT fits dense search/filter/paging flows, cell-level interactions, editable tables, and proxy-driven updates.
• Keep stable keys explicit whenever the table links to another surface. Row indices become fragile after sorting, filtering, pagination, or data refreshes, so linked details and exports should map through a key column or a clearly defined selected-row contract.
• Keep widget state explicit too. For reactable, read state through getReactableState() and update state through updateReactable(); for DT, track selection and filter state through the documented Shiny inputs and the proxy/update surface.
• When data refreshes, declare whether the app should preserve or clear selection, page, expanded rows, and search state. Current docs show that these state decisions differ across table engines.
• If the table is a companion to a publication or export surface, declare whether downloads reflect the full analytical slice, the currently filtered rows, or the currently selected rows.
• When linked htmlwidgets should share filtering or brushing without bespoke Shiny plumbing, crosstalk::SharedData can be an appropriate bridge as long as every participating widget shares the same wrapped data object.

3e. Keep API freshness, polling, and request boundaries explicit

• Keep request construction in helpers so server code mostly asks for one named API resource or payload instead of assembling URLs and headers inline inside observers.
• Current reactivePoll() documentation says it combines a cheap checkFunc with a heavier valueFunc. When an API offers a version token, timestamp, ETag-like freshness value, or lightweight status endpoint, reactivePoll() is usually a cleaner fit than blindly refetching the full payload every interval. This is a team inference grounded in the documented split between check and value functions.
• Current invalidateLater() documentation schedules re-execution inside the current reactive context and accepts a session so invalidations stop when the user session ends. Use it for deliberate timed refresh loops when there is no cheaper freshness check.
• Keep retry, throttling, and timeout posture close to the request helper so the app can explain why a source is temporarily unavailable or rate-limited.
• Keep JSON simplification boundaries explicit: the helper that parses API responses should decide whether nested results remain list-shaped, flatten into frames, or stay cached as raw lists for downstream selection.

3e2. Keep model-serving boundaries explicit

• Current vetiver_api() documentation says deployable models can be exposed through a prediction endpoint with an explicit path and prototype checks. When an app should score remotely, keep the endpoint helper explicit so the app can tell which model service it is calling.
• Current vetiver reference documentation lists vetiver_endpoint() plus predict(<vetiver_endpoint>) and augment(<vetiver_endpoint>) as the remote-client surface. Keep remote scoring helpers separate from any local fit helper so the app can keep the scoring boundary visible.
• Current pins documentation says pin_read() can retrieve a specific version or verify a hash. When an app loads a pinned artifact or model locally, keep the board and version boundary explicit at startup or refresh time.
• Team doctrine: if the same deployed model or pinned artifact drives multiple app outputs, keep the model name, artifact name, or version label visible in app status text so the scoring contract stays inspectable.

3f. Keep geospatial map layers and view state explicit

• Current leaflet Shiny documentation says initialize maps with leafletOutput() plus renderLeaflet(), then modify a running map with leafletProxy() instead of rebuilding the whole widget for every reactive change.
• Current leaflet shapes documentation says leaflet works directly with sf layers and points to sf::st_polygon() for polygons with holes. Keep map geometry in prepared sf objects instead of rebuilding ad hoc coordinate lists inside render code.
• Keep popups, labels, and legend-ready variables precomputed in helpers so the app layer mostly selects layers and display fields instead of formatting strings repeatedly inside map updates.
• Current leaflet color and legend documentation says palette functions should be created with an explicit domain, then reused in both layer styling and addLegend(). Keep the palette contract shared so color meaning stays stable across reactive filters.
• Current leaflet Shiny documentation says map events arrive through input$MAPID_* values such as input$mymap_shape_click. Keep layerId and group semantics explicit so click handling can resolve the selected feature reliably.
• Treat map bounds, zoom, and visible group toggles as display state unless the app explicitly says they redefine the analytical slice.

3g. Keep background compute outside the reactive hot path

• Current Shiny documentation says ExtendedTask is the right surface when a long-running operation should proceed in the background while the same session remains usable. Treat that as a separate layer from ordinary reactive calculations.
• Current Shiny and ExtendedTask documentation say the background function should not read reactive inputs or other reactive sources directly. Snapshot those values at invoke time and pass them as ordinary arguments.
• Current promises documentation says future_promise() runs the slow code through a future-backed promise, and the work-queue helpers delay launching new futures until workers are available. That makes future_promise() a good bridge for bursty button-driven work where queueing is better than freezing the session.
• Current future documentation says multisession resolves work in separate R sessions and works across platforms, while multicore can be unsupported or unstable in Windows and RStudio-driven workflows. For interactive Shiny doctrine, separate-session backends are usually the steadier starting point.
• If the background job fans out across many independent subproblems, make the concurrency boundary explicit. Team doctrine: one visible background-task boundary per app feature is usually easier to reason about than layered hidden parallelism.
• When app code parallelizes map-style work, current furrr documentation makes chunking, globals, packages, and random-number seeds explicit through furrr_options(). Keep those settings visible in the helper or task constructor whenever performance or reproducibility matters.

4. Extend with HTML and CSS in layers

• Start the visual system with bs_theme(), fonts, and a restrained palette; then add Bootstrap Sass variables or bs_add_rules() for theme-aware polish.
• When an app family needs a stable visual system across multiple surfaces, keep shared brand tokens centralized through bs_theme() and, where appropriate, _brand.yml support.
• Set the page language explicitly with lang = on page_sidebar(), page_navbar(), fluidPage(), or the equivalent page helper when the interface language is known.
• Keep page structure semantic when custom markup grows: one clear <main> region, labeled <nav> regions, and <aside> only for content that is related but meaningfully separate.
• Keep heading ranks logical across the app shell and within cards or sidebars so screen-reader and keyboard users can navigate by section.
• Lean on Bootstrap utility classes for spacing, alignment, borders, and display tuning before writing larger custom stylesheets.
• When the generated tag structure makes class placement awkward, reshape or annotate the markup with htmltools::tagQuery() rather than scattering brittle selectors through the stylesheet.
• Build bespoke structure with tags$... helpers so the markup remains visible inside the Shiny/htmltools pipeline.
• Keep every custom control or full-HTML input tied to an explicit label; use aria-describedby for extra instructions or validation text, and do not rely on placeholder text as the label.
• Use native interactive elements such as <button>, <a>, <input>, and <label> before recreating those semantics with clickable divs. When a genuinely custom tab, dialog, or disclosure widget is necessary, implement its focus and keyboard behavior deliberately.
• For app-local custom components whose assets repeat across instances, attach one-time CSS/JS with singleton(tags$head(...)).
• Move beyond inline styling once the CSS grows: place durable styles under www/ or package them as dependencies.
• Use htmlTemplate() or a full www/index.html UI when the app genuinely needs designer-owned HTML, and keep the Shiny binding contract visible: inputs bind through name, while outputs need the right id and shiny-* class.
• Package reusable custom components with htmltools::htmlDependency() or bslib::bs_dependency() when the component should travel cleanly across apps or react to theme changes.
• Keep visible focus and usable contrast in the theme layer so links, buttons, tabs, and custom controls remain recognizable during keyboard use.
• For long dashboards or repeated navigation blocks, consider a skip link or labeled in-page navigation surface so keyboard users can reach the main content or major sections quickly.
• Keep motion purposeful and local: use small transitions to clarify state changes, and keep larger movement rare enough that it does not dominate the analytical task.
• When an interaction-driven motion effect is decorative rather than essential, support reduced-motion preferences in CSS and keep modal/dialog motion easy to suppress.
• Prefer a tooltip for brief read-only hints, a popover for small interactive card-local controls, a notification for transient global feedback, and a modal for blocking decisions or workflows that truly need interruption.
• Treat hover/focus reveals as part of the interaction contract: the content should be discoverable by keyboard as well as pointer, and it should stay usable long enough to read or interact with it.
• Keep dashboard cards and column layouts responsive by default: define breakpoint behavior, mobile heights, and sidebar state deliberately rather than repairing overflow after the visual design is finished.

5. Validate before render

• Check output readiness before plotting or tabulating.
• Return informative messages when a variable combination or dataset state is unsupported.
• Keep display failures visible rather than silent.
• Cache only pure, repeatable work, and keep cache keys small by hashing filter values or dataset signatures rather than entire large data objects.
• For database-backed apps, make the collect/materialization boundary explicit so plots, models, and tables do not receive an unexpectedly remote tbl_sql object.
• For DuckDB-backed apps, keep the single-process versus multi-process story explicit before adding writeback paths or shared file-backed databases.

6. Verify behavior after implementation

• Smoke-test startup with shiny::runApp() when feasible.
• Add testServer() coverage when the change lives in a module.
• Add shinytest2 browser tests when the contract includes navigation, downloads, browser-visible text or HTML, tab state, uploads, or layout-sensitive behavior across a real app session.
• When the app feels slow for one user, profile the representative slow path with profvis before redesigning reactivity or UI structure.
• When the app is acceptable for one user but questionable under concurrency, move to shinyloadtest: record a realistic session, run shinycannon with explicit worker and duration settings, then inspect the loaded run data or HTML report.
• Current record_test() documentation positions the recorder as the easiest way to bootstrap a browser test. Treat the recorded script as scaffolding, then trim it into the smallest durable browser contract.
• Current AppDriver documentation says expect_values() snapshots inputs, outputs, and exported values to JSON while also writing a debug screenshot. A strong default is to keep shiny::exportTestValues() visible for important reactive contracts so browser tests can assert meaning directly.
• Current in-depth shinytest2 guidance recommends wait_for_idle() or wait_for_value() where people often reach for Sys.sleep(). Keep stabilization explicit in browser tests whenever async UI updates or expensive renders are involved.
• Keep seed, viewport, and snapshot variant deliberate when randomness, browser rendering, or layout size affect the test contract.
• Check desktop and mobile fill behavior once the shell is in place.
• Check reduced-motion behavior when the design adds custom transitions, hover reveals, or animated onboarding.
• Keep performance-sensitive recalculation event-driven when the UX expects explicit confirmation.
• For long-running loads or modeling jobs, move the slow path into ExtendedTask + future_promise() so the rest of the session stays responsive.
• For database-backed apps, confirm the pool lifecycle, deployment dependency detection, and writeback transaction posture.

Coordination notes

• Reach for /r-shiny-debugging when the main job is diagnosing reactive bugs, layout breakage, missing styles, template/dependency problems, full-HTML binding failures, or database-backed translation/connection issues.
• Reach for /r-package-dev when the custom HTML/CSS work should become a reusable package component instead of an app-local asset.
• Reach for /r-tables-reporting when the same analytical table also needs a publication/reporting companion or explicit filtered-versus-selected export semantics.
• Reach for /r-eda when the real bottleneck is building or refreshing the analytical source layer itself.
• Reach for /r-model-builder when the central work is a modeling module or a reusable post-estimation figure helper rather than the app shell.
• Reach for /r-stats when the app work is blocked on choosing the correct estimand, scale, or figure family for a statistical result.
• Reach for /r-advanced only when the same Shiny design or UI-state lesson becomes repo-grounded and broadly reusable across projects.

Resources

• references/app-builder-patterns.md
• references/html-css-dashboard-design.md
• references/expert-analyst-workbench-patterns.md
• references/accessibility-semantic-html.md
• references/micro-interactions-motion.md
• references/responsive-mobile-dashboards.md
• references/html-css-component-architecture.md
• references/arrow-parquet-app-performance.md
• references/data-table-backed-shiny-performance.md
• references/api-backed-shiny.md
• references/model-api-backed-shiny.md
• references/database-backed-shiny.md
• references/duckdb-backed-shiny.md
• references/leaflet-sf-shiny-maps.md
• references/nonblocking-compute-with-future-promises.md
• references/advanced-ggplot-interactive-figures.md
• references/interactive-statistical-figure-patterns.md
• references/interactive-tables-linked-views.md
• references/shinytest2-app-testing.md
• references/shiny-performance-profiling-load-testing.md
• references/shiny-extension-packages.md