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.

How to use?

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.