This guide have some instructions and tips on how to create a new Tachiyomi extension. Please **read
it carefully** if you're a new contributor or don't have any experience on the required languages
and knowledges.
This guide is not definitive and it's being updated over time. If you find any issue on it, feel
free to report it through a [Meta Issue](https://github.com/keiyoushi/extensions-source/issues/new?assignees=&labels=Meta+request&template=06_request_meta.yml)
or fixing it directly by submitting a Pull Request.
## Table of Contents
1. [Prerequisites](#prerequisites)
1. [Tools](#tools)
2. [Cloning the repository](#cloning-the-repository)
2. [Getting help](#getting-help)
3. [Writing an extension](#writing-an-extension)
1. [Setting up a new Gradle module](#setting-up-a-new-gradle-module)
| `extClass` | Points to the class that implements `Source`. You can use a relative path starting with a dot (the package name is the base path). This is used to find and instantiate the source(s). |
| `extVersionCode` | The extension version code. This must be a positive integer and incremented with any change to the code. |
| `isNsfw` | (Optional, defaults to `false`) Flag to indicate that a source contains NSFW content. |
purposes. The actual implementations can be found [here](https://github.com/tachiyomiorg/tachiyomi/tree/master/app/src/main/java/eu/kanade/tachiyomi/source).
| `name` | Name displayed in the "Sources" tab in Tachiyomi. |
| `baseUrl` | Base URL of the source without any trailing slashes. |
| `lang` | An ISO 639-1 compliant language code (two letters in lower case in most cases, but can also include the country/dialect part by using a simple dash character). |
| `id` | Identifier of your source, automatically set in `HttpSource`. It should only be manually overriden if you need to copy an existing autogenerated ID. |
### Extension call flow
#### Popular Manga
a.k.a. the Browse source entry point in the app (invoked by tapping on the source name).
- The app calls `fetchPopularManga` which should return a `MangasPage` containing the first batch of
found `SManga` entries.
- This method supports pagination. When user scrolls the manga list and more results must be fetched,
the app calls it again with increasing `page` values (starting with `page=1`). This continues while
`MangasPage.hasNextPage` is passed as `true` and `MangasPage.mangas` is not empty.
- To show the list properly, the app needs `url`, `title` and `thumbnail_url`. You **must** set them
here. The rest of the fields could be filled later (refer to Manga Details below).
- You should set `thumbnail_url` if is available, if not, `getMangaDetails` will be **immediately**
called (this will increase network calls heavily and should be avoided).
#### Latest Manga
a.k.a. the Latest source entry point in the app (invoked by tapping on the "Latest" button beside
the source name).
- Enabled if `supportsLatest` is `true` for a source
- Similar to popular manga, but should be fetching the latest entries from a source.
#### Manga Search
- When the user searches inside the app, `fetchSearchManga` will be called and the rest of the flow
is similar to what happens with `fetchPopularManga`.
- If search functionality is not available, return `Observable.just(MangasPage(emptyList(), false))`
-`getFilterList` will be called to get all filters and filter types.
##### Filters
The search flow have support to filters that can be added to a `FilterList` inside the `getFilterList`
method. When the user changes the filters' state, they will be passed to the `searchRequest`, and they
can be iterated to create the request (by getting the `filter.state` value, where the type varies
depending on the `Filter` used). You can check the filter types available [here](https://github.com/tachiyomiorg/tachiyomi/blob/master/source-api/src/commonMain/kotlin/eu/kanade/tachiyomi/source/model/Filter.kt)
| `Filter.Header` | None | A simple header. Useful for separating sections in the list or showing any note or warning to the user. |
| `Filter.Separator` | None | A line separator. Useful for visual distinction between sections. |
| `Filter.Select<V>` | `Int` | A select control, similar to HTML's `<select>`. Only one item can be selected, and the state is the index of the selected one. |
| `Filter.Text` | `String` | A text control, similar to HTML's `<input type="text">`. |
| `Filter.CheckBox` | `Boolean` | A checkbox control, similar to HTML's `<input type="checkbox">`. The state is `true` if it's checked. |
| `Filter.TriState` | `Int` | A enhanced checkbox control that supports an excluding state. The state can be compared with `STATE_IGNORE`, `STATE_INCLUDE` and `STATE_EXCLUDE` constants of the class. |
| `Filter.Group<V>` | `List<V>` | A group of filters (preferentially of the same type). The state will be a `List` with all the states. |
| `Filter.Sort` | `Selection` | A control for sorting, with support for the ordering. The state indicates which item index is selected and if the sorting is `ascending`. |
All control filters can have a default state set. It's usually recommended if the source have filters
to make the initial state match the popular manga list, so when the user open the filter sheet, the
state is equal and represents the current manga showing.
The `Filter` classes can also be extended, so you can create new custom filters like the `UriPartFilter`:
```kotlin
open class UriPartFilter(displayName: String, private val vals: Array<Pair<String,String>>) :
-`SManga.status` is an "enum" value. Refer to [the values in the `SManga` companion object](https://github.com/tachiyomiorg/extensions-lib/blob/master/library/src/main/java/eu/kanade/tachiyomi/source/model/SManga.kt#L26).
Make sure you make the `SimpleDateFormat` a class constant or variable so it doesn't get
recreated for every chapter. If you need to parse or format dates in manga description, create
another instance since `SimpleDateFormat` is not thread-safe.
- If the parsing have any problem, make sure to return `0L` so the app will use the default date
instead.
- The app will overwrite dates of existing old chapters **UNLESS**`0L` is returned.
- The default date has [changed](https://github.com/tachiyomiorg/tachiyomi/pull/7197) in
preview ≥ r4442 or stable > 0.13.4.
- In older versions, the default date is always the fetch date.
- In newer versions, this is the same if every (new) chapter has `0L` returned.
- However, if the source only provides the upload date of the latest chapter, you can now set
it to the latest chapter and leave other chapters default. The app will automatically set it (instead of fetch date) to every new chapter and leave old chapters' dates untouched.
-`getChapterUrl` is called when the user taps "Open in WebView" in the reader.
- If the source uses an API to fetch the data, consider overriding this method to return the
chapter absolute URL in the website instead.
- It defaults to the URL provided to the request in `pageListRequest`.
#### Chapter Pages
- When user opens a chapter, `getPageList` will be called and it will return a list of `Page`s.
- While a chapter is open in the reader or is being downloaded, `fetchImageUrl` will be called to get
URLs for each page of the manga if the `Page.imageUrl` is empty.
- If the source provides all the `Page.imageUrl`'s directly, you can fill them and let the `Page.url`
empty, so the app will skip the `fetchImageUrl` source and call directly `fetchImage`.
- The `Page.url` and `Page.imageUrl` attributes **should be set as an absolute URL**.
- Chapter pages numbers start from `0`.
- The list of `Page`s should be returned already sorted, the `index` field is ignored.
### Misc notes
- Sometimes you may find no use for some inherited methods. If so just override them and throw
To get the current `id` value before the name change, you can search the source name in the [repository JSON file](https://github.com/keiyoushi/extensions/blob/repo/index.json)
To make local development more convenient, you can use the following run configuration to launch
Tachiyomi directly at the Browse panel:
![](https://i.imgur.com/STy0UFY.png)
If you're running a Preview or debug build of Tachiyomi:
```
-W -S -n eu.kanade.tachiyomi.debug/eu.kanade.tachiyomi.ui.main.MainActivity -a eu.kanade.tachiyomi.SHOW_CATALOGUES
```
And for a release build of Tachiyomi:
```
-W -S -n eu.kanade.tachiyomi/eu.kanade.tachiyomi.ui.main.MainActivity -a eu.kanade.tachiyomi.SHOW_CATALOGUES
```
> [!IMPORTANT]
> If you're deploying to Android 11 or higher, enable the "Always install with package manager" option in the run configurations. Without this option enabled, you might face issues such as Android Studio running an older version of the extension without the modifications you might have done.
## Debugging
### Android Debugger
You can leverage the Android Debugger to step through your extension while debugging.
You *cannot* simply use Android Studio's `Debug 'module.name'` -> this will most likely result in an
error while launching.
Instead, once you've built and installed your extension on the target device, use
`Attach Debugger to Android Process` to start debugging Tachiyomi.
![](https://i.imgur.com/muhXyfu.png)
### Logs
You can also elect to simply rely on logs printed from your extension, which
show up in the [`Logcat`](https://developer.android.com/studio/debug/am-logcat) panel of Android Studio.
### Inspecting network calls
One of the easiest way to inspect network issues (such as HTTP errors 404, 429, no chapter found etc.)
is to use the [`Logcat`](https://developer.android.com/studio/debug/am-logcat) panel of Android Studio
and filtering by the `OkHttpClient` tag.
To be able to check the calls done by OkHttp, you need to enable verbose logging in the app, that is
not enabled by default and is only included in the Preview versions of Tachiyomi. To enable it, go to
More -> Settings -> Advanced -> Verbose logging. After enabling it, don't forget to restart the app.
Inspecting the Logcat allows you to get a good look at the call flow and it's more than enough in most
cases where issues occurs. However, alternatively, you can also use an external tool like `mitm-proxy`.
For that, refer to the subsequent sections.
On newer Android Studio versions, you can use its built-in Network Inspector inside the
App Inspection tool window. This feature provides a nice GUI to inspect the requests made in the app.
To use it, follow the [official documentation](https://developer.android.com/studio/debug/network-profiler)
and select Tachiyomi package name in the process list.
### Using external network inspecting tools
If you want to take a deeper look into the network flow, such as taking a look into the request and
response bodies, you can use an external tool like `mitm-proxy`.
#### Setup your proxy server
We are going to use [mitm-proxy](https://mitmproxy.org/) but you can replace it with any other Web
Debugger (i.e. Charles, Burp Suite, Fiddler etc). To install and execute, follow the commands below.
```console
Install the tool.
$ sudo pip3 install mitmproxy
Execute the web interface and the proxy.
$ mitmweb
```
Alternatively, you can also use the Docker image:
```
$ docker run --rm -it -p 8080:8080 \
-p 127.0.0.1:8081:8081 \
--web-host 0.0.0.0 \
mitmproxy/mitmproxy mitmweb
```
After installing and running, open your browser and navigate to http://127.0.0.1:8081.
#### OkHttp proxy setup
Since most of the manga sources are going to use HTTPS, we need to disable SSL verification in order
to use the web debugger. For that, add this code to inside your source class:
Note: `10.0.2.2` is usually the address of your loopback interface in the android emulator. If
Tachiyomi tells you that it's unable to connect to 10.0.2.2:8080 you will likely need to change it
(the same if you are using hardware device).
If all went well, you should see all requests and responses made by the source in the web interface
of `mitmweb`.
## Building
APKs can be created in Android Studio via `Build > Build Bundle(s) / APK(s) > Build APK(s)` or
`Build > Generate Signed Bundle / APK`.
## Submitting the changes
When you feel confident about your changes, submit a new Pull Request so your code can be reviewed
and merged if it's approved. We encourage following a [GitHub Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962)
and following the good practices of the workflow, such as not commiting directly to `main`: always
create a new branch for your changes.
If you are more comfortable about using Git GUI-based tools, you can refer to [this guide](https://learntodroid.com/how-to-use-git-and-github-in-android-studio/)
about the Git integration inside Android Studio, specifically the "How to Contribute to an to Existing
Git Repository in Android Studio" section of the guide.
> [!IMPORTANT]
> Make sure you have generated the extension icon using the linked Icon Generator tool in the [Tools](#tools)
> section. The icon **must follow the pattern** adopted by all other extensions: a square with rounded