How to migrate json config files to yaml
- Step 1Confirm the target tool reads YAML — Check the migration matrix below. ESLint, Prettier, Babel (via separate config), and most app configs accept YAML.
package.jsonandtsconfig.jsondo not — don't migrate those. - Step 2Get the JSON config file — Open the JSON config in your editor and save a copy —
.eslintrc.json,.prettierrc.json, or your app'sconfig.json. Keep the original until you've verified the YAML works. - Step 3Drop the JSON file on the tool — There's no paste field — drop the
.jsonfile onto the dropzone. Free tier accepts files up to 2 MB; Pro raises it to 100 MB, far beyond any config file. - Step 4Choose indent 2 and run — Leave indent at 2 (the near-universal config convention) and click Convert to YAML. The output is standard YAML with unquoted keys and proper sequence formatting for array values like ESLint
extends. - Step 5Add the comments that justify the migration — Paste the YAML into your editor and add
#comments above non-obvious rules or sections — e.g. why a lint rule is disabled. This is the main reason to move off JSON; the conversion itself can't add them. - Step 6Rename, test, then delete the JSON — Rename
.eslintrc.json→.eslintrc.yaml(or.yml), delete the JSON, and run the tool (eslint .,prettier --check ., etc.) to confirm it reads the YAML. To verify fidelity, round-trip back with yaml-to-json and diff.
Which configs can move to YAML
Whether the tool natively reads a YAML config. Verify against your tool version's docs before deleting the JSON.
| Config | YAML supported? | YAML filename / note |
|---|---|---|
| ESLint (legacy) | Yes | .eslintrc.yaml / .eslintrc.yml. Flat config (eslint.config.js) is JS-only, not YAML |
| Prettier | Yes | .prettierrc.yaml / .prettierrc.yml |
| Babel | Partial | babel.config.json is supported; for YAML, use babel.config.js to require() a YAML file — Babel has no native .yaml config |
| Custom app config | Usually | Most YAML parsers (js-yaml, PyYAML) read it; depends on your app's loader |
| package.json | No | Node.js reads JSON only — never migrate this |
| tsconfig.json | No | tsc reads JSON-with-comments; not natively YAML. (ts-node can be configured, but tsc itself can't) |
Conversion behaviour for config files
What happens to the value shapes config files use most.
| JSON in | YAML out | Config note |
|---|---|---|
"extends": ["airbnb", "prettier"] | extends: sequence | Array becomes a clean - list |
"no-console": "warn" | no-console: warn | Rule level unquoted string — paste-ready |
"semi": ["error", "always"] | semi: sequence | ESLint tuple rule → 2-item YAML list |
"tabWidth": 2 | tabWidth: 2 | Integer stays an integer |
"version": "3.10" | version: '3.10' | Quoted string — 3.10 would otherwise be read as the float 3.1 |
"//": "comment-as-key hack" | '//': comment-as-key hack | The JSON "//" comment hack becomes a real key — delete it and use a real # comment instead |
Cookbook
Real config files migrated from JSON to YAML. Paths and package names are illustrative; nothing is uploaded.
.eslintrc.json → .eslintrc.yaml
ExampleAn ESLint config loses its quote noise in YAML, and array rule tuples become readable two-item lists. Add comments after to explain why a rule is set.
JSON (.eslintrc.json):
{"extends":["airbnb","prettier"],
"rules":{"no-console":"warn","semi":["error","always"]}}
YAML (.eslintrc.yaml, indent 2):
extends:
- airbnb
- prettier
rules:
no-console: warn
semi:
- error
- alwaysComments don't transfer — add them after
ExampleThe conversion preserves values but cannot create comments (JSON has none). Gaining comments is the entire point of migrating, so add them by hand.
JSON: {"rules":{"no-explicit-any":"off"}}
YAML as produced (no comment):
rules:
no-explicit-any: off # <- 'off' is quoted? see next example
After hand-editing:
rules:
# disabled until the legacy module is typed (TICKET-481)
no-explicit-any: 'off'The 'off' / 'on' / version-string quoting
ExampleValues that look like YAML 1.1 keywords or numbers are quoted so they stay strings. An ESLint level of "off" stays the string 'off', not the boolean false.
JSON:
{"rules":{"camelcase":"off"},"node":"3.10"}
YAML:
rules:
camelcase: 'off' # quoted: stays the string 'off', not boolean
node: '3.10' # quoted: stays a version string, not 3.1Don't migrate package.json
ExampleNode.js only ever reads package.json as JSON. Converting it to YAML produces valid YAML, but npm/yarn/pnpm will ignore it — keep package.json as JSON.
package.json (keep as JSON):
{"name":"my-app","scripts":{"build":"tsc"}}
Converting to YAML 'works' but is useless:
name: my-app
scripts:
build: tsc
→ npm reads NONE of this. package.json must stay JSON.Removing the "//" comment-key hack
ExampleSome JSON configs fake comments with a "//" key. After converting to YAML, delete that key and replace it with a real # comment — the reason YAML is better for configs.
JSON (fake comment):
{"//":"keep in sync with CI","timeout":30}
YAML as produced:
'//': keep in sync with CI
timeout: 30
Clean it up:
# keep in sync with CI
timeout: 30Errors and edge cases
Real errors and silent failures sourced from each platform's own documentation. Match the wording to the row, fix what the row says to fix.
package.json migrated to YAML
Unsupported by NodeNode.js, npm, yarn, and pnpm only read package.json as JSON. Converting it to YAML produces valid YAML, but no tool will read it — your scripts, dependencies, and metadata effectively vanish. Never migrate package.json; keep it as JSON.
tsconfig.json migrated to YAML
Unsupported by tscThe TypeScript compiler reads tsconfig.json as JSON-with-comments and does not natively load a YAML tsconfig. ts-node can be configured to read alternatives, but tsc itself cannot. Keep tsconfig.json as JSON; you can keep its comments there since TS allows them.
Comments cannot be carried over
By designJSON has no comments to migrate, and the converter adds none. The output YAML is comment-free. Add # comments by hand afterward — that capability is precisely why YAML configs are worth the migration.
'off'/'on'/'yes' quoted to stay strings
PreservedESLint rule levels and similar values like off, on, yes, no are quoted on output ('off') so YAML 1.1 doesn't coerce them to booleans. This keeps the config semantically identical. Leave the quotes; removing them risks off becoming the boolean false.
Version strings quoted to avoid float coercion
PreservedA string like "3.10" becomes '3.10', preventing YAML from reading it as the float 3.1. If your JSON stored the version as a number (3.10), JSON.parse already dropped the trailing zero before conversion — store versions as strings.
Invalid JSON (trailing comma / comment)
ErrorThe converter runs JSON.parse. Many real-world config files include trailing commas or // comments (which strict JSON forbids — tsconfig.json allows them but it's not pure JSON). These throw a parse error. Run the file through json-format-fixer first to strip comments and trailing commas.
The "//" comment-as-key hack becomes a real key
Cleanup neededConfigs that fake comments with a "//" key convert that key literally into YAML ('//': ...). Delete it after conversion and replace it with a proper # comment — the whole reason to move to YAML.
Indent 4 produces unusual config formatting
ExpectedConfig files almost universally use 2-space indent. Indent 4 is valid but expands array items (like ESLint extends) onto separate lines and looks unfamiliar in a config. Use indent 2.
null config values left literal
PreservedJSON null becomes YAML null. Some loaders treat null differently from an absent key. Review null-valued settings; to drop them, pre-clean with json-null-stripper before converting.
Duplicate keys collapse to last
Last winsIf a hand-edited config has the same key twice, JSON.parse keeps only the last before conversion — the first is silently lost. Validate with json-validator if you've been merging configs manually.
Frequently asked questions
Which config files can't be migrated to YAML?
package.json (Node.js, npm, yarn, and pnpm read it only as JSON) and tsconfig.json (the tsc compiler reads JSON-with-comments and doesn't natively load YAML). Converting either produces valid YAML that the respective tool simply ignores. ESLint (.eslintrc.yaml), Prettier (.prettierrc.yaml), and most app configs migrate fine — check the matrix above.
Are comments carried over or generated?
Neither. JSON has no comments to migrate, and the converter doesn't invent any. The output YAML is comment-free; add # comments by hand afterward. Gaining the ability to comment is the main reason to migrate a config from JSON to YAML.
Why is my ESLint level "off" quoted as 'off' in the YAML?
Because YAML 1.1 treats bare off (and on, yes, no) as booleans. The converter quotes the string value as 'off' so it stays the string ESLint expects, not the boolean false. Leave the quotes — removing them would change the meaning.
Will special characters in string values get quoted correctly?
Yes. js-yaml quotes any string that starts with a special character (#, :, *, &, @, [, {) or contains a colon-space, so the YAML stays valid. It also quotes strings that look like numbers or YAML keywords. You generally don't need to fix quoting by hand, but it's worth a quick scan.
Can I convert tsconfig.json since it has comments?
You can convert it, but tsc won't read the YAML result, so it's not useful. Also, if your tsconfig.json contains // comments or trailing commas (allowed by TS but not by strict JSON), JSON.parse will reject it — run it through json-format-fixer first. Best practice: leave tsconfig.json as JSON, where TS permits comments anyway.
Is the configuration file content sent to JAD Apps?
No. Conversion runs entirely in your browser using js-yaml. Config contents — internal paths, package names, and rule settings — never reach a JAD Apps server. The only server-side record when signed in is an anonymous run counter, with no content.
How much shorter is the YAML version?
Typically meaningfully shorter, because YAML drops the quotes around keys and most string values and removes the braces and trailing commas. The exact reduction depends on how nested and string-heavy the config is, but the readability gain is consistent — fewer punctuation characters per line.
What about the "//" comment hack some JSON configs use?
A "//" key converts to a literal '//': key in YAML. After converting, delete it and write a real # comment instead — that's the cleaner YAML idiom and the reason the migration is worthwhile.
Which indent should I use for config files?
Indent 2 — it's the near-universal config convention. Indent 4 is valid but expands array items onto separate lines and looks unfamiliar in a config file.
What's the file size limit?
Free tier accepts files up to 2 MB; Pro raises it to 100 MB — both far larger than any config file. The tool takes a dropped .json file; there's no paste box.
How do I verify the YAML config behaves identically?
Round-trip it: convert the YAML back to JSON with yaml-to-json and diff against the original with json-diff. A clean diff (key order aside if you used sort-keys) confirms every value survived. Then run the actual tool (eslint ., prettier --check .) against the YAML to confirm it loads.
Should I sort the keys when migrating?
Off by default, which keeps your config's logical grouping intact (e.g. ESLint env → extends → rules). Turn sort-keys on only if you want a long rules block alphabetised for easier scanning.
Privacy first
Conversion runs locally in your browser. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.