Terraria Companion

A self-contained web app for searching Terraria items, exploring crafting trees, and tracking recipe progress — all powered by data from the Terraria Wiki.

---

Features

• Item Search — Fast, ranked search across 5000+ Terraria items (exact > prefix > contains)
• Crafting Trees — Recursive visualization of crafting recipes with ingredients and stations
• Drop Information — See which enemies and bosses drop an item, with quantity and drop rates
• Pinned Recipes — Save favorite recipes for quick reference
• Owned Item Tracking — Mark ingredients you already have; tracks progress per recipe
• Auto-Collapse — Owned items in recipe trees collapse automatically to reduce clutter
• Terraria-Style Tooltips — Hover over items to see damage, defense, knockback, sell price, and more
• Light / Dark Mode — Adapts to your system color scheme
• Single Binary — Everything embeds into one executable with zero external dependencies
• Cross-Platform — Builds for Linux and macOS (amd64 and arm64)

Quick Start

Prerequisites

• Go 1.24+

1. Fetch data from the Terraria Wiki

make fetch

This downloads items, recipes, drops, and icons into the data/ and public/icons/ directories. The process is resumable — if interrupted, just run it again.

2. Build and run

make serve

Open http://localhost:3000 in your browser.

Development mode

make dev

Serves frontend assets from disk and hot-reloads data files on change.

Usage

Action	How
Search for an item	Type in the search box (min 2 characters)
View crafting tree	Click any item from search results
See drop sources	Scroll down on an item page
Pin a recipe	Click the pin icon on a recipe
Track owned items	Check the boxes next to ingredients you have
View pinned recipes	Navigate to /pins

Deployment

Docker Compose

services:
  terraria-companion:
    image: git.nakama.town/fmartingr/terraria-companion:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/data:ro
      - ./public/icons:/app/public/icons:ro
    environment:
      - PORT=3000
      # - ANALYTICS_SCRIPT=<script defer src="https://analytics.example.com/script.js" data-website-id="YOUR_ID"></script>

docker-compose up -d

Standalone binary

# Build with embedded data (single portable executable)
make build

# Run it
./terraria-companion

Environment variables

Variable	Default	Description
PORT	3000	HTTP server port
DEV	(unset)	Set to any value to enable development mode
ANALYTICS_SCRIPT	(unset)	Raw HTML <script> tag injected before </head> (e.g. Umami, Plausible)

API

All endpoints return JSON.

Endpoint	Parameters	Description
GET /api/search	q (min 2 chars)	Search items by name
GET /api/item	name	Get a single item
GET /api/recipes	item	Get crafting recipes for an item
GET /api/drops	item	Get drop sources for an item
GET /api/splashes	—	Get random splash text strings
GET /api/status	—	Server status and item counts

Building

make help          # Show all available targets
make build         # Production binary with embedded data
make build-nodata  # Binary that reads data from disk at runtime
make build-snapshot # Cross-platform builds via goreleaser
make fetch         # Fetch/resume wiki data
make fetch-reset   # Reset and fetch from scratch
make dev           # Development mode with hot-reload
make format        # Format Go source
make lint          # Run linter
make clean         # Remove build artifacts
make clean-data    # Remove fetched data

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Fetch the data (make fetch)
4. Run in dev mode (make dev)
5. Make your changes
6. Format and lint (make format && make lint)
7. Commit and push
8. Open a pull request

License

This project fetches data and images from the Terraria Wiki. Terraria is developed by Re-Logic. All game assets and data belong to their respective owners.