Types for the sing-box config

This project provides TypeScript types for the entire sing-box config.

Why Use TypeBox?

• Type Safety: TypeBox provides a robust type system that ensures your configurations are type-safe, reducing errors.
• Auto-completion: With TypeBox, you get auto-completion features in your IDE, making it easier to write and maintain configurations.
• Modular Design: TypeBox allows you to create modular configurations, enabling better organization and reuse of configuration components.
• Tag Checking: TypeBox supports tag checking, ensuring that all required tags are present in your configurations.

Try TypeBox in browser

You can try TypeBox in browser: TypeBox Playground. It runs entirely in the browser, so it is almost identical to the local setup but doesn't require installing anything on your machine.

[!IMPORTANT] All data is stored in your browser's local storage, so it won't be sent to any server.

How to use?

| Feature Matrix | JSON Schema | TypeScript | | -------------- | ----------- | ---------- | | Auto complete | ✔️ | ✔️ | | Modular | ❌ | ✔️ | | Tag check | ❌ | ✔️ |

Use in JSON schema

{
    "$schema": "https://github.com/jiang-zhexin/typebox/releases/latest/download/schema.json",
    // other sing-box config
}

Use in TypeScript

# Node.js
npx jsr add @zhexin/typebox
yarn add jsr:@zhexin/typebox
pnpm add jsr:@zhexin/typebox
# Deno
deno add jsr:@zhexin/typebox
# Bun
bunx jsr add @zhexin/typebox

Coding

// main.ts
import { createTypebox } from "@zhexin/typebox"
import { createOutbound } from "@zhexin/typebox/outbound"

const ss_out = createOutbound({
    type: 'shadowsocks',
    tag: 'ss-out',
    method: '2022-blake3-aes-128-gcm',
    password: '',
    server: '',
    server_port: 0,
    multiplex: {
        enabled: true,
    },
})

const config = createTypebox({
    log: {},
    dns: {},
    endpoints: [],
    inbounds: [],
    outbounds: [ss_out],
    route: {},
    experimental: {},
})

// export to .json file
await Deno.writeTextFile("./path/to/config.json", JSON.stringify(config, null, 4))

Run it

deno run --allow-write ./main.ts

About version

This project does not follow semantic versioning in the traditional sense. Instead, it follows the versioning of sing-box.

For example, 1.10.x provides TypeScript types for sing-box 1.10.x.

However, the "x" is independent of the sing-box version and is used for revisions of this project itself.

Standard

Here are the differences from the sing-box acceptable configuration.

The differences are intentional.

Tag

The value of any tag field like dns.server.tag or outbound.tag is required, even though it's optional in sing-box.

Enabled

Any enabled field must be true.

if you are not enabling it, you should omit the entire field.