CLAUDE.mdtypescript

anthropic_dashboard CLAUDE.md

This file provides guidance to LLM coding agents when working with this Shiny-React application.

View Source

CLAUDE.md

This file provides guidance to LLM coding agents when working with this Shiny-React application.

Project Overview

This is newapp, a Shiny-React application created from a template. This project uses the Shiny-React library to enable bidirectional communication between React frontend components and Shiny servers.

Architecture:

  • Frontend: React with TypeScript using shiny-react hooks
  • Backend: Shiny server (both R and Python versions available)
  • Communication: Real-time data flow via shiny-react library
  • Build System: ESBuild bundling for fast development

Tools

You may have access to a shadcn MCP server. If so, use it to find and install UI components when the user asks you to implement UI.

IMPORTANT: in most casees, the user will already be running npm run dev while you are working, so you do not need to run npm run build yourself, or start the Shiny app with npm run shinyapp. If you want to know whether a build is working, ask the user what the output is from the relevant command, and offer to run it if they are not doing so already.

Directory Structure

newapp/
├── package.json            # Build configuration and npm dependencies
├── tsconfig.json           # TypeScript configuration
├── CLAUDE.md               # This file - instructions for LLM coding agents
├── SHINY-REACT.md          # Comprehensive shiny-react library documentation
├── srcts/                  # React TypeScript source code
│   ├── main.tsx            # React app entry point
│   ├── *.tsx               # React components using shiny-react hooks
│   └── styles.css/globals.css  # CSS styling
├── r/                      # R Shiny backend
│   ├── app.R               # Main R Shiny application
│   ├── shinyreact.R        # R functions for shiny-react
│   └── www/                # Built JavaScript/CSS output (auto-generated)
│       ├── main.js         # Compiled React code for R backend
│       └── main.css        # Compiled CSS for R backend
└── py/                     # Python Shiny backend
    ├── app.py              # Main Python Shiny application
    ├── shinyreact.py       # Python functions for shiny-react
    └── www/                # Built JavaScript/CSS output (auto-generated)
        ├── main.js         # Compiled React code for Python backend
        └── main.css        # Compiled CSS for Python backend

Key Files and Their Purpose

Frontend (React/TypeScript)

  • srcts/main.tsx: Entry point that mounts the React app to the DOM
  • srcts/*.tsx: React components using shiny-react hooks
  • srcts/styles.css: Application styling

Backend (Shiny)

  • r/app.R or py/app.py: Main Shiny server application
  • r/shinyreact.R or py/shinyreact.py: Utility functions for bare page setup and custom renderers
  • r/www/ or py/www/: Auto-generated build output (JavaScript and CSS bundles)

Available npm Scripts

This application includes several npm scripts for different development and build workflows:

Development Scripts (Recommended)

  • npm run dev - 🚀 Primary development command - Builds frontend and starts Shiny server automatically with hot-reload
  • npm run watch - 👀 Frontend-only watching - Watch TypeScript/React files for changes and rebuild automatically
  • npm run shinyapp - 🖥️ Backend-only server - Start only the Shiny server (Python by default)

Build Scripts

  • npm run build - 🔨 Development build - Build frontend once with TypeScript checking and CSS processing
  • npm run build-prod - 📦 Production build - Optimized build with minification (advanced templates)
  • npm run clean - 🧹 Clean build - Remove all generated build files

Port Configuration

You can customize the port (default is 8000):

# Use custom port
PORT=3000 npm run dev
PORT=3000 npm run shinyapp

Quick Start Development Workflow

Method 1: All-in-One Development (Recommended)

# Install dependencies
npm install

# Start development with hot-reload (builds frontend + starts server)
npm run dev

This single command will:

  • Build the TypeScript/React frontend with CSS processing
  • Start the Shiny server with hot-reload enabled
  • Automatically open your browser to http://localhost:8000
  • Watch for changes and rebuild/restart as needed

Method 2: Manual Development Setup

If you prefer more control, you can run the frontend and backend separately:

  1. Start build watcher (in one terminal):

    npm run watch

  2. Run Shiny server (in another terminal):

    # For R backend
R -e "options(shiny.autoreload = TRUE); shiny::runApp('r/app.R', port=8000)"

# For Python backend
shiny run py/app.py --port 8000 --reload

  3. Open browser: Navigate to http://localhost:8000

Production Deployment

For production builds:

# Create optimized production build
npm run build-prod

# Deploy the generated www/ directories along with your Shiny app

How Shiny-React Works

Core Concepts

  • useShinyInput<T>(id, defaultValue): Sends data FROM React TO Shiny server
  • useShinyOutput<T>(id, defaultValue): Receives data FROM Shiny server TO React
  • Real-time bidirectional communication: Changes in React trigger server updates, server responses update React UI

Basic Example

import { useShinyInput, useShinyOutput } from "@posit/shiny-react";

function MyComponent() {
  const [inputValue, setInputValue] = useShinyInput<string>("my_input", "default");
  const [outputValue] = useShinyOutput<string>("my_output", undefined);

  return (
    <div>
      <input value={inputValue} onChange={(e) => setInputValue(e.target.value)} />
      <div>Server says: {outputValue}</div>
    </div>
  );
}

Common Development Tasks

Starting Development

  • Quick start: Run npm run dev - Starts both frontend building and backend server with hot-reload
  • Frontend only: Run npm run watch - Rebuilds frontend on file changes
  • Backend only: Run npm run shinyapp - Starts only the Shiny server

Adding a New Input/Output Pair

  1. In React component: Add useShinyInput and useShinyOutput hooks
  2. In Shiny server: Add corresponding input handler and output renderer
  3. Automatic rebuild: Changes are detected automatically with watch mode

Adding New React Components

  1. Create component file in srcts/ directory
  2. Import and use in main component or main.tsx
  3. Follow shiny-react patterns for any Shiny communication
  4. Update styling in styles.css or globals.css if needed

Modifying Backend Logic

  • R: Edit r/app.R for server logic, r/shinyreact.R for utilities
  • Python: Edit py/app.py for server logic, py/shinyreact.py for utilities
  • No rebuild needed for backend changes (Shiny auto-reloads)

Making Production Builds

  • Development build: Run npm run build
  • Production build: Run npm run build-prod (if available)
  • Clean build: Run npm run clean to remove generated files

Troubleshooting

Common Issues

  1. "Shiny not found" errors: Ensure Shiny server is running and accessible
  2. Build failures: Check that all dependencies are installed (npm install)
  3. Hot reload not working: Restart development mode
  4. Data not syncing: Verify matching input/output IDs between React and Shiny
  5. TypeScript errors: Check type definitions and imports
  6. Port already in use: Use PORT=<number> npm run dev to change the port

Development Tips

  • Use browser DevTools: Check console for React/JavaScript errors
  • Monitor Shiny logs: Watch R/Python console for server-side errors
  • Verify IDs match: Input/output IDs must be identical in React and Shiny code
  • Check network tab: Verify WebSocket communication between client and server

Port Conflicts

If port 8000 is in use:

# Use environment variable (recommended)
PORT=8001 npm run dev

# Or manual server startup
R -e "shiny::runApp('r/app.R', port=8001)"
shiny run py/app.py --port 8001

Key Dependencies

  • @posit/shiny-react: Core library for React-Shiny communication
  • react + react-dom: React framework
  • typescript: TypeScript compiler and type checking
  • esbuild: Fast JavaScript bundling

Comprehensive Shiny-React Documentation

📚 For complete API reference, advanced patterns, and detailed examples, see: @SHINY-REACT.md

The SHINY-REACT.md file contains:

  • Complete API documentation for all hooks and components
  • Advanced input patterns (file uploads, compound forms, etc.)
  • Debouncing and event priority concepts
  • Server-to-client messaging
  • Backend patterns for R and Python
  • Shiny reactivity system explanation
  • Data serialization details
  • shadcn/ui integration guide
  • Troubleshooting and best practices