# shadowrocket-rules: a module collection for Shadowrocket, and the one rule that breaks them all

> A large personal collection of Shadowrocket modules, base configurations and routing rules, where the README spends more space on a hostname directive called %APPEND% than on anything else.

**deezertidal/shadowrocket-rules** — Config files, modules and scripts for Shadowrocket, with illustrated tutorials, rules, traffic routing and unlocking tips.

- Repository: https://github.com/deezertidal/shadowrocket-rules
- Website: https://yfamilys.com/shadowrocket
- Stars: 6,765 · Forks: 344
- Language: JavaScript
- License: not declared
- Published: 2026-10-06 · Updated: 2026-10-06 · Language: en
- Canonical page: https://hysenlabs.com/projects/deezertidal-shadowrocket-rules

## What is actually in the repository

The tree is short, and it is not a codebase. There is no source to build, no test suite and no package manifest. What you have is a documentation page and a set of served files:

```text
IMG/
README.md
TrollStore.MD
js/
modules/
rule/
shadowrocket_basic.conf
```

`shadowrocket_basic.conf` is the important one. It is the base configuration the README tells you to pair with any module you install, and the pairing is not optional in practice. `modules/` holds the module files themselves, `rule/` holds routing rules for traffic splitting, `js/` holds the scripts that power features such as check-in automation, and `TrollStore.MD` covers installation on devices where the module host list is the awkward part.

GitHub labels the repository JavaScript, which comes from `js/` and not from anything in the configuration format. There are no releases and no tags in the project at all. Updates arrive as commits to `main`, which is why the last push date is the only version information that exists for this project.

## The %APPEND% warning is the whole manual

Buried in a short list of notes near the top of the README is the single most important piece of documentation in the repository. If a module sometimes works and sometimes does not, the README says to check whether other modules have added `%APPEND%` to their hostname entries, and that leaving it out will cause other modules to fail. It then states that every module in this repository has `%APPEND%` added.

That is not a style preference, it is how Shadowrocket merges module hostnames. A module that writes a bare hostname line replaces the accumulated list rather than extending it, so one module without the directive quietly undoes every rule that came before it. The symptom the README describes, a module that appears to work alone and fails in combination, is exactly what that causes. Anyone adding a third-party module to a configuration built from this repository needs to check this line first, because the third-party module can break the collection just as easily.

The same note block also says modules are meant to be combined with the basic configuration to avoid redundancy. Without that base file you end up hand-merging rules that the author already merged once.

## Several hundred modules, sorted by the app they touch

The module table is the bulk of the README, and its structure is a category column in disguise. Each row pairs a module name with a direct URL and a one-line description naming the app it modifies. Reading across the categories tells you what the collection is actually for.

```
|:white_check_mark:bilibili NoAD|[:link:链接地址](https://yfamilys.com/module/biliad.module)|bilibili去广告
|:white_check_mark:grammarly|[:link:链接地址](https://yfamilys.com/module/grammarly.module)|外语类
|:white_check_mark:lightroom|[:link:链接地址](https://yfamilys.com/module/lightroom.module)|照片编辑
```

Three job types repeat across the table. Ad blocking covers the largest group, with separate entries for Bilibili, music apps, comic readers and photography tools. Member and subscription unlocking covers services such as Grammarly, Lightroom, Nicegram and several Chinese apps. App-specific tweaks cover the long tail: a video editor, a calculator, a PDF tool, a language-learning reader, a wallpaper app.

Two details are worth reading off the URLs rather than the descriptions. Some modules end in `.module` and others in `.sgmodule`, which is the naming used by the module format that originated outside Shadowrocket. And the files are served from `yfamilys.com/module/` rather than from raw GitHub, so the modules are fetched from the author's web host. That is what makes the direct install addresses work as a subscription-style update source, and it also means the modules are not versioned artifacts you can pin.

## Rules, scripts and the difference between blocking ads and routing traffic

Two directories do different jobs, and conflating them is the most common misunderstanding with Shadowrocket. A module rewrites requests for specific hostnames: it redirects an ad domain to nothing, or rewrites a video manifest URL so the higher quality variant loads. A routing rule decides which connection path a domain takes. The `rule/` directory is the second kind, and the `shadowrocket_basic.conf` file is where the general routing structure lives.

If your problem is that an app shows adverts, a module is the answer. If your problem is that a domain resolves slowly or takes the wrong exit, a routing rule is the answer. Installing ten modules will not fix a routing problem, which is worth knowing before spending an afternoon on it.

The `js/` directory covers a third category: local scripts that run inside the client. The `boxjs` entry in the module table is described as containing a check-in script, which is the pattern for apps where daily sign-in rewards are worth automating. The README also links a separate rule page on the author's site, so the routing rules published online are broader than what is committed under `rule/`.

One design consequence of the whole approach: every module assumes it is loaded alongside others. That is why `%APPEND%` matters, and why the base configuration exists.

## Where the files come from, and what you cannot check

The distribution story is unusual enough to be worth stating plainly. The README links a direct module install address, a configuration tutorial, a rules page and a basic configuration file, all under the author's personal site. The GitHub repository holds the README and the directories, but the modules themselves are fetched from that site when you install them.

There is no license file in the tree, so the terms for reusing or redistributing these modules are not stated. There is also no changelog, so when a module changes behaviour there is no record of which version you had. The open issue tracker has three entries, which suggests it is not where support happens.

The project is current rather than abandoned: the last push was on 2026-09-21. For a collection maintained this way, freshness is the practical substitute for versioning, and the trade is that you cannot pin or roll back a module. If you need reproducibility, copy the modules you depend on into your own configuration once you have chosen them, rather than subscribing to the live URL.

The `TrollStore.MD` file is the piece that solves the iOS installation problem. Shadowrocket configuration and module management is fiddly on a jailbroken or sideloaded device, and sideloading through TrollStore is one of the documented routes in.

## How to use this collection without fighting it

The order of operations matters more than any individual module. Start with `shadowrocket_basic.conf` as the configuration, because the modules assume a base that already handles general routing. Then add the modules for the apps you actually use, through the direct install address rather than by opening each URL and pasting it, so that updates arrive without you editing files.

After that, verify rather than assume. The failure mode the README warns about is silent: a module without `%APPEND%` does not error, it just stops other modules from taking effect. If a rule that used to work stops working after adding an unrelated module, check the hostname lines of what you just added before you suspect the app.

Keep ad blocking and routing decisions in separate files if you can, so that you know which one to open when something misbehaves. And check the `rule/` directory and the author's rules page when the problem is connection path rather than an advert appearing.

What the repository does not offer is any explanation of how a given module rewrites a specific service, so debugging a module that stops working usually means reading the module file itself. That is normal for a collection of this kind, and it is the main cost of using one.

## Conclusion

This repository is a working collection rather than a documented project, and reading it that way is the only sensible approach. It has no releases, no changelog and no stated license; what it has is several hundred modules, a base configuration, a rule directory and a scripts folder, all kept current, with the last push on 2026-09-21. The single most useful line in the README is the warning about `%APPEND%`, because a module without it silently disables the hostnames of every module loaded before it. Copy `shadowrocket_basic.conf` first, add modules through the direct install page rather than one at a time by hand, and check the `rule/` directory only when you want to change how traffic is split rather than which hosts are rewritten.

## FAQ

### How do I use Shadowrocket?

For this collection, the sequence the README implies is: import shadowrocket_basic.conf as your base configuration, then install modules from the direct install address on the author's site. Add modules one at a time at first so you can tell which one changes a given app's behaviour, and keep an eye on the %APPEND% hostname directive.

### What does %APPEND% do in a Shadowrocket module?

It makes the module append its hostnames to the list already accumulated by other modules instead of replacing that list. Because Shadowrocket merges modules in load order, a module that writes bare hostname lines will undo every rule loaded before it, which is the intermittent failure the README warns about. Every module in this repository already includes the directive.

### What is the difference between a Shadowrocket module and a rule in this repository?

A module rewrites requests for named hostnames, which is how ad blocking and video variant rewriting work. A routing rule decides which path a connection takes, and those live in the rule/ directory and in shadowrocket_basic.conf. Ad blocking problems need a module; wrong exit or slow resolution needs a rule.

## Sources

- [deezertidal/shadowrocket-rules on GitHub](https://github.com/deezertidal/shadowrocket-rules)
- [Issues](https://github.com/deezertidal/shadowrocket-rules/issues)
- [Project website](https://yfamilys.com/shadowrocket)
- [README](https://github.com/deezertidal/shadowrocket-rules/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/deezertidal-shadowrocket-rules