### Rhino YAML Configuration Examples

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/configuration.md

Examples of rhino.yml configurations for standard setup, legacy entrypoints, and style error tolerance.

```yaml
sass: node
```

```yaml
sass: node
legacy_entrypoint: app_dir
```

```yaml
sass: node
legacy_max_lint_r_errors: 10
```

--------------------------------

### Config YAML Logging Configuration Examples

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/configuration.md

Examples of config.yml for different profiles (default, production, staging) demonstrating logging level and file path settings.

```yaml
default:
  rhino_log_level: !expr Sys.getenv("RHINO_LOG_LEVEL", "INFO")
  rhino_log_file: !expr Sys.getenv("RHINO_LOG_FILE", NA)

production:
  rhino_log_level: !expr Sys.getenv("RHINO_LOG_LEVEL", "WARN")
  rhino_log_file: !expr Sys.getenv("RHINO_LOG_FILE", "/var/log/rhino.log")

staging:
  rhino_log_level: !expr Sys.getenv("RHINO_LOG_LEVEL", "INFO")
  rhino_log_file: "logs/staging.log"
```

--------------------------------

### Entry Points

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Functions to start and initialize a Rhino project.

```APIDOC
## Entry Points

### `app()`

**Purpose**: Run Rhino application

### `init()`

**Purpose**: Initialize new project
```

--------------------------------

### Core Application

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

The `app()` function is the main entrypoint for starting a Rhino application.

```APIDOC
## app()

### Description
Entrypoint for Rhino application.

### Function Signature
`app()`

### Module
`R/app.R`
```

--------------------------------

### pkg_install()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

Installs project dependencies. This function manages the installation of required packages.

```APIDOC
## pkg_install()

### Description
Installs project dependencies.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
(Details not provided in source)

### Request Example
```R
pkg_install()
```

### Response
(Details not provided in source)
```

--------------------------------

### Logging Quick Start

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Demonstrates basic logging in Rhino using different levels (info, warn, error, debug) and string interpolation.

```r
box::use(rhino[log])

log$info("App started")
log$warn("Warning message")
log$error("Error occurred")
log$debug("Debug info")

# With string interpolation
name <- "Rhino"
log$info("Hello {name}!")
```

--------------------------------

### Install shiny.react Package

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/react.md

Provides the command to install the `shiny.react` package if it's missing, which is required for using React components in your Rhino application.

```r
rhino::pkg_install("shiny.react")
```

--------------------------------

### Package Installation

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `pkg_install()` function installs R packages. This is essential for managing project dependencies.

```R
pkg_install()

```

--------------------------------

### Installing shiny.react for React Component Usage in R

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

Before using React components with `react_component()`, ensure the `shiny.react` package is installed. This snippet shows the command to install it.

```R
# Fails if shiny.react not installed
TextBox <- react_component("TextBox")
```

```R
rhino::pkg_install("shiny.react")
```

--------------------------------

### Application Entrypoint

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `app()` function serves as the application entrypoint. It is used to start and run the Rhino application.

```R
app()

```

--------------------------------

### Config YAML Logging Configuration Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Shows the config.yml file for setting up logging, including the log level and log file, with options for environment variable overrides.

```yaml
default:
  rhino_log_level: !expr Sys.getenv("RHINO_LOG_LEVEL", "INFO")
  rhino_log_file: !expr Sys.getenv("RHINO_LOG_FILE", NA)
```

--------------------------------

### Rhino YAML Configuration Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Demonstrates the structure of the rhino.yml configuration file, specifying Sass compilation methods and optional legacy settings.

```yaml
# Sass compilation method (required)
sass: node    # Use Dart Sass (recommended)
# sass: r     # Or use R sass package
# sass: custom  # Or use custom build

# Optional: Legacy entrypoint for migration
legacy_entrypoint: box_top_level

# Optional: Allow style errors in legacy code
legacy_max_lint_r_errors: 10
```

--------------------------------

### Application Structure Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Illustrates the typical directory structure for a Rhino project, including R scripts, JavaScript, Sass, tests, and configuration files.

```text
project/
├── app.R                    # Just contains: rhino::app()
├── app/
│   ├── main.R             # UI and server modules
│   ├── view/              # UI component modules
│   ├── logic/             # Business logic modules
│   ├── js/index.js        # JavaScript source
│   ├── styles/main.scss   # Sass stylesheets
│   └── static/            # Static files (compiled output)
├── tests/
│   ├── testthat/          # R unit tests
│   └── cypress/           # E2E tests
├── rhino.yml              # Framework configuration
└── config.yml             # Logging configuration
```

--------------------------------

### Essential Commands for Project Management

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Provides R code snippets for initializing a new project and managing R package dependencies by installing or removing them.

```r
rhino::init()             # Initialize new project
rhino::pkg_install("pkg") # Install R package
rhino::pkg_remove("pkg")  # Remove R package
```

--------------------------------

### Install Package with renv

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/configuration.md

Installs a specified R package and updates the renv lockfile to ensure reproducible environments.

```r
rhino::pkg_install("dplyr")
```

--------------------------------

### Setting Environment Variables for Rhino

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/configuration.md

Examples of setting environment variables for Rhino configuration in different shell environments and R.

```bash
# In shell (Unix/Linux/macOS)
export RHINO_LOG_LEVEL=DEBUG
export RHINO_NPM=yarn

# In Windows Command Prompt
set RHINO_LOG_LEVEL=DEBUG
set RHINO_NPM=yarn

# In .Renviron file (R session-wide)
RHINO_LOG_LEVEL=DEBUG
RHINO_NPM=yarn

# In app via Sys.setenv()
Sys.setenv(RHINO_LOG_LEVEL = "DEBUG")
```

--------------------------------

### Run App in Development Mode

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Starts the application in development mode, enabling auto-rebuild and auto-testing for a faster development cycle.

```r
rhino::devmode()
```

--------------------------------

### Initialize a new Rhino project

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/init-and-setup.md

Generates the complete file structure for a new Rhino application. Customize setup by specifying parameters like directory, CI workflows, E2E tests, and agent instructions.

```r
init(
  dir = ".",
  github_actions_ci = TRUE,
  agents_instructions = TRUE,
  e2e_tests = TRUE,
  rhino_version = "rhino",
  force = FALSE
)
```

```r
# Create a new Rhino project in current directory
init()

# Create project with minimal setup
init(github_actions_ci = FALSE, e2e_tests = FALSE)

# Create project in a specific directory
init("./my-shiny-app")

# Override home directory protection
init("~/myproject", force = TRUE)
```

--------------------------------

### GitHub Actions CI Setup

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `use_github_actions_ci()` function configures the project to use GitHub Actions for Continuous Integration. This automates build and test processes.

```R
use_github_actions_ci()

```

--------------------------------

### app()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The application entrypoint function. This is the primary function to start or run the Rhino application.

```APIDOC
## app()

### Description
Provides the application entrypoint for Rhino.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
(Details not provided in source)

### Request Example
```R
app()
```

### Response
(Details not provided in source)
```

--------------------------------

### Creating a Module in R

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

An R code example demonstrating how to create a reusable UI module using the box package, including UI and server function definitions.

```r
# app/view/dashboard.R
box::use(shiny[moduleServer, reactive])

ui <- function(id) {
  ns <- shiny::NS(id)
  div(h1("Dashboard"), plotOutput(ns("plot")))
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$plot <- renderPlot({
      # Plot logic
    })
    list(data = reactive({ ... }))
  })
}
```

--------------------------------

### pkg_install()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/dependencies.md

Installs or updates R package dependencies in a Rhino project. It installs packages to the local `renv` library and updates both `dependencies.R` and `renv.lock` files in a single operation. This is the recommended way to add dependencies to a Rhino project.

```APIDOC
## pkg_install()

### Description
Installs or updates R package dependencies in a Rhino project. It installs packages to the local `renv` library and updates both `dependencies.R` and `renv.lock` files in a single operation. This is the recommended way to add dependencies to a Rhino project.

Supports the following package specification formats:
- Package name (e.g., `"dplyr"`)
- Specific version (e.g., `"shiny@1.6.0"`)
- GitHub (e.g., `"Appsilon/shiny.i18n"`)
- Bioconductor (e.g., `"bioc::Biobase"`)
- Local path (e.g., `"~/path/to/shiny"`)

### Parameters
#### Parameters
- **packages** (character vector) - Required - Names of packages to install. Supports various formats.

### Returns
None. Called for side effects.

### Examples
```r
# Install latest version
pkg_install("dplyr")

# Install specific version
pkg_install("shiny@1.6.0")

# Install from GitHub
pkg_install("Appsilon/shiny.i18n")

# Install from Bioconductor
pkg_install("bioc::Biobase")

# Install from local source
pkg_install("~/path/to/shiny")

# Install multiple packages
pkg_install(c("dplyr", "ggplot2", "shiny@1.6.0"))
```
```

--------------------------------

### Install R Package with pkg_install()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/dependencies.md

Use pkg_install() to add R packages to your Rhino project. It installs packages to the local renv library and updates project files.

```r
pkg_install("dplyr")
```

```r
pkg_install("shiny@1.6.0")
```

```r
pkg_install("Appsilon/shiny.i18n")
```

```r
pkg_install("bioc::Biobase")
```

```r
pkg_install("~/path/to/shiny")
```

```r
pkg_install(c("dplyr", "ggplot2", "shiny@1.6.0"))
```

--------------------------------

### Install Development Rhino Version

Source: https://github.com/appsilon/rhino/blob/main/README.md

Install the development version of the Rhino package directly from GitHub. Use this for the latest features and bug fixes, but be aware it may be less stable.

```r
remotes::install_github("Appsilon/rhino")
```

--------------------------------

### Simple List Destructuring Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/destructuring.md

Demonstrates basic destructuring of a named list into separate variables. Prints the assigned variables.

```r
box::use(
  shiny[moduleServer, reactive],
  rhino[`%<-%`],
)

# Example 1: Simple list destructuring
person <- list(name = "Alice", age = 30, city = "Portland")
c(name, age) %<-% person
print(name)  # "Alice"
print(age)   # 30
```

--------------------------------

### Lazy Reactive Computation Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Demonstrates lazy reactive computation where an expensive calculation is only performed when its result is actually needed, with a simulated delay.

```r
# Expensive computation only when needed
expensive_result <- reactive({
  log$debug("Running expensive computation")
  # Long-running calculation
  Sys.sleep(2)
  result <- sum(1:1000000)
  result
})
```

--------------------------------

### Testing Modules

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Write unit tests for your modules using the `testthat` package. This example demonstrates testing a module's UI component by checking its output type.

```r
# tests/testthat/test-module.R
box::use(testthat[test_that, expect_true])
box::use(app/view/my_module)

test_that("module creates UI", {
  ui <- my_module$ui("test")
  expect_true(inherits(ui, "shiny.tag"))
})
```

--------------------------------

### End-to-End Tests Setup

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `use_e2e_tests()` function is used to set up end-to-end testing for the project. This function configures the necessary components for running E2E tests.

```R
use_e2e_tests()

```

--------------------------------

### Missing System Dependency Error

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

Fails when a required system dependency, such as Node.js, is not found. Install the missing dependency following the provided instructions to resolve the issue.

```r
build_js()  # Fails if Node.js not installed
```

```bash
# Install Node.js (includes npm)
# Visit https://nodejs.org/
```

--------------------------------

### Get and Print Testthat Coverage

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/types.md

Demonstrates how to obtain a coverage object using `covr_r()` and then display its summary using the print method. The object is of class 'coverage'.

```r
coverage <- covr_r()
class(coverage)  # "coverage"
print(coverage)  # Display summary
```

--------------------------------

### Shiny Reactive Module Destructuring Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/destructuring.md

Shows how to destructure reactive values returned from a child module within a parent module server function.

```r
# Example 2: Shiny reactive module
my_module_server <- function(id) {
  moduleServer(id, function(input, output, session) {
    list(
      text_value = reactive(input$text),
      numeric_value = reactive(input$number)
    )
  })
}

# Destructure in parent module
parent_server <- function(id) {
  moduleServer(id, function(input, output, session) {
    c(text, number) %<-% my_module_server("child")
    # Use text and number as reactive expressions
  })
}
```

--------------------------------

### Initialize New Rhino Project

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Sets up a new Rhino project with the standard directory structure and configuration files.

```r
rhino::init()
```

--------------------------------

### Using a Module in main.R

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Demonstrates how to include and use a custom module's UI and server logic within the main application file.

```r
# app/main.R
box::use(
  app/view/my_module,
)

ui <- function(id) {
  my_module$ui(id)
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    my_module$server(id)
  })
}
```

--------------------------------

### Install Stable Rhino Version

Source: https://github.com/appsilon/rhino/blob/main/README.md

Install the latest stable version of the Rhino package from CRAN. This is the recommended method for most users.

```r
install.packages("rhino")
```

--------------------------------

### Basic Logging with Rhino

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/logging.md

Shows how to log simple messages using different severity levels. Ensure the 'rhino' package is loaded.

```r
box::use(rhino[log])

# Simple messages
log$info("Application started")
log$warn("Missing configuration value")
log$error("Database connection failed")
```

--------------------------------

### Build Documentation Site

Source: https://github.com/appsilon/rhino/blob/main/AGENTS.md

Build the pkgdown documentation site. This command generates the user-facing documentation.

```r
devtools::build_site()
```

--------------------------------

### init()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

Initializes a new Rhino project. This function is used to set up the project structure and configuration.

```APIDOC
## init()

### Description
Initializes a new Rhino project.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
(Details not provided in source)

### Request Example
```R
init()
```

### Response
(Details not provided in source)
```

--------------------------------

### Dependency Management

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Functions for installing and removing R package dependencies.

```APIDOC
## pkg_install()

### Description
Installs specified R packages.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
- **packages** - Required - A list or vector of package names to install.

### Request Example
```r
pkg_install(packages = c("dplyr", "tidyr"))
```

### Response
Installation status
```

```APIDOC
## pkg_remove()

### Description
Removes specified R packages.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
- **packages** - Required - A list or vector of package names to remove.

### Request Example
```r
pkg_remove(packages = "old_package")
```

### Response
Removal status
```

--------------------------------

### Project Initialization

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `init()` function is used to initialize a new Rhino project. This is the first step in setting up a project.

```R
init()

```

--------------------------------

### Snapshot renv Environment

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/configuration.md

Updates the renv lockfile to reflect the current state of installed packages in the R environment.

```r
renv::snapshot()
```

--------------------------------

### Project Initialization

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Functions to help initialize and set up a new Rhino project with various configurations.

```APIDOC
## init()

### Description
Initialize new Rhino project.

### Function Signature
`init()`

### Module
`R/init.R`
```

```APIDOC
## use_e2e_tests()

### Description
Add Cypress E2E test structure.

### Function Signature
`use_e2e_tests()`

### Module
`R/init.R`
```

```APIDOC
## use_github_actions_ci()

### Description
Add GitHub Actions CI workflow.

### Function Signature
`use_github_actions_ci()`

### Module
`R/init.R`
```

```APIDOC
## use_agents_md()

### Description
Add AGENTS.md guidance file.

### Function Signature
`use_agents_md()`

### Module
`R/init.R`
```

--------------------------------

### init()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/init-and-setup.md

Generates the complete file structure for a new Rhino application. It can create a project in a specified directory with optional configurations for GitHub Actions CI, AI agent instructions, and E2E tests.

```APIDOC
## init()

### Description
Generates the complete file structure for a Rhino application.

### Parameters
#### Path Parameters
- **dir** (character) - Optional - Directory to create the application in. Defaults to ".".
- **github_actions_ci** (logical) - Optional - Whether to add GitHub Actions CI workflow. Defaults to TRUE.
- **agents_instructions** (logical) - Optional - Whether to add `AGENTS.md` file. Defaults to TRUE.
- **e2e_tests** (logical) - Optional - Whether to add Cypress E2E test structure. Defaults to TRUE.
- **rhino_version** (character) - Optional - Rhino version or source for `renv::install()` (e.g., "Appsilon/rhino@v0.4.0"). Defaults to "rhino".
- **force** (logical) - Optional - Force initialization in home directory. Defaults to FALSE.

### Returns
None. Called for side effects.

### Behavior
- **Home Directory Check**: By default refuses to initialize in the home directory to prevent accidental use. Set `force = TRUE` to override.
- **Dependency Detection**: Automatically detects dependencies from `dependencies.R` (if exists) or infers from `app/` directory
- **renv Initialization**: Sets up local package library via renv

### Examples
```r
# Create a new Rhino project in current directory
init()

# Create project with minimal setup
init(github_actions_ci = FALSE, e2e_tests = FALSE)

# Create project in a specific directory
init("./my-shiny-app")

# Override home directory protection
init("~/myproject", force = TRUE)
```
```

--------------------------------

### lint_js()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/code-quality.md

Lints JavaScript code using ESLint. It can optionally fix detected problems. Requires Node.js to be installed.

```APIDOC
## lint_js()

### Description
Lints JavaScript using ESLint.

### Method
```r
lint_js(fix = FALSE)
```

### Parameters
#### Path Parameters
- **fix** (logical) - Optional - If `TRUE`, automatically fixes problems

### Returns
None. Called for side effects.

### Description
Runs ESLint on JavaScript sources in the `app/js` directory. Requires Node.js.

**Global Objects**: Use `/* global OBJECT_NAME */` comments to define global objects used from other libraries (e.g., `/* global L */` for Leaflet). `Shiny` and `$` are defined by default.

**Disable Rules**: Use `// eslint-disable-next-line RULE_NAME` to disable specific rules for a line.

### Examples
```r
if (interactive()) {
  # Check for linting errors
  lint_js()
  
  # Automatically fix errors
  lint_js(fix = TRUE)
}
```
```

--------------------------------

### Nested List Destructuring Example

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/destructuring.md

Illustrates destructuring a nested named list, where the unpacked variables themselves become lists.

```r
# Example 3: Nested usage
config <- list(
  database = list(host = "localhost", port = 5432),
  api = list(url = "https://api.example.com", timeout = 30)
)

c(database, api) %<-% config
# Now database and api are lists themselves
```

--------------------------------

### Package Removal

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `pkg_remove()` function removes R packages from the system. This is useful for managing installed dependencies and freeing up space.

```R
pkg_remove()

```

--------------------------------

### Importing React Components

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Shows how to import and define a React component using Rhino's `react_component` utility.

```r
box::use(rhino[react_component])

MyComponent <- react_component("MyComponent")
```

--------------------------------

### Development Function Signatures

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Details signatures for development-related functions like 'devmode' and 'diagnostics', aiding in project setup and troubleshooting.

```r
# Development
devmode(build_sass = TRUE, build_js = TRUE, run_r_unit_tests = TRUE,
        auto_test_r_args = list(...), ...)
diagnostics()
```

--------------------------------

### Initializing Rhino App in Home Directory Error

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

Prevents creating a Rhino app directly in the user's home directory for safety. Use a specific subdirectory or set `force = TRUE` to override this protection.

```r
init("~")  # Would fail
```

```r
# Option 1: Create in subdirectory
init("~/my_projects/my_app")

# Option 2: Override protection
init("~", force = TRUE)
```

--------------------------------

### Use Box Modules in Main Application

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Demonstrates how to import and use modules from different parts of the application in the main R file. It integrates the dashboard UI and server.

```r
# app/main.R
box::use(
  app/view/dashboard,
  app/logic/data_processing
)

ui <- function(id) {
  ns <- shiny::NS(id)
  dashboard$ui(ns("dashboard"))
}

server <- function(id) {
  moduleServer(id, function(input, output, session) {
    dashboard$server("dashboard")
  })
}
```

--------------------------------

### Essential Commands for Running and Development

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Provides R code snippets for running the application, enabling development mode with auto-rebuild and tests, and executing unit tests.

```r
rhino::app()              # Run the application
rhino::devmode()          # Run with auto-rebuild and tests
rhino::test_r()           # Run unit tests
rhino::auto_test_r()      # Watch files and auto-run tests
```

--------------------------------

### Load Rhino Population Data

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/types.md

Loads the 'rhinos' dataset, which contains population data for rhino species. This is an example dataset for demonstrating Rhino functionality.

```r
data(rhinos)
```

--------------------------------

### Core Functions

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Provides the main entry point for the application and initialization routines.

```APIDOC
## app()

### Description
Starts the Rhino application.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
None

### Request Example
```r
app()
```

### Response
None (executes the application)
```

```APIDOC
## init()

### Description
Initializes a new Rhino project or sets up an existing one.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
- **dir** (string) - Optional - The directory to initialize the project in. Defaults to ".".
- **github_actions_ci** (boolean) - Optional - Whether to set up GitHub Actions CI. Defaults to TRUE.
- **agents_instructions** (boolean) - Optional - Whether to include agents instructions. Defaults to TRUE.
- **e2e_tests** (boolean) - Optional - Whether to set up end-to-end tests. Defaults to TRUE.
- **rhino_version** (string) - Optional - The version of Rhino to use. Defaults to "rhino".
- **force** (boolean) - Optional - Whether to force initialization, overwriting existing files. Defaults to FALSE.

### Request Example
```r
init(dir = "my_project", e2e_tests = FALSE)
```

### Response
None (initializes project files)
```

--------------------------------

### Initialization Function Signatures

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Lists the signatures for initialization functions, including 'init', 'use_e2e_tests', 'use_github_actions_ci', and 'use_agents_md'. These are used to set up a new Rhino project.

```r
# Initialization
init(dir = ".", github_actions_ci = TRUE, agents_instructions = TRUE, 
     e2e_tests = TRUE, rhino_version = "rhino", force = FALSE)
use_e2e_tests()
use_github_actions_ci()
use_agents_md()
```

--------------------------------

### Reactive Dependencies and Observation

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Illustrates how reactive expressions automatically update based on their dependencies and how `observe` can be used to log changes to reactive values or inputs.

```r
box::use(
  shiny[reactive, observe]
)

data_filtered <- reactive({
  # Automatically re-runs when input$filter changes
  filter_data(data(), input$filter)
})

plot_result <- reactive({
  # Depends on data_filtered, re-runs when filter changes
  create_plot(data_filtered())
})

# Track which reactive was used
observe({
  log$info("Filter changed: {input$filter}")
})
```

--------------------------------

### Logging with String Interpolation (Glue Syntax)

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/logging.md

Illustrates logging messages with dynamic content using glue syntax for string interpolation. Variables are embedded directly within the message string.

```r
box::use(rhino[log])

# Messages with string interpolation (glue syntax)
name <- "Rhino"
log$warn("Hello {name}!")

# Vector operations with glue
log$info("{1:3} + {1:3} = {2 * (1:3)}")
```

--------------------------------

### API Client Module Server

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

A reusable module server for interacting with an API. It handles GET requests, parses JSON responses, and includes error logging.

```r
box::use(
  shiny[reactive, moduleServer],
  rhino[log],
)

api_client_server <- function(id, base_url) {
  moduleServer(id, function(input, output, session) {
    get_data <- function(endpoint) {
      tryCatch({
        log$debug("GET {base_url}/{endpoint}")
        resp <- httr::GET(paste0(base_url, "/", endpoint))
        httr::content(resp, "parsed")
      },
      error = function(e) {
        log$error("API error: {e$message}")
        NULL
      })
    }
    
    list(
      get = get_data
    )
  })
}
```

--------------------------------

### Add AGENTS.md Guidance File

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Generates an AGENTS.md file to provide guidance on agent usage within the project.

```r
rhino::use_agents_md()
```

--------------------------------

### Standard Module Imports

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Shows how to import multiple components from different modules using box::use, including Shiny functions and custom app modules.

```r
box::use(
  shiny[moduleServer, reactive, observeEvent],
  app/view/dashboard,
  app/logic/data_processing,
)
```

--------------------------------

### app()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/app.md

Creates and runs a Rhino Shiny application. This is the primary entrypoint function that should be the only call in `app.R`. It orchestrates initialization and configuration tasks.

```APIDOC
## app()

### Description

Creates and runs a Rhino Shiny application. This is the primary entrypoint function that should be the only call in `app.R`. It orchestrates initialization and configuration tasks, including reading configuration, setting up the box module system, static file serving, logging, and loading the main module.

### Returns

A Shiny application object that can be passed to `shiny::runApp()`.

### Usage

```r
# app.R
# This is the only content your app.R file should contain
rhino::app()
```

### Details

The application loads `app/main.R` as a box module and expects it to export two functions: `ui(id)` and `server(id)`. Legacy entrypoint modes (`app_dir`, `source`, `box_top_level`) are supported for migration scenarios. Rhino also automatically registers autoreload callbacks for interactive development.
```

--------------------------------

### Shiny Module UI Function

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/types.md

Example of a standard Shiny module UI function within a Rhino application. It returns Shiny UI elements using `shiny::tagList`.

```r
# UI function
ui <- function(id) {
  # Return Shiny UI
  shiny::tagList(
    # UI elements
  )
}
```

--------------------------------

### Build Sass Stylesheets

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/code-quality.md

Builds Sass from `app/styles/main.scss` to `app/static/css/app.min.css`. The `watch` parameter is only supported with `sass: node`.

```R
build_sass(watch = FALSE)
```

```R
if (interactive()) {
  # Build once
  build_sass()
  
  # Keep building on changes (requires Node.js)
  build_sass(watch = TRUE)
}
```

--------------------------------

### Logging within Modules

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Demonstrates how to import and use the Rhino logging utility within a module to record events.

```r
box::use(rhino[log])

log$info("Processing data")
```

--------------------------------

### Shiny Module Server Function with Return Values

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/types.md

Example of a Shiny module server function in Rhino. It uses `shiny::moduleServer` and can optionally return a named list of reactive values.

```r
# Server function
server <- function(id) {
  shiny::moduleServer(id, function(input, output, session) {
    # Server logic
    # Optionally return reactive values
    list(
      reactive_value = reactive(...)
    )
  })
}
```

--------------------------------

### Validating File Paths for Linting in R

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

This example demonstrates calling `lint_r()` with a path that does not exist, triggering an 'Unexpected invalid path' error. Ensure the provided path is a valid file or directory.

```R
lint_r("nonexistent/path.R")  # Path doesn't exist
```

--------------------------------

### diagnostics()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/development.md

Prints system and environment diagnostic information, including OS, R version, Rhino version, and Node.js version, which is useful for troubleshooting Rhino issues.

```APIDOC
## diagnostics()

### Description
Prints system and environment diagnostic information useful for troubleshooting Rhino issues.

### Method
`diagnostics()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Returns
None. Called for side effects (prints diagnostic information).

### Description
Outputs the following diagnostic information:

- **System**: OS name, release, and version
- **R**: R version string
- **Rhino**: Installed Rhino package version
- **Node.js**: Installed Node.js version (if available)

This information is useful for:
- Reporting bugs
- Diagnosing compatibility issues
- Verifying system dependencies are installed

### Examples
```r
if (interactive()) {
  diagnostics()
}
```

### Output Example
```
Linux 5.4.0-42-generic #46-Ubuntu SMP Fri Jul 10 00:24:02 UTC 2020
R version 4.3.1 (2023-06-16) -- "Beagle Plays Chess"
rhino: 1.12.0
node: v18.16.1
```
```

--------------------------------

### Use Declared React Components in Shiny UI

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/react.md

Demonstrates how to use the R-declared React components within a Shiny UI function. This example shows rendering a 'TextBox' with a specific font size.

```r
box::use(
  shiny[tags],
  rhino[react_component],
)

TextBox <- react_component("TextBox")

ui <- function(id) {
  TextBox("Hello World", font_size = 20)
}
```

--------------------------------

### Declare and Use Multiple React Components in UI

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/react.md

Declares 'Button' and 'Card' React components in R and then uses them within a Shiny UI function. This example shows how to pass children and props to these components.

```r
box::use(
  shiny[div],
  rhino[react_component],
)

# Declare components
Button <- react_component("Button")
Card <- react_component("Card")

# Use in UI
ui <- function(id) {
  div(
    Card(
      "Card content",
      title = "My Card"
    ),
    Button(
      "Click me",
      onClick = "handleClick"
    )
  )
}
```

--------------------------------

### Import Specific Symbols

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Demonstrates how to import specific symbols from the 'rhino' package using `box::use`.

```APIDOC
## Importing Symbols with box::use

### Description
This section shows examples of importing specific functions and operators from the 'rhino' package using the `box::use` syntax. It highlights importing individual items, multiple items, and items from specific submodules (though submodule imports are not recommended).

### Method
Not applicable (import statement)

### Endpoint
Not applicable

### Parameters
- **box::use(...)** - The R command for importing modules.

### Request Example
```r
# Import specific functions
box::use(rhino[app, init, test_r, lint_r, log])

# Import an operator (must be quoted)
box::use(rhino[`%<-%`])

# Import multiple symbols with comments
box::use(
  rhino[
    # Testing
    test_r, auto_test_r, test_e2e, covr_r, covr_report,
    # Code quality
    lint_r, format_r, build_js, lint_js, format_js,
    build_sass, lint_sass, format_sass,
    # Dependencies
    pkg_install, pkg_remove,
    # Utilities
    log, devmode, diagnostics, react_component,
    # Operators
    `%<-%`,
  ],
)
```

### Response
Availability of imported functions and operators in the current R session.
```

--------------------------------

### System Command Execution Error

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

Indicates that an npm, node, or other system command failed with a non-zero exit status. Check the full error message and ensure system dependencies like Node.js and npm are installed and accessible.

```bash
# Install Node.js and npm
# Then retry the command
```

--------------------------------

### Handling Missing Keys During List Destructuring in R

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

When destructuring a list using %<-%, ensure that all variable names on the left-hand side exist as keys in the list on the right-hand side. This example shows how to correct a situation where a key is missing.

```R
# Wrong
data <- list(x = 1, y = 2)
c(x, z) %<-% data  # 'z' not in list

# Correct
c(x, y) %<-% data
```

--------------------------------

### Dynamic Module Creation

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Enables dynamic creation of child modules based on a reactive input. Uses renderUI and uiOutput to render modules on demand.

```r
box::use(
  shiny[moduleServer, renderUI, uiOutput],
)

dynamic_server <- function(id, num_modules) {
  moduleServer(id, function(input, output, session) {
    output$modules <- renderUI({
      lapply(seq_len(num_modules()), function(i) {
        child_module(paste0("child_", i))
      })
    })
  })
}
```

--------------------------------

### Create a Dashboard Module Server

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Implements the server logic for a dashboard module, rendering a plot and exposing reactive plot data. It utilizes `moduleServer` for encapsulation.

```r
# app/view/dashboard.R
box::use(
  shiny[div, moduleServer, reactive]
)

#' Dashboard UI
ui <- function(id) {
  ns <- shiny::NS(id)
  div(
    h1("Dashboard"),
    plotOutput(ns("plot"))
  )
}

#' Dashboard Server
server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$plot <- renderPlot({
      # Plot logic
    })
    
    list(
      plot_data = reactive({ ... })
    )
  })
}
```

--------------------------------

### Rhino Project File Structure

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Illustrates the standard directory layout for a Rhino project, including application code, tests, configuration, and static assets.

```text
project/
├── app.R                    # Entry point (just call rhino::app())
├── app/
│   ├── main.R             # UI and server
│   ├── view/              # UI modules
│   ├── logic/             # Business logic
│   ├── js/index.js        # JavaScript
│   ├── styles/main.scss   # Sass styles
│   └── static/            # Generated: CSS, JS, images
├── tests/
│   ├── testthat/          # Unit tests
│   └── cypress/           # E2E tests
├── rhino.yml              # Framework config
├── config.yml             # Logging config
├── dependencies.R         # Package dependencies
├── renv.lock             # Package versions
└── .Rproj                # RStudio project
```

--------------------------------

### Agents Guidance

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/GENERATED.txt

The `use_agents_md()` function provides guidance on using agents within the project. This function likely generates or displays documentation related to agent usage.

```R
use_agents_md()

```

--------------------------------

### Basic Module Server Definition

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Defines the server logic for a basic Shiny module, rendering a 'Hello!' message.

```r
# app/view/my_module.R
server <- function(id) {
  moduleServer(id, function(input, output, session) {
    output$text <- renderText("Hello!")
  })
}
```

--------------------------------

### build_sass()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/code-quality.md

Builds Sass from `app/styles/main.scss` to `app/static/css/app.min.css`. It supports different build methods configured in `rhino.yml` and can optionally watch for changes.

```APIDOC
## build_sass()

### Description

Builds Sass stylesheets using one of two methods configured in `rhino.yml`:

| Method | Tool | Recommended |
|--------|------|-------------|
| `node` | Dart Sass (Node.js) | Yes, actively maintained |
| `r` | `sass` R package | Fallback, uses deprecated LibSass |
| `custom` | User's own build process | Custom setup, no default action |

The `watch` parameter is only supported with `sass: node`.

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `watch` | logical | `FALSE` | If `TRUE`, keeps process running and rebuilds on changes (Node.js only) |

### Returns

None. Called for side effects.

### Examples

```r
if (interactive()) {
  # Build once
  build_sass()
  
  # Keep building on changes (requires Node.js)
  build_sass(watch = TRUE)
}
```
```

--------------------------------

### Configuration Module Server

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

A module server for managing application configuration. It uses the 'config' package to load settings and exposes them reactively.

```r
box::use(
  shiny[reactive, moduleServer],
  config,
)

config_server <- function(id) {
  moduleServer(id, function(input, output, session) {
    app_config <- reactive({
      config::get()
    })
    
    list(
      config = app_config,
      log_level = reactive(app_config()$rhino_log_level)
    )
  })
}
```

--------------------------------

### Add AGENTS.md file to Rhino project

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/init-and-setup.md

Creates an `AGENTS.md` file at the project root with guidance for AI coding agents. This is automatically handled by `init()` unless `agents_instructions = FALSE`.

```r
use_agents_md()
```

```r
if (interactive()) {
  use_agents_md()
}
```

--------------------------------

### Error Recovery with Try-Catch

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Implement error recovery in module servers using tryCatch to handle potential errors during data loading. Logs success or failure messages.

```r
box::use(
  shiny[moduleServer, reactive],
  rhino[log],
)

data_loader_server <- function(id, url) {
  moduleServer(id, function(input, output, session) {
    data <- reactive({
      tryCatch(
        {
          log$info("Loading data from {url}")
          result <- read_from_api(url)
          log$success("Data loaded successfully")
          result
        },
        error = function(e) {
          log$error("Failed to load data: {e$message}")
          NULL
        }
      )
    })
    
    list(data = data)
  })
}
```

--------------------------------

### Import Specific Symbols with box

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Demonstrates importing specific functions and operators from the 'rhino' package using the 'box::use' syntax. This allows for selective loading of functionalities.

```r
box::use(
  rhino[app, init, test_r, lint_r, log]
)
```

```r
box::use(
  rhino[`%<-%`]
  # Operator must be quoted
)
```

```r
box::use(
  rhino[
    # Testing
    test_r, auto_test_r, test_e2e, covr_r, covr_report,
    # Code quality
    lint_r, format_r, build_js, lint_js, format_js,
    build_sass, lint_sass, format_sass,
    # Dependencies
    pkg_install, pkg_remove,
    # Utilities
    log, devmode, diagnostics, react_component,
    # Operators
    `%<-%`,
  ]
)
```

--------------------------------

### Build JavaScript with build_js()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/code-quality.md

Builds and minifies JavaScript from app/js/index.js to app/static/js/app.min.js using Babel and webpack. Supports ES6+ and can optionally watch for changes and rebuild automatically.

```r
if (interactive()) {
  # Build once
  build_js()
  
  # Keep building on changes
  build_js(watch = TRUE)
}
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/appsilon/rhino/blob/main/AGENTS.md

Execute all package unit tests using devtools. Ensure this command is run to verify code integrity.

```r
devtools::test()
```

--------------------------------

### Build JavaScript

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/quick-reference.md

Compiles JavaScript files. The 'watch = TRUE' option enables automatic rebuilding when source files change.

```r
rhino::build_js(watch = TRUE)
```

--------------------------------

### Module Server with Validation and Error Messages

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/module-patterns.md

Implements a module server that validates incoming data, displaying error messages if data is missing or empty before rendering. It logs successful rendering.

```r
box::use(
  shiny[moduleServer, reactive, validate, need],
  rhino[log]
)

data_display_server <- function(id, data) {
  moduleServer(id, function(input, output, session) {
    output$display <- renderText({
      validate(
        need(!is.null(data()), "No data available"),
        need(nrow(data()) > 0, "Data is empty")
      )
      
      log$info("Rendering data with {nrow(data())} rows")
      format_data(data())
    })
  })
}
```

--------------------------------

### Run Unit Tests with test_r()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/testing.md

Executes all unit tests in the `tests/testthat` directory. It purges the box module cache before running tests to ensure fresh module loading. Use this to run your standard unit test suite.

```r
test_r()

# Run tests with specific reporter
test_r(reporter = testthat::default_reporter())
```

--------------------------------

### Importing a Package with box::use and Accessing via $

Source: https://github.com/appsilon/rhino/blob/main/inst/templates/agents_md/AGENTS.md

Use this method when importing more than 8 functions from a package or script. Access functions using the '$' operator.

```r
box::use(
  dplyr,
)
dplyr$filter(mtcars, cyl > 4)
```

--------------------------------

### Function Signatures Summary

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Summary of the most used and all available functions with their signatures.

```APIDOC
## Function Signatures Summary

### Most Used

- `app()`
- `init(dir = ".", github_actions_ci = TRUE, e2e_tests = TRUE)`
- `test_r()`
- `devmode()`
- `pkg_install(packages)`
- `lint_r(paths = NULL)`
- `format_r(paths, exclude_files = NULL)`
- `log$info(message)  # Also: error, warn, debug, trace, fatal, success

### All Functions

See [API Reference](api-reference/) for complete signatures and documentation.
```

--------------------------------

### Development Utilities

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/exported-symbols.md

Tools to aid in development, such as setting up development mode and diagnostics.

```APIDOC
## devmode()

### Description
Enters development mode, enabling features like hot-reloading and automatic testing.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
- **build_sass** (boolean) - Optional - Whether to enable Sass building in dev mode. Defaults to TRUE.
- **build_js** (boolean) - Optional - Whether to enable JavaScript building in dev mode. Defaults to TRUE.
- **run_r_unit_tests** (boolean) - Optional - Whether to run R unit tests in dev mode. Defaults to TRUE.
- **auto_test_r_args** (list) - Optional - Arguments to pass to `auto_test_r()`.
- **...** - Additional arguments.

### Request Example
```r
devmode(build_js = FALSE)
```

### Response
None (enters development mode)
```

```APIDOC
## diagnostics()

### Description
Runs diagnostic checks on the project setup and environment.

### Method
Not applicable (function call)

### Endpoint
Not applicable

### Parameters
None

### Request Example
```r
diagnostics()
```

### Response
Diagnostic report
```

--------------------------------

### Logging in Modules

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/README.md

Use the `log` object from the `rhino` package to log messages at different severity levels within your modules. Ensure `rhino` is loaded using `box::use`.

```r
box::use(rhino[log])

log$info("Starting module")
log$warn("Missing data: {variable_name}")
log$error("Calculation failed")
```

--------------------------------

### Format JavaScript Files

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/code-quality.md

Runs Prettier on JavaScript files in the app/js directory. Use `// prettier-ignore` comments to skip formatting specific code chunks.

```R
if (interactive()) {
  # Fix formatting issues
  format_js()
  
  # Only check for formatting errors
  format_js(fix = FALSE)
}
```

--------------------------------

### use_agents_md()

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/api-reference/init-and-setup.md

Adds an `AGENTS.md` file to the project root, providing guidance for AI coding agents.

```APIDOC
## use_agents_md()

### Description
Adds `AGENTS.md` file with guidance for AI coding agents.

### Returns
None. Called for side effects.

### Conflict Handling
If `AGENTS.md` already exists:
- **Interactive session**: Prompts to abort (default) or back up the existing file
- **Non-interactive session**: Aborts with an error

### Examples
```r
if (interactive()) {
  use_agents_md()
}
```
```

--------------------------------

### Missing Rhino Configuration File Error

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/errors.md

This error occurs when `app()` is called without a `rhino.yml` or `rhino.yaml` file in the project root. Ensure the configuration file exists in the project's root directory.

```yaml
# rhino.yml
sass: node
```

--------------------------------

### Create Option Validator

Source: https://github.com/appsilon/rhino/blob/main/_autodocs/types.md

Shows how to create an option validator using `option_validator(...)`. This returns a list containing a 'check' function and a 'help' string for validating enumerated values.

```r
option_validator(...) -> list(check, help)
```