Shiny Modularization

Shiny App Modularization - Research Notes

Experiment Overview

Context

The Islet Explorer app grew to 5,400 lines in a single app.R. Modularization was needed for maintainability, but interactive features (plotly click-to-segmentation, cross-tab communication) broke during extraction.

Verified Workflow

1. Extraction Order (least to most coupled)

1. 00_globals.R - library loads, constants, feature flags
2. Pure utility functions (no Shiny deps): utils_safe_join.R, utils_stats.R, data_loading.R
3. Domain helpers: segmentation_helpers.R, viewer_helpers.R, ai_helpers.R
4. Self-contained modules: AI Assistant
5. Data-consuming modules: Statistics, Viewer
6. Interactive modules: Plot (click handler), Trajectory (click handler + H5AD)

2. Plotly Click Events in Modules

# In module server - namespace the source string
ns <- session$ns
gg <- ggplotly(p, source = ns("my_source"))
gg <- gg %>% event_register("plotly_click")

# Click handler - use matching ns() source
observeEvent(event_data("plotly_click", source = ns("my_source")), {
  d <- event_data("plotly_click", source = ns("my_source"))
  # ...
})

3. Root-Level Shared Outputs for Cross-Module Rendering

When multiple modules need to render to the same output (e.g., segmentation plot used by both a modal and an embedded panel), define the renderPlot at the ROOT level in app.R, not inside any module.

# app.R server - root level
output$shared_plot <- renderPlot({
  req(shared_reactive())
  render_function(shared_reactive())
})

# Module A - modal references root-level output (NO ns() prefix)
showModal(modalDialog(plotOutput("shared_plot")))

# Module B - embedded panel references root-level output (NO ns() prefix)
output$my_panel <- renderUI({
  plotOutput("shared_plot")
})

5. Non-namespaced output deconfliction across modules

When multiple modules emit non-namespaced output IDs (shared root-level renders), pass active_tab reactive and guard renderUI to prevent duplicate DOM IDs.

4. ggplot2 vs sf Namespace

# WRONG - coord_sf and geom_sf are NOT sf exports
sf::coord_sf(...)   # Error: 'coord_sf' is not an exported object from 'namespace:sf'
sf::geom_sf(...)    # Works but wrong namespace

# CORRECT - these are ggplot2 functions
ggplot2::coord_sf(xlim = ..., ylim = ..., expand = FALSE)
ggplot2::geom_sf(data = polygons, fill = NA, color = "blue")

Failed Attempts (Critical)

Key Insights

• Shiny's R/ directory is auto-sourced alphabetically before global.R. Prefix globals file with 00_ to ensure it loads first.
• showModal from inside a module works fine for sending the modal, but the plotOutput inside the modal must match a renderPlot that Shiny can bind. Root-level outputs are safest for shared rendering.
• reactiveVal objects can be passed as module parameters for cross-module communication (e.g., selected_islet, forced_image).
• When extracting monolithic code, grep for bare function calls (like coord_sf, geom_sf) and verify which package exports them before adding pkg:: prefixes.
• For diverging data (zero-centered z-scores), use scale_color_gradient2() with limits and scales::squish, not sequential colormaps.
• Non-namespaced output deconfliction: When multiple modules emit the same non-namespaced plotOutput() / tableOutput() IDs (required for root-level shared renders), pass active_tab = reactive(input$tabs) to each module and guard the renderUI that emits those IDs. Pattern: if (active_tab() != "Plot") return(NULL). This prevents duplicate DOM IDs that cause Shiny to grey out / orphan one binding.

References

• Shiny Modules
• Plotly event_data in modules
• Islet Explorer: app/shiny_app/ in this repository