---
name: foundryvtt-modding
description: Guidance on FoundryVTT module and custom system development using TypeScript, Vite, or Rollup.
disable-model-invocation: false
category: GameDev
risk: safe
tags:
  - foundryvtt
  - typescript
  - modding
  - javascript
---

# FoundryVTT Modding

## Purpose

To guide the development of custom FoundryVTT modules and systems, emphasizing TypeScript configuration, modern build tools (Vite/Rollup), schema structures (`module.json`), Actor/Item sheet architecture, and hook lifecycles.

## When to Use

Use when writing, refactoring, or structuring TypeScript/JavaScript code for FoundryVTT modules or systems, defining manifest metadata, or hooking into Foundry's rendering lifecycle.

## TypeScript & Build Configuration

- Use `@league-of-foundry-developers/foundry-vtt-types` for autocomplete and type safety of the `game`, `canvas`, and other global variables.
- Configure `tsconfig.json` to target ES2022+ and resolve modules correctly.
- Set up `vite.config.ts` or `rollup.config.js` to bundle files into a single distribution file under `dist/` and copy assets/templates.

## Manifest Layout (`module.json` / `system.json`)

Ensure the manifest contains clean references to script entrypoints:
```json
{
  "id": "my-module",
  "title": "My Foundry Module",
  "description": "Custom additions for Homebrew Magic",
  "version": "1.0.0",
  "compatibility": {
    "minimum": "11",
    "verified": "12"
  },
  "esmodules": ["dist/module.mjs"],
  "styles": ["styles/module.css"]
}
```

## Lifecycle Hooks

Standardize hook registrations to keep initialization organized:
- `init`: Register game settings, active effect keys, and customize configuration structures (`CONFIG`).
- `setup`: Perform setups dependent on settings availability.
- `ready`: Execute scripts that require canvas or database collections to be fully loaded.

```typescript
Hooks.once("init", () => {
  console.log("Initializing Homebrew Magic Module");
  
  // Register custom sheets
  Actors.registerSheet("homebrew-magic", CustomActorSheet, {
    makeDefault: true
  });
});
```