Foundry VTT React + Shadcn UI Boilerplate

A modern, production-ready boilerplate for building Foundry VTT modules using React, TypeScript, Tailwind CSS, and Shadcn UI components.

🚀 Features

• React 18 with TypeScript for type-safe component development
• Shadcn UI components for beautiful, accessible UI elements
• Tailwind CSS for utility-first styling
• Vite for fast development and optimized builds
• Foundry VTT v12+ compatibility (tested on v13)
• ApplicationV2 API for modern Foundry window management
• Hot Module Replacement support for development
• Example Implementation demonstrating business management features

📋 Prerequisites

• Node.js v18 or higher
• Foundry VTT v12 or higher (v13 recommended)
• Basic knowledge of React, TypeScript, and Foundry VTT module development

🛠️ Quick Start

1. Clone or Use This Repository

git clone <your-repo-url>
cd foundryvtt-react-shadcn-boilerplate

2. Install Dependencies

npm install

3. Customize Your Module

Before building, you'll want to customize the module for your needs:

1. Update module.json:

   • Change the id, title, and description fields
   • Update pack names if you're using compendiums
   • Modify system compatibility if needed

2. Update package.json:

   • Change the name and description fields

3. Update src/main.tsx:

   • Replace MODULE_ID constant with your module ID
   • Rename MainApp and BusinessManagerApp classes to match your module
   • Customize the scene control buttons (names, icons, titles)
   • Update template paths if you rename templates
   • Important: Update CSS class names - do a find-and-replace for foundry-capital-module to your module's class name in:
     • src/styles/global.css
     • tailwind.config.js (the important property)
     • src/main.tsx (in classes arrays)
     • Any component files using the class

4. Update vite.config.ts:

   • Change the output file name to match your module ID

5. Customize Components:

   • Modify src/App.tsx to build your main interface
   • Update or remove src/components/BusinessManager.tsx (this is just an example)
   • Add your own components in src/components/

6. Update Templates:

   • Modify templates/app.hbs and templates/business-manager.hbs as needed
   • Ensure root element IDs match what you use in main.tsx

4. Build the Module

npm run build

This creates a dist/ directory with:

• Your compiled JavaScript bundle
• Compiled CSS styles
• module.json (copied from root)

5. Link to Foundry VTT

You need to place this module in your Foundry VTT Data/modules folder.

Mac/Linux (Symlink - Recommended for Development):

ln -s "$(pwd)" ~/Library/Application\ Support/FoundryVTT/Data/modules/your-module-id

Windows (Symlink):

mklink /D "C:\Users\YourName\AppData\Local\FoundryVTT\Data\modules\your-module-id" "C:\Path\To\This\Project"

Alternative (Copy Method): Simply copy the entire project folder to your Foundry Data/modules directory. Note: You'll need to rebuild and copy the dist/ folder after each change.

6. Enable in Foundry VTT

1. Launch Foundry VTT
2. Log in as a Gamemaster
3. Go to Game Settings → Manage Modules
4. Find your module and enable it
5. Click Save Module Settings

7. Use Your Module

Look for your module's button in the Scene Controls (left sidebar). The example includes buttons in the Token Controls section.

🏗️ Project Structure

foundryvtt-react-shadcn-boilerplate/
├── src/
│   ├── components/          # React components
│   │   ├── ui/             # Shadcn UI components
│   │   ├── BusinessManager.tsx  # Example component
│   │   └── ...
│   ├── systems/            # Foundry system logic
│   │   ├── CampaignManager.ts
│   │   └── ...
│   ├── styles/
│   │   └── global.css      # Global styles + Tailwind
│   ├── types/
│   │   └── foundry-shim.d.ts  # TypeScript definitions
│   ├── App.tsx             # Main React app component
│   └── main.tsx            # Foundry module entry point
├── templates/              # Handlebars templates
│   ├── app.hbs
│   └── business-manager.hbs
├── packs/                  # Optional: Compendium packs (see packs/README.md)
│   ├── npcs/              # Actor compendium (if needed)
│   ├── items/             # Item compendium (if needed)
│   └── scenes/            # Scene compendium (if needed)
├── assets/                 # Optional: Static assets (see assets/README.md)
│   ├── icons/             # Custom icons (if needed)
│   ├── images/            # Images (if needed)
│   └── sounds/            # Sound files (if needed)
├── dist/                   # Build output (generated)
├── module.json             # Foundry module manifest
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── tsconfig.json

About Packs

The packs/ directory is optional and currently empty. This boilerplate creates entities programmatically (see src/systems/CampaignManager.ts) rather than using compendium packs.

If you need compendium packs:

• See packs/README.md for detailed instructions
• Uncomment the packs section in module.json
• Add your pack content to the appropriate subdirectories

If you don't need packs:

• You can safely ignore or delete the packs/ directory
• The packs section in module.json is commented out by default

About Assets

The assets/ directory is optional and currently empty. This boilerplate uses Foundry's built-in Font Awesome icons and doesn't require custom assets.

If you need custom assets:

• See assets/README.md for detailed instructions
• Add your images, icons, or sounds to the appropriate subdirectories
• Reference them in your code using the module path format

If you don't need assets:

• You can safely ignore or delete the assets/ directory

🎨 Adding Shadcn UI Components

This boilerplate includes Shadcn UI setup. To add more components:

npx shadcn-ui@latest add [component-name]

For example:

npx shadcn-ui@latest add dialog
npx shadcn-ui@latest add dropdown-menu

Components will be added to src/components/ui/.

🧩 Example Features

This boilerplate includes a working example of a business management system to demonstrate:

• React state management with hooks
• Foundry API integration (game, ui, etc.)
• Application windows using Foundry's ApplicationV2
• Scene control buttons for easy access
• Shadcn UI components (Button, Card, etc.)
• Custom styling with Tailwind CSS

You can use this as a reference or remove it entirely and build your own features.

🔧 Development

Development Server

For development with hot-reloading, you can use:

npm run dev

Note: Hot-reloading requires additional proxy setup to work with Foundry VTT. For most development, you'll want to:

1. Make changes to your code
2. Run npm run build
3. Refresh Foundry VTT (F5)

TypeScript

The project uses strict TypeScript. Type definitions for Foundry are provided in src/types/foundry-shim.d.ts. You may need to extend these based on your Foundry version.

Styling

• Tailwind CSS: Utility classes for rapid UI development
• Global CSS: Custom styles in src/styles/global.css
• Shadcn UI: Pre-built accessible components

📦 Building for Production

npm run build

The build output in dist/ is ready for distribution. Make sure to:

1. Test thoroughly in Foundry VTT
2. Update module.json with proper version numbers
3. Update repository URLs in module.json if publishing
4. Consider minification and optimization (Vite handles this)

🐛 Debugging

1. Open Foundry DevTools: Press F12 or Cmd + Option + I (Mac)
2. Console Tab: Look for logs prefixed with your module ID
3. Network Tab: Verify module.json and your JS bundle are loading
4. Source Maps: Enable in vite.config.ts for better debugging:

   build: {
     sourcemap: true,
     // ...
   }

📚 Key Concepts

Module ID

Your module ID (defined in module.json and src/main.tsx) should be:

• Unique
• Lowercase
• Use hyphens instead of spaces
• Match your module folder name

Application Windows

The boilerplate uses Foundry's ApplicationV2 API with HandlebarsApplicationMixin:

• Modern window management
• React integration via root elements
• Proper cleanup on window close

React Integration

React apps are mounted into Handlebars template root elements:

1. Handlebars template provides the container
2. React mounts into that container
3. React handles all UI logic and state

🤝 Contributing

This is a boilerplate template. Feel free to:

• Fork and customize for your needs
• Submit improvements via pull requests
• Report issues or suggest features

📄 License

This boilerplate is provided as-is. Check the LICENSE file for details, or add your own license.

🎯 Next Steps

1. Customize the module for your specific use case
2. Add your features in src/components/ and src/systems/
3. Style with Tailwind and Shadcn UI components
4. Test thoroughly in Foundry VTT
5. Build and distribute your module

💡 Tips

• Keep your module ID consistent across all files
• Use TypeScript for better development experience
• Leverage Shadcn UI components for rapid UI development
• Test with different Foundry versions if targeting multiple
• Use Foundry's hooks system (Hooks.on, Hooks.once) for integration
• Check Foundry VTT documentation for API details

🔗 Resources

• Foundry VTT Documentation
• React Documentation
• Shadcn UI
• Tailwind CSS
• Vite Documentation

---

Happy Module Building! 🎲