{"id":11177,"library":"json-to-ts","title":"JSON to TypeScript Interface Converter","description":"json-to-ts is a utility library, currently at stable version 2.1.0, designed to automatically convert JSON objects into corresponding TypeScript interface definitions. It parses input JSON data, intelligently inferring primitive types (strings, numbers, booleans), array structures, and nested objects. Key differentiators include its robust handling of complex scenarios like automatic array type merging, generation of union types where data properties might vary, and prevention of redundant type declarations, ensuring clean and efficient output. It also offers the capability to infer optional properties. This package aims to streamline the developer workflow by reducing the manual effort and potential for errors associated with defining TypeScript types for API responses or dynamic data structures. It follows an active release cadence, providing reliable tooling for TypeScript projects dealing with structured JSON.","status":"active","version":"2.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/MariusAlch/json-to-ts","tags":["javascript","typescript","ts","convert","json","util","lib","types"],"install":[{"cmd":"npm install json-to-ts","lang":"bash","label":"npm"},{"cmd":"yarn add json-to-ts","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-to-ts","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The primary conversion function is exported as the default export in ESM. Attempting a named import will likely result in an undefined function.","wrong":"import { JsonToTS } from 'json-to-ts';","symbol":"JsonToTS","correct":"import JsonToTS from 'json-to-ts';"},{"note":"For CommonJS environments, the entire module export is the JsonToTS function.","symbol":"JsonToTS (CommonJS)","correct":"const JsonToTS = require('json-to-ts');"},{"note":"While `json-to-ts` generates types, if you need to import its internal types (e.g., for extending its behavior), they are typically found in the `dist/types` directory. However, generally, you'd use the generated types directly.","symbol":"Type definitions","correct":"import type { RootObject, Cat } from 'json-to-ts/dist/types';"}],"quickstart":{"code":"import JsonToTS from 'json-to-ts';\n\nconst json = {\n  users: [\n    { id: 1, name: 'Alice', email: 'alice@example.com' },\n    { id: 2, name: 'Bob', email: 'bob@example.com', phone: '123-456-7890' }\n  ],\n  settings: {\n    theme: 'dark',\n    notificationsEnabled: true\n  },\n  version: 2.1,\n  timestamp: new Date().toISOString()\n};\n\nconsole.log('Generating TypeScript interfaces...');\nJsonToTS(json, {\n  rootName: 'AppData',\n  // Optional: customize type names, e.g., for arrays of specific objects\n  // arrayTypeSuffix: 'Item'\n}).forEach(typeInterface => {\n  console.log(typeInterface);\n});\n/* Expected Output:\ninterface AppData {\n  users: User[];\n  settings: Settings;\n  version: number;\n  timestamp: string;\n}\ninterface User {\n  id: number;\n  name: string;\n  email: string;\n  phone?: string;\n}\ninterface Settings {\n  theme: string;\n  notificationsEnabled: boolean;\n}\n*/","lang":"typescript","description":"This example demonstrates how to import and use `json-to-ts` to convert a complex JSON object into a set of TypeScript interfaces, including nested objects and optional properties."},"warnings":[{"fix":"For extremely complex or large JSONs, consider simplifying the input or manually refining the generated types. Ensure your `tsconfig.json` has appropriate `maxNodeModuleJsDepth` or similar settings if encountering deep recursion errors.","message":"Generating types for very large or deeply nested JSON structures can strain TypeScript's type inference engine, potentially leading to slow compilation times or 'Type instantiation is excessively deep and potentially infinite' errors, particularly with older TypeScript versions or specific compiler flags.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Review the generated types for `any` or overly broad union types. Manually specify more precise types if the inference is not exact enough for your use case, particularly for optional fields (e.g., `field?: Type`) or explicit nullability (e.g., `field: Type | null`).","message":"While `json-to-ts` excels at inference, highly ambiguous JSON structures (e.g., arrays with mixed types, objects with inconsistent property presence across array elements, or null values without explicit alternatives) might result in broader union types or `any` where more specific types were desired. This sometimes requires manual refinement of the generated interfaces.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `esModuleInterop: true` in your `tsconfig.json` for better compatibility. Always use the default import syntax (`import JsonToTS from 'json-to-ts';`) for ESM, and `const JsonToTS = require('json-to-ts');` for CommonJS.","message":"The library primarily uses a CommonJS default export (`module.exports = function`). When used in a pure ESM project, especially with strict `esModuleInterop: false` or certain bundler configurations, directly importing `JsonToTS` might behave unexpectedly if not using `import JsonToTS from 'json-to-ts'` (default import syntax).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install json-to-ts` or `yarn add json-to-ts`. Verify the import statement uses the correct package name: `from 'json-to-ts'`.","cause":"The package is not installed or the import path is incorrect.","error":"Cannot find module 'json-to-ts'"},{"fix":"For CommonJS, use `const JsonToTS = require('json-to-ts');`. For ESM, use `import JsonToTS from 'json-to-ts';` to correctly capture the default export.","cause":"The main conversion function was imported incorrectly, often by attempting a named import from a module that uses a default or CommonJS module.exports export.","error":"TypeError: JsonToTS is not a function"},{"fix":"Manually review and adjust the generated TypeScript interfaces to precisely reflect the expected JSON structure. Add `?` for optional properties or use union types (e.g., `string | number | null | undefined`) where data can vary. Ensure sample JSON provided for generation is representative of all possible data shapes.","cause":"The TypeScript interfaces generated by `json-to-ts` do not perfectly align with the actual runtime JSON data, possibly due to optional fields not being inferred correctly or unexpected variations in data structure.","error":"Property 'x' is missing in type 'Y' but required in type 'Z' (or similar type mismatch during compilation/runtime)"}],"ecosystem":"npm"}