Quick start
A source is a TypeScript module that default-exports an object with a few async functions: popular titles, search, a title’s details, its chapters, and a chapter’s pages. The build bundles each source into one JavaScript file and writes a repository’s index.json listing them. Honya runs those files in JavaScriptCore.
If you’ve written or read a Mihon extension, the functions will look familiar: they mirror Mihon’s HttpSource, and the HTML parser speaks Jsoup’s API, so selectors carry over unchanged.
What you need
Section titled “What you need”- Node.js 22 or later
- The SDK repository, which has the SDK, the build and serve scripts, and Public Domain Comics, a complete example source
- Honya on an iPhone, iPad, or the iOS Simulator
Set up
Section titled “Set up”-
Get the SDK and install its dependencies:
Terminal window git clone https://github.com/HonyaApp/Extensions my-sourcescd my-sourcesnpm install -
Type-check, build and serve the repository:
Terminal window npm run devThis builds every source into
dist/and serves it on port 8642, printing the addresses it can be reached at. -
In Honya, go to Settings → Sources → Add Repository and enter
http://localhost:8642in the Simulator, or the network addressnpm run devprinted on a device on the same Wi-Fi. -
Tap Get next to a source to install it, then browse it from Discover.
The repository’s layout
Section titled “The repository’s layout”Directorysdk/ the types, the host API’s declarations, and helpers
- index.ts what
"../../../sdk"imports - types.ts
- host.d.ts
- helpers.ts requests, URLs, encoding, concurrency, images
- dates.ts
- crypto.ts
- nextjs.ts
- index.ts what
Directorysrc/
Directoryen/
Directorypublicdomaincomics/
- index.ts the example source
Directoryscripts/ build and serve
- …
- .github/workflows/publish.yml publishes
dist/to therepobranch Directorydist/ what
npm run buildwrites, ready to publish- …
- package.json
honya.repoNamenames the repository - AGENTS.md instructions for AI agents, including porting from Keiyoushi
Each source lives in src/<lang>/<name>/index.ts, where <lang> is an ISO 639-1 code like en, or all for a source with several languages. An icon.png beside it is used when info.icon isn’t set. Public Domain Comics reads the Internet Archive’s JSON APIs. For a site you read as HTML, start from the source below.
Your first source
Section titled “Your first source”Create src/en/examplemanga/index.ts. Here’s a complete source for an imaginary site:
import { fetchHTML, imgAttr, parseDate, queryString, relativeUrl, type HTMLNode, type Manga, type MangasPage, type Source } from "../../../sdk"
const baseUrl = "https://manga.example"
const source: Source = { info: { id: "712815673375441830", // md5("example manga/en/1"), as Mihon computes it name: "Example Manga", lang: "en", version: "1.0.0", baseUrl, supportsLatest: true, rateLimits: [{ host: "manga.example", permits: 2, periodMs: 1000 }], },
getPopularManga(page) { return mangaList(`${baseUrl}/popular?page=${page}`) },
getLatestUpdates(page) { return mangaList(`${baseUrl}/latest?page=${page}`) },
searchManga(page, query) { return mangaList(`${baseUrl}/search?${queryString([["q", query], ["page", page]])}`) },
async getMangaDetails(manga) { const document = await fetchHTML(baseUrl + manga.url) return { title: document.selectFirst("h1")?.text(), author: document.selectFirst(".author")?.text(), description: document.selectFirst(".synopsis")?.text(), genres: document.select(".genres a").map((a) => a.text()), status: document.selectFirst(".status")?.text() === "Completed" ? "completed" : "ongoing", } },
// Newest first. async getChapterList(manga) { const document = await fetchHTML(baseUrl + manga.url) return document.select(".chapters li a").map((a) => ({ url: relativeUrl(a.attr("abs:href")), name: a.selectFirst(".name")?.text() ?? a.text(), dateUpload: parseDate(a.selectFirst("time")?.attr("datetime")), })) },
async getPageList(chapter) { const document = await fetchHTML(baseUrl + chapter.url) return document.select(".reader img").map((img) => ({ url: imgAttr(img) })) },}
async function mangaList(url: string): Promise<MangasPage> { const document = await fetchHTML(url) return { mangas: document.select(".manga-card").map(mangaFromCard), hasNextPage: document.selectFirst("a.next") != null, }}
function mangaFromCard(card: HTMLNode): Manga { const link = card.selectFirst("a.title") if (!link) throw new Error("card without a title link") return { url: relativeUrl(link.attr("abs:href")), title: link.text(), thumbnailUrl: card.selectFirst("img")?.attr("abs:src"), }}
export default sourceTry a change
Section titled “Try a change”- Edit the source and run
npm run build(ornpm run devagain). - Raise
versionin itsinfo. Honya only offers an update when the version is newer. - Pull down in Settings → Sources and tap Update.
Logs from console.log go to the app’s log. On a Mac, open Console.app, choose the device or Simulator, and filter by the category Extension <source name>.
- Anatomy of a source covers every field and function.
- The host API is what a source can call.
- Publishing puts your repository online for others to add.
- Making a repository with AI has an AI agent port Keiyoushi’s Mihon extensions, following
AGENTS.md.