# Surgio rule generation for Surge, Clash, and Quantumult > Surgio is a TypeScript package for generating proxy-client rules through modular provider, generator, project, cache, and runtime APIs. Its v4 line is still described as beta, so compatibility needs verification before adoption. **surgioproject/surgio** — Generating rules for Surge, Clash, Quantumult like a PRO - Repository: https://github.com/surgioproject/surgio - Website: https://surgio.js.org - Stars: 1,822 · Forks: 161 - Language: TypeScript - License: MIT - Published: 2026-10-16 · Updated: 2026-10-16 · Language: en - Canonical page: https://hysenlabs.com/projects/surgioproject-surgio ## Surgio's target clients and intended developers Surgio addresses the repeated work of maintaining proxy-client rules across tools with different configuration formats. Its package description explicitly names Surge, Clash, and Quantumult. The repository topics also cover Loon, Stash, sing-box, Hysteria, Shadowsocks, Snell, Trojan, V2Ray, and VLESS. Topic labels do not establish that every listed client or protocol has identical support, but they place Surgio clearly in the network proxy configuration field rather than general-purpose proxy server software. The project is aimed at developers who can work with TypeScript and the npm ecosystem. Its repository contains TypeScript source, type definitions, tests, documentation, examples, and multiple workspace packages. This structure suits someone who wants configuration represented as code and wants to generate client-specific artifacts from reusable inputs. It is less suitable for someone who only wants to paste a finished rule into a client and has no interest in provider logic, project files, or generated output. Surgio should also be understood as a configuration generator, not a complete traffic service. The README does not describe packet routing, local proxy behavior, protocol implementation, or account management. Its responsibility is narrower: transform higher-level definitions into rules for existing clients. Users still need a client that can interpret the generated rules and the network services referenced by their configuration. ## Surgio's modular TypeScript package structure The `package.json` exposes the main package plus focused entry points. The default export points to `build/index.js`, with TypeScript declarations at `build/index.d.ts`. Separate exports exist for `./generator`, `./provider`, `./project`, `./runtime`, `./runtime/node`, `./cache`, `./config`, `./constant`, `./utils`, and `./internal`. Consumers can therefore depend on a narrower API surface instead of importing every internal module through the package root. The package declares `"type": "module"`, so its published JavaScript is configured as ES modules. Its export map uses the `module-sync` and `default` conditions and provides explicit type entry points. Package exports and module conditions matter for TypeScript users because they form part of the compatibility boundary. The repository includes a `.node-version` file and a Node.js version badge, but the README does not state the supported major Node.js version in prose. The repository layout separates source code in `src/`, tests in `test/`, documentation in `docs/`, and sample projects in `examples/`. Example directories include Clash remote snippets, hooks, Quantumult X, and TypeScript configuration. This indicates that configuration authoring, extension examples, and generated output are separate concerns. The available repository description does not expose the complete schemas or command implementation, so the exact runtime sequence should be checked in the versioned documentation and source files rather than inferred from package names alone. ## Providers, generators, and Surgio's configuration flow The named entry points indicate a flow built around reusable providers and output generators. A provider module can represent an input definition, while a generator module can handle client-specific rendering. The `./project` entry point suggests that file discovery and project-level configuration have their own public boundary. `./config` exposes configuration handling, and `./runtime` plus `./runtime/node` separates the general runtime API from its Node.js implementation. The README does not include a complete input schema or a sample generation command, so exact internal calls cannot be quoted. The repository examples provide the clearest starting point for tracing the flow. `examples/clash-remote-snippet/` is relevant to Clash output, while `examples/quantumultx/` shows that Quantumult X is represented in the example set. The `examples/hooks/` directory also indicates a hook mechanism, although the README does not state when hooks run or what interfaces they receive. For an engineer, Surgio should be evaluated as a build pipeline rather than a single formatter function. The provider, generator, project, runtime, and cache modules suggest that reusable source definitions, rendering, execution context, and temporary data have separate homes. That separation can isolate client-specific logic, but it also creates more configuration concepts than a one-file converter requires. ## Installing Surgio and starting from its examples The README identifies the npm package as `surgio` and directs users to `https://surgio.js.org` for complete documentation. It does not provide an installation command, a CLI invocation, or a complete first-use example. For that reason, no installation flag or command should be invented. The linked documentation is the appropriate place to choose a supported Node.js version and install procedure. The repository offers concrete reading material under `examples/`. Begin with `examples/README.md`, then inspect the directory closest to the intended client, such as `examples/quantumultx/` or `examples/clash-remote-snippet/`. The root `examples/tsconfig.json` shows that the examples account for TypeScript configuration. Because `package.json` declares the package as an ES module and publishes declaration files, module resolution and TypeScript settings are part of the first-use path. There is an explicit version split to resolve before copying an example. The README warns that Surgio v4 is in beta and points v3 users to `https://v3.surgio.royli.dev/`. The repository's `package.json` identifies version `4.0.0-beta.7`, while the listed release history includes `v4.0.0-beta.5` and `v3.19.0`. The README does not explain the distinction between the package version and the listed release entry. Verify that the documentation, installed package version, and example files belong to the same major line before building. ## Surgio's v4 beta and compatibility costs The clearest adoption risk is version maturity. The README does not call v4 stable; it says that v4 is undergoing beta testing. The repository has recent release activity, with the last push recorded on 2026-09-30 and releases listed for v3.19.0 and v4.0.0-beta.5. Recent activity confirms that work is occurring, but it does not remove the migration risk created by a beta major version. The public export map increases the cost of that risk. Consumers can import specialized entry points such as `./generator`, `./provider`, and `./runtime/node`. If an application imports those paths, a v4 change may require code changes rather than only a package replacement. The repository includes `CHANGELOG.md`, but its contents are not reproduced in the README, so the scope of upgrade work cannot be quantified from the project summary alone. Surgio uses the MIT license. That license permits reuse and modification under its terms and includes its copyright and permission notice, but this review does not provide legal advice. Operationally, maintenance cost includes checking generated rules after client or protocol changes. Surgio supports several proxy ecosystems, while each client can have its own syntax and feature set. Successful package installation does not prove that every target client receives a valid configuration. ## Surgio versus direct client configuration The practical alternative is maintaining each client's configuration directly. Surge users can edit the format expected by Surge, Clash users can maintain Clash configuration, and Quantumult users can maintain Quantumult configuration without adding a TypeScript generation layer. This approach has fewer moving parts when there is one client and a small rule set. It also removes questions about compatibility with a beta generator. Surgio takes a different approach by representing reusable configuration as project data and rendering it for multiple targets. That can be preferable when policy groups, proxy sources, or transformations need to feed several client formats. The provider, generator, and hooks structure is intended for repeatable generation rather than isolated manual edits. The trade-off is that users must learn Surgio's configuration model and debug both their source definitions and the generated client syntax. Neither approach is automatically superior. Direct configuration offers fewer abstractions and may be the right choice for a one-off personal setup. Surgio is more relevant when configuration reuse, TypeScript authoring, and multi-client generation are explicit requirements. The README does not document rollback, validation commands, or a complete matrix mapping every client to every protocol. Those details should be confirmed in the documentation for the selected major version before selecting the tool. ## Conclusion Surgio fits developers who want a TypeScript-based rule generation layer across Surge, Clash, and Quantumult rather than hand-maintaining separate client files. It is a poor fit for teams needing a documented, stable v4 setup or expecting the README to cover installation and migration. Before adoption, compare generated output for each required client, check examples against the current documentation, and decide whether beta-specific API changes are acceptable. The last push was on 2026-09-30, but the explicit v4 beta warning makes API stability the first project-specific concern. ## FAQ ### Which proxy clients does Surgio generate rules for? The package description explicitly names Surge, Clash, and Quantumult. Repository topics also include Loon, Stash, sing-box, and several proxy protocols, but the README does not provide a complete support matrix. ### Is Surgio v4 stable? The README does not call v4 stable. It explicitly says that Surgio v4 is undergoing beta testing, and `package.json` identifies the repository version as `4.0.0-beta.7`. ### How do I start using Surgio after installation? The README sends users to `https://surgio.js.org` for complete documentation. The repository also provides `examples/README.md`, `examples/quantumultx/`, `examples/clash-remote-snippet/`, and `examples/hooks/` as starting points, but the README does not give a complete first-use command. ## Sources - [License: MIT](https://github.com/surgioproject/surgio/blob/master/LICENSE) - [Project website](https://surgio.js.org) - [README](https://github.com/surgioproject/surgio/blob/master/README.md) - [Releases](https://github.com/surgioproject/surgio/releases) - [surgioproject/surgio on GitHub](https://github.com/surgioproject/surgio) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/surgioproject-surgio