📦 json-to-interface

@darth_sith_99/json-to-interface is a simple CLI tool that lets you generate TypeScript interfaces directly from a JSON payload. It’s perfect for quickly scaffolding data contracts for your frontend or backend project.

✨ Features

• 🧠 Infers types from JSON structure
• 📁 Outputs .ts files with clean, readable interfaces
• 🏃‍♂️ No install required — run instantly with npx
• 🤖 Interactive prompts, or non-interactive arguments for scripts and coding agents

🚀 Getting Started

✅ Requirements

• Node.js v18.13 or higher
• Internet access (for npx to fetch the package)

🛠️ Usage

Prepare two JSON mock files in the same folder: one for the success response and one for the error response.

sample/
├── success.json
└── error.json

Interactive mode

Run the CLI with no arguments and answer the prompts:

npx @darth_sith_99/json-to-interface

1. Select the API method.
2. Enter the API name, for example currentFlight.
3. Enter the folder containing the mocks, for example ./sample/.
4. Confirm the success and error mock filenames.

The generated file is saved in the same folder, for example sample/GetCurrentFlight.contract.ts.

Argument mode

Pass arguments to skip the prompts. Use this from scripts, CI, or coding agents that cannot answer interactive questions.

npx @darth_sith_99/json-to-interface \
  --method GET \
  --name currentFlight \
  --directory ./sample/ \
  --success success.json \
  --error error.json \
  --suffix-interface Response \
  --suffix-file types

This writes sample/GetCurrentFlight.types.ts with names such as GetCurrentFlightSuccessDataResponse.

| Option | Short | Required | Description | Default | | --- | --- | --- | --- | --- | | --method | -m | Yes | API method: GET, POST, PUT, PATCH, or DELETE | | | --name | -n | Yes | API name used in type names and the filename | | | --directory | -d | Yes | Folder with the mocks, also used for output. Must look like ./sample/ | | | --success | -s | No | Success mock filename | success.json | | --error | -e | No | Error mock filename | error.json | | --suffix-interface | -i | No | Suffix added to every generated type name | APIResponseType | | --suffix-file | -f | No | Suffix in the output filename | contract | | --help | -h | No | Show usage | |

--suffix-interface and --suffix-file only exist in argument mode. Interactive mode always uses the values from .jsonrc or the defaults.

⚙️ Configuration

Defaults can be changed with a .jsonrc file in the directory where you run the CLI:

SUCCESS_MOCK_FILE=success.json
ERROR_MOCK_FILE=error.json
SUFFIX_INTERFACE=APIResponseType
SUFFIX_FILE=contract

| Key | Controls | Default | | --- | --- | --- | | SUCCESS_MOCK_FILE | Default success mock filename | success.json | | ERROR_MOCK_FILE | Default error mock filename | error.json | | SUFFIX_INTERFACE | Suffix added to every generated type name | APIResponseType | | SUFFIX_FILE | Suffix in the output filename | contract |

Values are resolved in this order: CLI argument, then .jsonrc, then the built-in default.

📄 Output

For --method GET --name currentFlight with the default suffixes, the CLI generates GetCurrentFlight.contract.ts:

export interface GetCurrentFlightSuccessRootAPIResponseType {
  meta?: GetCurrentFlightSuccessMetaAPIResponseType;
  data?: GetCurrentFlightSuccessDataAPIResponseType;
}

export interface GetCurrentFlightErrorRootAPIResponseType {
  meta?: GetCurrentFlightErrorMetaAPIResponseType;
  error?: GetCurrentFlightErrorErrorAPIResponseType;
}

export type GetCurrentFlightRootAPIResponseType =
  | GetCurrentFlightSuccessRootAPIResponseType
  | GetCurrentFlightErrorRootAPIResponseType;

If the output file already exists, it is replaced.

📦 Publish to npm

This package is published to the public npm registry as @darth_sith_99/json-to-interface. Publishing is done from your machine with your npm account. The @darth_sith_99 scope must belong to that account.

npm login
pnpm publish

pnpm publish builds the package first. npm rejects a version that was already published, so bump version in package.json before the next release.

Install or run it with:

pnpm add @darth_sith_99/json-to-interface

# Or run it without adding it to the project
pnpm dlx @darth_sith_99/json-to-interface --help