AGENTS.md · transloadit/uppy

Sections

1. Repository Overview
2. Development Commands
3. Architecture
4. Build System
5. Code Standards
6. Testing
7. Companion Server
8. Important Notes

First lines (shown under the repo's MIT license)

# Uppy Repository Guide

This file provides repository guidance for coding agents. Maintain shared instructions here.

## Repository Overview

Uppy is a modular JavaScript file uploader that integrates seamlessly with any application. It’s
built using a monorepo structure with Yarn workspaces, Turbo for build orchestration, and Biome for
linting/formatting.

## Development Commands

### Core Commands

- `yarn build` - Build all packages (uses Turbo)
- `yarn build:watch` - Watch mode for building packages
- `yarn test` - Run tests for all packages
- `yarn test:watch` - Run tests in watch mode
- `yarn typecheck` - Type checking across all packages
- `yarn check` - Run Biome linting and formatting
- `yarn check:ci` - Run Biome in CI mode (no writes)

### Development Server

- `yarn dev` - Start development server (from private/dev workspace)
- `yarn dev:with-companion` - Start dev server with Companion backend
- `yarn start:companion` - Start only the Companion server

### Single Test Execution

To run tests for a specific package:

```bash
yarn workspace @uppy/[package-name] test
# Example: yarn workspace @uppy/core test
```

### Individual Package Development

```bash
yarn workspace @uppy/[package-name] build
```

## Architecture

### Monorepo Structure

- `packages/@uppy/` - Core Uppy packages (plugins, utilities)
- `packages/uppy/` - Main bundle package
- `examples/` - Example implementations for various frameworks
- `private/` - Internal development tools

### Core Architecture

- **Uppy Core** (`@uppy/core`) - Main class that manages plugins, state, and events
- **Plugins** - Modular components for different functionalities:
  - **UI Plugins**: Dashboard, Drag & Drop, File Input, Webcam, etc.
  - **Provider Plugins**: Google Drive, Dropbox, etc. (require Companion)
  - **Uploader Plugins**: Tus (resumable), XHR Upload, AWS S3, etc.
  - **Utility Plugins**: Golden Retriever (recovery), Thumbnail Generator, etc.

### Plugin Types

1. **Acquirer** - Gets files (File Input, Webcam, Google Drive)
2. **Modifier** - Modifies files (Image Editor, Compressor)
3. **Uploader** - Uploads files (Tus, XHR, AWS S3)
4. **Presenter** - Shows UI (Dashboard, Progress Bar, Status Bar)
5. **Orchestrator** - Manages workflow
6. **Logger** - Handles logging

### Key Packages

- `@uppy/core` - Main Uppy class and plugin system
- `@uppy/dashboard` - Complete UI with file management
- `@uppy/companion` - Server-side component for remote providers
- `@uppy/companion-client` - Client for communicating with Companion
- `@uppy/utils` - Shared utilities
- `@uppy/components` - Headless Preact components (with framework wrappers)

## Build System

### Turbo Configuration

The build system uses Turbo (turbo.json) for task orchestration:

- Builds have dependency ordering (`dependsOn: ["^build"]`)
- TypeScript builds output to `lib/` and `dist/` directories
- CSS builds process SCSS files to CSS
- Specific handling for the main `uppy` package bundle

### TypeScript Configuration

- Individual packages have `tsconfig.json` and `tsconfig.build.json`
- Build outputs include declaration files (.d.ts) and source maps

## Code Standards

### Linting and Formatting

- **Biome** is used for linting and formatting (replaces ESLint/Prettier)
- Configuration in `biome.json`
- Use single quotes, semicolons as needed
- 2-space indentation

### Framework Integration

- **Preact** for UI components with framework wrappers generated for React, Vue, Svelte
- **TypeScript** throughout the codebase
- Components in `@uppy/components` use Tailwind CSS with `uppy:` prefix

### Plugin Development

- All plugins extend `BasePlugin` or `UIPlugin`
- Plugins must have unique IDs and specify their type
- State management through Uppy’s store system
- Event-driven architecture using namespace-emitter

## Testing

### Test Framework

- **Vitest** for unit tests (migrated from Jest)
- **Vitest Browser Mode** for browser testing (migrated from Cypress)
- Unit tests use `.test.{ts,tsx}` extensions and browser tests `.browser.test.{ts,tsx}`

### Running Tests

- Tests run in parallel across packages via Turbo
- Examples also include tests (React, Vue, SvelteKit examples)
- Use `yarn test` for development

## Companion Server

The Companion server enables integration with remote file sources:

- Handles OAuth flows for providers like Google Drive, Dropbox
- Proxies file downloads to avoid CORS issues
- Provides search functionality for providers
- Located in `packages/@uppy/companion/`

## Important Notes

- Never commit sensitive information (API keys, tokens)
- Follow existing code conventions and patterns within each package
- Use the `@uppy/utils` package for shared functionality
- UI components should be accessible and support internationalization
- Always run `yarn check` and `yarn typecheck` before committing
- When adding a new component to `@uppy/components`, you have to run `yarn migrate:components` from
  root. This is not needed for changing existing components.