Skip to content

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.

  • 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
  1. Get the SDK and install its dependencies:

    Terminal window
    git clone https://github.com/HonyaApp/Extensions my-sources
    cd my-sources
    npm install
  2. Type-check, build and serve the repository:

    Terminal window
    npm run dev

    This builds every source into dist/ and serves it on port 8642, printing the addresses it can be reached at.

  3. In Honya, go to Settings → Sources → Add Repository and enter http://localhost:8642 in the Simulator, or the network address npm run dev printed on a device on the same Wi-Fi.

  4. Tap Get next to a source to install it, then browse it from Discover.

  • 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
  • Directorysrc/
    • Directoryen/
      • Directorypublicdomaincomics/
        • index.ts the example source
  • Directoryscripts/ build and serve
    • …
  • .github/workflows/publish.yml publishes dist/ to the repo branch
  • Directorydist/ what npm run build writes, ready to publish
    • …
  • package.json honya.repoName names 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.

Create src/en/examplemanga/index.ts. Here’s a complete source for an imaginary site:

src/en/examplemanga/index.ts
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 source
  1. Edit the source and run npm run build (or npm run dev again).
  2. Raise version in its info. Honya only offers an update when the version is newer.
  3. 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>.