TypeScript Reference ยท Modules and Declaration Files
Importing JSON in TypeScript
Import JSON files in TypeScript: resolveJsonModule, import attributes with type json, inferred types, Node's runtime rules, and safe alternatives for untyped data.
A .json file can be imported like a module. With resolveJsonModule enabled, TypeScript reads the file and infers a type from its contents, so config.port is a number and a typo like config.prot is an error. The value you get is the parsed JSON, and there is only a default export (plus, in some setups, named exports for top-level keys).
In real ES modules the host also needs to be told that the file is JSON and not JavaScript, using an import attribute: import data from "./data.json" with { type: "json" }. Node requires this attribute for ES module imports of JSON. Under module: "nodenext", TypeScript requires the attribute too.
import settings from "./settings.json" with { type: "json" }; const data = await import("./data.json", { with: { type: "json" } });
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.
Syntax
import name from "./file.json" with { type: "json" }; import("./file.json", { with: { type: "json" } }): Promise<{ default: JsonType }>
{ "compilerOptions": { "resolveJsonModule": true } }
| Part | Description |
|---|---|
with { type: "json" } |
Import attributes (TypeScript 5.3+). Tells the runtime to parse the file as JSON. Older code used assert { type: "json" }, which Node no longer accepts. |
resolveJsonModule |
Lets TypeScript load .json files and infer their types. Defaults to on with moduleResolution: "bundler"; set it explicitly in other setups. |
| Default import | The whole parsed object. Named imports of top-level keys work in some bundlers, but not in Node ES modules. |
Errors and edge cases:
- Without
resolveJsonModule, importing JSON reports TS2732: Cannot find module; consider using--resolveJsonModule. - Node rejects an ES import of JSON without the attribute with
ERR_IMPORT_ATTRIBUTE_MISSING. - Inferred types are widened:
"red"becomesstring, and arrays becomeT[], not tuples. JSON cannot carryas const. - JSON must be strict: no comments, no trailing commas. Only
.jsonfiles are covered;.jsoncand.json5are not. - Large JSON files slow type checking, because TypeScript infers a type for every value.
Usage notes
- Under
module: "commonjs"withesModuleInterop,import data from "./data.json"works without attributes, because the output isrequire. Switching the module format later then needs the attribute. - For files you read at run time (user input, network), the type is not inferred.
JSON.parsereturnsany, so validate it, as in the second example or with a validation library. import.meta.dirnameplusreadFileSyncis a flexible alternative when you want a path computed at run time or the file is outside your source folder.- If you need exact literal types from a config, write it as a
.tsfile withas constorsatisfiesinstead.