README.md

---
title: Imageboard Grabber
emoji: 🖼️
colorFrom: indigo
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# Imageboard Grabber

Booru-style imageboard grabber (inspired by Bionus/Grabber): tag search, thumbnail grid, multi-select, server-side batch ZIP download. Ships with **e621** preconfigured and a **schema-based "Add site" panel** for Danbooru/Gelbooru/Safebooru/etc.

## Features

- **Tag exclusion on ZIP download:** Specify custom tags to filter out of the compiled ZIP's `.txt` tag list and markdown meta files.
- **Direct Hugging Face dataset upload:** Enter your Hugging Face write token and desired dataset repository name to instantly package and upload your compiled archives to a Hugging Face dataset. Creates the dataset automatically if it does not already exist.

## Run locally with Docker

```bash
docker build -t grabber .
docker run --rm -p 7860:7860 grabber
```

Then open http://localhost:7860.

## Deploy to Hugging Face Spaces

1. Push this repo to GitHub (Lovable → GitHub sync, or `git push`).
2. Create a new Space on Hugging Face → **SDK: Docker**.
3. Link the GitHub repo (or add the Space as a remote and push).

The frontmatter above tells HF Spaces to build the `Dockerfile` and serve on port `7860`.

## Adding a custom site

Click **+ Add site** and paste the site's API schema:

- **Base URL / Search Path** — e.g. `https://danbooru.donmai.us` + `/posts.json`
- **Param names** for tags / page / limit
- **JSON path** to the posts array (empty = root)
- **Field mappings** (dotted paths) for `id`, `previewUrl`, `fileUrl`, `ext`, `tags`, `source`, `rating`, `score`

Example (Danbooru):

```
baseUrl:    https://danbooru.donmai.us
searchPath: /posts.json
postsPath:  (empty)
fields.id:            id
fields.previewUrl:    preview_file_url
fields.fileUrl:       file_url
fields.ext:           file_ext
fields.tags:          tag_string_general
fields.source:        source
fields.rating:        rating
fields.score:         score
```

## Tech

- TanStack Start (React 19, Vite 7) + Tailwind v4 + shadcn/ui
- Server-side image fetching and streaming ZIP via `fflate`
- Node server build via nitro `node-server` preset