# Build Shiny Module

> Construir módulos Shiny reutilizables con aislamiento correcto del espacio de nombres usando NS(). Cubre pares UI/server de módulos, valores de retorno reactivos, comunicación entre módulos y composición de módulos anidados. Úsalo al extraer un componente reutilizable de una aplicación Shiny en crecimiento, al construir un widget de UI usado en múltiples lugares, al encapsular lógica reactiva compleja detrás de una interfaz limpia, o al componer aplicaciones más grandes a partir de unidades más pequeñas y comprobables.

- Skill: `pjt222/build-shiny-module-2` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/build-shiny-module-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/build-shiny-module-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/build-shiny-module-2

---


# Build Shiny Module

Crear pares de módulos Shiny UI/server reutilizables con aislamiento correcto del espacio de nombres, comunicación reactiva y composabilidad.

## Cuándo Usar

- Al extraer un componente reutilizable de una aplicación Shiny en crecimiento
- Al construir un widget de UI que se usará en múltiples lugares
- Al encapsular lógica reactiva compleja detrás de una interfaz limpia
- Al componer aplicaciones más grandes a partir de unidades más pequeñas y comprobables

## Entradas

- **Requerido**: Descripción del propósito y funcionalidad del módulo
- **Requerido**: Contrato de entrada/salida (qué recibe y devuelve el módulo)
- **Opcional**: Si el módulo anida otros módulos (predeterminado: no)
- **Opcional**: Contexto del framework (golem, rhino o vanilla)

## Procedimiento

### Paso 1: Definir la Interfaz del Módulo

Antes de escribir código, define qué acepta y devuelve el módulo:

```text
Módulo: data_filter
Entradas: dataset reactivo, nombres de columnas para filtrar
Salidas: dataset filtrado reactivo
UI: controles de filtro (selectInput, sliderInput, dateRangeInput)
```

**Esperado:** Contrato claro que especifica entradas reactivas, salidas reactivas y elementos de UI.

**En caso de fallo:** Si la interfaz no está clara, el módulo probablemente es demasiado amplio. Divídelo en módulos más pequeños con responsabilidades únicas.

### Paso 2: Crear la Función UI del Módulo

```r
#' Data Filter Module UI
#'
#' @param id Module namespace ID
#' @return A tagList of filter controls
#' @export
dataFilterUI <- function(id) {
  ns <- NS(id)
  tagList(
    selectInput(
      ns("column"),
      "Filter column",
      choices = NULL
    ),
    uiOutput(ns("filter_control")),
    actionButton(ns("apply"), "Apply Filter", class = "btn-primary")
  )
}
```

Reglas clave:
- El nombre de la función sigue la convención `<nombre>UI`
- El primer argumento siempre es `id`
- Crea `ns <- NS(id)` al inicio
- Envuelve cada `inputId` y `outputId` con `ns()`
- Devuelve un `tagList()` para permitir ubicación flexible

**Esperado:** Función UI que crea elementos de entrada/salida con espacio de nombres.

**En caso de fallo:** Si los IDs colisionan al usar el módulo dos veces, verifica que cada ID esté envuelto con `ns()`. Omisión común: IDs dentro de `renderUI()` o `uiOutput()` — estos también necesitan `ns()`.

### Paso 3: Crear la Función Server del Módulo

```r
#' Data Filter Module Server
#'
#' @param id Module namespace ID
#' @param data Reactive expression returning a data frame
#' @param columns Character vector of filterable column names
#' @return Reactive expression returning the filtered data frame
#' @export
dataFilterServer <- function(id, data, columns) {
  moduleServer(id, function(input, output, session) {
    ns <- session$ns

    # Update column choices when data changes
    observeEvent(data(), {
      available <- intersect(columns, names(data()))
      updateSelectInput(session, "column", choices = available)
    })

    # Dynamic filter control based on selected column
    output$filter_control <- renderUI({
      req(input$column)
      col_data <- data()[[input$column]]

      if (is.numeric(col_data)) {
        sliderInput(
          ns("value_range"),
          "Range",
          min = min(col_data, na.rm = TRUE),
          max = max(col_data, na.rm = TRUE),
          value = range(col_data, na.rm = TRUE)
        )
      } else {
        selectInput(
          ns("value_select"),
          "Values",
          choices = unique(col_data),
          multiple = TRUE,
          selected = unique(col_data)
        )
      }
    })

    # Return filtered data as a reactive
    filtered <- eventReactive(input$apply, {
      req(input$column)
      col <- input$column
      df <- data()

      if (is.numeric(df[[col]])) {
        req(input$value_range)
        df[df[[col]] >= input$value_range[1] &
           df[[col]] <= input$value_range[2], ]
      } else {
        req(input$value_select)
        df[df[[col]] %in% input$value_select, ]
      }
    }, ignoreNULL = FALSE)

    return(filtered)
  })
}
```

Reglas clave:
- El nombre de la función sigue la convención `<nombre>Server`
- El primer argumento siempre es `id`
- Los argumentos adicionales son expresiones reactivas o valores estáticos
- Usa `moduleServer(id, function(input, output, session) { ... })`
- Usa `session$ns` para UI dinámica creada dentro del server
- Devuelve valores reactivos explícitamente

**Esperado:** Función server que procesa entradas y devuelve salida reactiva.

**En caso de fallo:** Si los valores reactivos no se actualizan, verifica que las entradas de UI dinámica usen `session$ns` (no el `ns` externo). Si el módulo devuelve NULL, asegúrate de que `return()` sea la última expresión dentro de `moduleServer()`.

### Paso 4: Conectar el Módulo a la App Principal

```r
# In app_ui.R or ui
ui <- page_sidebar(
  title = "Analysis App",
  sidebar = sidebar(
    dataFilterUI("filter1")
  ),
  card(
    DT::dataTableOutput("table")
  )
)

# In app_server.R or server
server <- function(input, output, session) {
  # Raw data source
  raw_data <- reactive({ mtcars })

  # Call module — capture its return value
  filtered_data <- dataFilterServer(
    "filter1",
    data = raw_data,
    columns = c("cyl", "mpg", "hp", "wt")
  )

  # Use the module's returned reactive
  output$table <- DT::renderDataTable({
    filtered_data()
  })
}
```

**Esperado:** El módulo aparece en la UI y su reactivo devuelto fluye hacia las salidas posteriores.

**En caso de fallo:** Si la UI del módulo no se renderiza, verifica que la cadena `id` coincida entre las llamadas UI y server. Si el reactivo devuelto es NULL, verifica que la función server realmente devuelva un valor.

### Paso 5: Componer Módulos Anidados (Opcional)

Para módulos que contienen otros módulos:

```r
analysisUI <- function(id) {
  ns <- NS(id)
  tagList(
    dataFilterUI(ns("filter")),
    plotOutput(ns("plot"))
  )
}

analysisServer <- function(id, data) {
  moduleServer(id, function(input, output, session) {
    # Call inner module with namespaced ID
    filtered <- dataFilterServer("filter", data = data, columns = names(data()))

    output$plot <- renderPlot({
      req(filtered())
      plot(filtered())
    })

    return(filtered)
  })
}
```

Regla clave: En la UI, anida con `ns("inner_id")`. En el server, llama con solo `"inner_id"` — `moduleServer` gestiona el encadenamiento del espacio de nombres.

**Esperado:** El módulo interno se renderiza correctamente dentro del espacio de nombres del módulo externo.

**En caso de fallo:** Si la UI del módulo interno no aparece, probablemente olvidaste `ns()` alrededor del ID del módulo interno en la función UI externa. Si la comunicación del server falla, verifica que el ID del módulo interno coincida (sin `ns()` en la llamada del server).

### Paso 6: Probar el Módulo en Aislamiento

```r
# Quick test app for the module
if (interactive()) {
  shiny::shinyApp(
    ui = fluidPage(
      dataFilterUI("test"),
      DT::dataTableOutput("result")
    ),
    server = function(input, output, session) {
      data <- reactive(iris)
      filtered <- dataFilterServer("test", data, names(iris))
      output$result <- DT::renderDataTable(filtered())
    }
  )
}
```

**Esperado:** El módulo funciona correctamente en la app de prueba mínima.

**En caso de fallo:** Si el módulo falla en aislamiento pero funciona en la app completa (o viceversa), busca dependencias implícitas en variables globales o en el estado de la sesión padre.

## Validación

- [ ] La función UI del módulo acepta `id` como primer argumento y usa `NS(id)`
- [ ] Cada ID de entrada/salida en la UI está envuelto con `ns()`
- [ ] El server del módulo usa `moduleServer(id, function(input, output, session) { ... })`
- [ ] La UI dinámica en el server usa `session$ns` para los IDs
- [ ] El módulo puede instanciarse múltiples veces sin colisiones de IDs
- [ ] Los valores de retorno reactivos son accesibles para la app padre
- [ ] El módulo funciona en una app de prueba independiente mínima

## Errores Comunes

- **Olvidar `ns()` en `renderUI()`**: La UI dinámica creada dentro del server debe usar `session$ns` — el `ns` externo no está disponible dentro de `moduleServer()`.
- **Pasar datos no reactivos**: Los argumentos del módulo que cambian con el tiempo deben ser expresiones reactivas. Pasa `reactive(data)` no `data`.
- **Incompatibilidad de IDs**: La cadena `id` en la llamada UI debe coincidir exactamente con el `id` en la llamada server.
- **No devolver reactivos**: Si el módulo calcula algo que necesita el padre, debe `return()` un reactivo. Olvidarlo es un bug silencioso.
- **Espacio de nombres en módulos anidados**: En UI: `ns("inner_id")`. En server: solo `"inner_id"`. Mezclar esto causa doble envolvimiento del espacio de nombres o prefijos faltantes.

## Habilidades Relacionadas

- `scaffold-shiny-app` — configurar la estructura de la app antes de añadir módulos
- `test-shiny-app` — probar módulos con tests unitarios testServer()
- `design-shiny-ui` — layout y temas bslib para UIs de módulos
- `optimize-shiny-performance` — patrones de caché y async dentro de módulos

