subscription-template: a starting point for building your own GKD rule subscription

A template repository, so the starting point is one click

The repository is a GKD subscription template, and its purpose is stated in the first line: it exists so you can build your own subscription, with a Use this template button in the top right that opens the template creation flow on GitHub.

That is the whole design idea. Rather than asking you to clone and restructure a repository, the template gives you a new repository with the tooling, the directory layout and the build already wired, so the only thing left for you to write is the rules.

The runtime requirements are specific. You need the latest Node.js and pnpm, and you are expected to open the project in VS Code. The important note is an important one: the selectors need to be validated using the WasmGc implementation of Node 22, in order to check the Java and Kotlin regular expressions, so you must ensure nodejs is at version 22 or above. The stated requirements are nodejs 22 or newer, pnpm 9 or newer, and VS Code.

The reason for the WasmGc requirement is worth understanding, because it is not obvious. A GKD rule is a JavaScript object with a match rule, and for Android apps the match rule can use a Java or Kotlin regular expression, which is not the same regular expression dialect that JavaScript uses. Validating those expressions properly needs a JVM-like engine, and the template uses the Node build that ships with WebAssembly garbage collection support so it can run the check without a separate JVM.

The environment setup is three commands once you have created your repository from the template:

git clone https://github.com/username/subscription
cd subscription
pnpm install

And there is a mirror option for a slow network, using the Aliyun registry:

pnpm install --registry=https://registry.npmmirror.com

The README also points out that if you cannot initialise a Node environment at all, you can edit the files directly in the GitHub web editor and commit online, which is a genuinely useful fallback for a rule file that is mostly data.

Four directories, and one field you must change

The source is split into four places, and the split tells you how a subscription is organised.

The subscription details live in src/subscription.ts, and this is the file you have to edit first, because the id field has to be changed or your subscription may conflict with others. The guidance is to fill in a fairly large random number. There is a way to check for a collision, by searching GitHub code for the export default defineGkdSubscription block with an id.

The global rules are in src/globalGroups.ts, the rule categories in src/categories.ts, and the application rules in src/apps/.

The ergonomics are handled by the type system and the editor. Hovering over any field in VS Code shows a comment explaining it, and the same explanations can be searched in the GKD API documentation. That is a good pattern for a rules project, where the shape of a rule object is the thing you need to learn, and where the only documentation available is the comments in the type definitions.

The build output goes to the dist/ directory, and the built file is a single gkd.json5. The separate source files are merged into one file on the way out, which is what makes the result fetchable as a single URL.

The formatting and linting story is also handled for you. Prettier formats the code and eslint detects and fixes code errors, with simple-git-hooks running the formatting and fixing scripts when you commit. When your code has errors, the hook blocks the commit and prints the specific errors so you can fix them and commit again. The same job runs on the repository side through GitHub Actions, which means you have to grant the workflow write permission, and the README walks through setting Workflow permissions to Read and write permissions and saving.

That combination, a local pre-commit hook and a CI job doing the same thing, is a deliberate belt-and-braces approach to keeping a generated file in a consistent format.

The build runs in GitHub Actions, and the output is a URL

The build step is where the separate source files become the single file GKD actually downloads, and it happens in CI rather than on your machine.

The README recommends using GitHub Actions for the build, and there are three workflows under .github/workflows, with build_release.yml being the one used to build and publish. You open that workflow in the Actions tab of your repository and click Run workflow on the right, and the build runs and publishes.

After the build, the subscription is in the dist directory, and the file subscription address to copy into GKD is:

https://raw.githubusercontent.com/username/subscription/main/dist/gkd.json5

The address matters because it is what you paste into the app, and because it is a raw GitHub URL. The README then addresses a real practical problem: raw.githubusercontent.com is often inaccessible from mainland China, and you can swap it for the jsDelivr mirror at fastly.jsdelivr.net/gh/username/subscription@main/dist/gkd.json5.

And if neither is reachable, the README says to solve the network problem yourself, which is honest but not helpful. In practice that means the subscription needs a host you control, and that is a decision to make before you build the whole thing.

The package.json in the repository confirms the shape of the tooling. The package is @gkd-kit/subscription-template, it is an ES module, and the scripts are a postinstall that runs simple-git-hooks, a format script running prettier with the cache and ignore-unknown flags, a lint script running eslint with the cache and fix, a check script that runs tsc with noEmit and then a check script from the scripts directory, and a build script that does the same type check before running the build script. The check and build scripts are why a type error blocks the build rather than producing a broken subscription.

The dependencies are the GKD toolchain itself, @gkd-kit/api at 0.9.3, @gkd-kit/define at 0.0.1 and @gkd-kit/tools at 0.8.0, alongside the formatting stack of prettier, eslint, typescript-eslint and the prettier and unused-imports plugins, plus tsx for running the TypeScript scripts directly and json5 for the output format.

Build options you almost never need to touch

The configuration section is marked as one you do not need in the majority of cases, which is a good sign about the defaults, and it covers the build output.

You can add a gkd property to package.json to customise the build options:

{
  "gkd": {
    "outDir": "dist",
    "file": "gkd.json5",
    "versionFile": "gkd.version.json5",
    "changelog": "CHANGELOG.md",
    "README.md": "README.md"
  }
}

The type for that configuration is documented in full, with a default annotation on each field. outDir is the output directory, file is the name of the built subscription, versionFile is the separate file carrying the version, and changelog and readme are the files that get attached to the published version.

The version being a separate artefact from the subscription is the interesting one, since it is what lets a client check whether it has the latest rules without downloading them.

If you would rather not write the config file, the same parameters can be passed directly to the updateDist function of @gkd-kit/tools. The one constraint when passing them manually is that you must explicitly pass the path arguments, as distinct from the file name arguments, to the updatePkgVersion and stdoutGkdVersion functions under .github/workflows/build_release.yml.

The repository layout is small and matches the workflow. There is src/ for the rule sources, dist/ for the build output, scripts/ for the check and build scripts, .github/ for the workflows, pnpm-workspace.yaml and pnpm-lock.yaml for the workspace, and eslint.config.ts, prettier.config.ts, tsconfig.json and a .prettierignore at the root. The primary language is TypeScript, and the last push was on 2026-08-05.

Editorial conclusion

subscription-template suits someone who wants to publish their own ad-blocking and app-behaviour rules for GKD and wants the subscription in version control rather than in a text editor, because the source is split by concern and the build output is a single fetchable file. It does not suit you if you only need a couple of rules, since the toolchain of Node, pnpm, TypeScript and GitHub Actions is a lot for that. Before you publish, change the id field in the subscription details, because the default is likely to collide with other subscriptions, and note that Node 22 or newer is required because the selector validation uses its WasmGc implementation to check Java and Kotlin regular expressions.

Frequently asked questions

Official sources

1. gkd-kit/subscription-template on GitHub
2. Issues
3. README