{"id":29409206,"url":"https://github.com/ycmjason/ts-migrating","last_synced_at":"2025-10-10T12:57:07.421Z","repository":{"id":295984293,"uuid":"991491491","full_name":"ycmjason/ts-migrating","owner":"ycmjason","description":"This plugin lets you upgrade to your desired compilerOptions (e.g. strict, noUncheckedIndexedAccess, erasableSyntaxOnly) across your entire codebase, while letting problematic lines fall back to the old compilerOptions.","archived":false,"fork":false,"pushed_at":"2025-09-06T06:16:22.000Z","size":1471,"stargazers_count":60,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-10T01:03:07.249Z","etag":null,"topics":["strict-mode","ts-strict","tsconfig","typescript","typescript-library","typescript-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ts-migrating","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ycmjason.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"ycmjason"}},"created_at":"2025-05-27T17:50:56.000Z","updated_at":"2025-09-23T18:22:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"eb2f8d87-fcf0-415e-af5c-1241c2dc0f70","html_url":"https://github.com/ycmjason/ts-migrating","commit_stats":null,"previous_names":["ycmjason/ts-migrating"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ycmjason/ts-migrating","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycmjason%2Fts-migrating","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycmjason%2Fts-migrating/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycmjason%2Fts-migrating/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycmjason%2Fts-migrating/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ycmjason","download_url":"https://codeload.github.com/ycmjason/ts-migrating/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ycmjason%2Fts-migrating/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279003891,"owners_count":26083641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["strict-mode","ts-strict","tsconfig","typescript","typescript-library","typescript-plugin"],"created_at":"2025-07-11T04:02:06.702Z","updated_at":"2025-10-10T12:57:07.413Z","avatar_url":"https://github.com/ycmjason.png","language":"TypeScript","funding_links":["https://github.com/sponsors/ycmjason"],"categories":["Language service plugins"],"sub_categories":["Optimization"],"readme":"# `@ts-migrating` — Progressively Upgrade `tsconfig.json`\n\n🚀 **TypeScript keeps evolving — and your `tsconfig` should too.**\n\nThis plugin lets you upgrade to your desired `compilerOptions` (e.g. `strict`, `noUncheckedIndexedAccess`, `erasableSyntaxOnly`, `checkJs`) across your entire codebase, while letting problematic lines fall back to the old `compilerOptions`.\n\nUpgrading `tsconfig` often breaks existing code, and fixing all errors at once is unrealistic.\n\n**`@ts-migrating`** helps your team migrate to a desired `tsconfig` gradually and safely.\n\n\u003e I chose `@ts-migrating` (rather than `@ts-migration`) to better reflect the plugin’s progressive and incremental philosophy.\n\n## 🙋‍♀️ Why not `@ts-expect-error` / `@ts-ignore`?\n\nUsing `@ts-expect-error` or `@ts-ignore` to silence TypeScript errors can work in the short term — but they come with trade-offs:\n\n- They suppress all errors on the line, not just those introduced by the new `compilerOptions`. This can hide unrelated issues and introduce technical debt.\n- There are cases where you actually want to use `@ts-expect-error` and `@ts-ignore`. Mixing their real usages with `tsconfig` migration is 🤮.\n\nThis plugin takes a different approach: it lets you apply the desired `compilerOptions` globally while allowing them to be reverted line-by-line. This keeps your code clean, and your intent clear — enabling a safer and more maintainable upgrade path.\n\n## 🤖 How does this work?\n\n`@ts-migrating` is a TypeScript plugin that lets you **enable your target tsconfig during development** (in IDEs or editors that use the [TypeScript Language Service](https://github.com/microsoft/typescript/wiki/Using-the-Language-Service-API)) and in CI — **without affecting `tsc` or your production build**.\n\nThe philosophy behind the plugin follows three simple steps:\n\n1. 🛑 **Prevention**\n\n   * Errors from your target config are surfaced during development and in CI.\n   * This ensures no new violations are introduced into the codebase.\n\n2. 🔧 **Reduction**\n\n   * Lines marked with `@ts-migrating` will be typechecked with your original `tsconfig`. Ensuring type-safety throughout.\n   * Developers can progressively fix these lines, reducing violations over time.\n\n3. ✅ **Migration**\n\n   * Once all violations are fixed, no `@ts-migrating` directives remain.\n   * At this point, you're ready to fully adopt the new tsconfig — and the plugin has served its purpose.\n\n## 📚 Overview\n\n`@ts-migrating` consists of two parts:\n\n1. 🔌 **[TypeScript Language Service Plugin](https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin)**\n\n   * Enables IDEs to show errors from the `tsconfig` you're migrating to.\n   * Revert lines marked with `@ts-migrating` to be type-checked with your original `tsconfig`.\n\n2. 🖥️ **Standalone CLI: `ts-migrating`**\n\n   * `ts-migrating check`\n\n     * Run `@ts-migrating`-aware type checking using your new `tsconfig`.\n   * `ts-migrating annotate`\n\n     * Automatically mark all errors caused by your new `tsconfig` with `@ts-migrating`.\n     * ⚠️ Run this with a clean git state!!! This script will automatically add the `@ts-migrating` directive above every line with TypeScript error introduced by your new `tsconfig`. Please review the changes carefully. It is recommended to run your formatter and linter afterwards. You may need to run this command again after formatter / linter.️\n\n## 🎪 Examples\n\n* [Migrating to `strict`](./examples/strict-mode-migration/src/index.ts)\n* [Migrating to `noUncheckedIndexedAccess`](./examples/no-unchecked-indexed-access-migration/src/index.ts):\n\n  | Without `@ts-migrating` | With `@ts-migrating` |\n  | ----------------------- | -------------------- |\n  | ![Migrating to noUncheckedIndexedAccess](./assets/ts-migrating-no-unchecked-indexed-access.png)  | ![Migrating to noUncheckedIndexedAccess marked](./assets/ts-migrating-no-unchecked-indexed-access-marked.png)  |\n\n* [Migrating to `erasableSyntaxOnly`](./examples/erasable-syntax-only-migration/src/index.ts)\n* [Migrating to `checkJs`](./examples/check-js-migration/src/index.js)\n\n## 📦 Install and Setup\n\nThis project does **NOT** require any IDE extensions. It relies purely on TypeScript's own Language Service, so it works on most IDEs and editors that support TypeScript (e.g., VSCode, WebStorm).\n\nTo install:\n\n```bash\ncd my-cool-project\nnpm install -D ts-migrating\n```\n\nIn your existing `tsconfig.json`, add the plugin:\n\n```jsonc\n{\n  // ...\n  \"compilerOptions\": {\n    // ...\n    \"plugins\": [\n      {\n        \"name\": \"ts-migrating\",\n        \"compilerOptions\": {\n          // ... put the compiler options you wish to migrate to, for example:\n          \"strict\": true\n        }\n      }\n    ]\n    // ...\n  }\n  // ...\n}\n```\n\nℹ️ *Note: `plugins` only affect the TypeScript Language Service (used by IDEs). They do **not** impact `tsc` or your build.*\n\n🎉 Your codebase is now ready!\n\n### ✅ Verify the Setup\n\n#### 🧑‍💻 In your IDE\n\n* Restart the IDE, or just the TS server.\n* Confirm that type errors now reflect the new `compilerOptions`. For example, when migrating to strict mode, verify that strict-specific errors appear.\n* Add `// @ts-migrating` before a line with an error — the error should disappear in the IDE.\n\n#### 🖥 In the terminal\n\n* Run:\n\n  ```bash\n  npx ts-migrating check\n  ```\n\n  You should see errors from the new config, excluding those marked with `@ts-migrating`.\n\n### ✨ Optional Next Steps\n\n* Run `npx ts-migrating annotate` to automatically annotate newly introduced errors with `// @ts-migrating`.\n* Replace your CI type-check step with `npx ts-migrating check` to prevent unreviewed errors from slipping through.\n\n## API\n\nYou can use this project programmatically. This can be useful if you would like to have custom integrations, for example: reporting error counts to dashboard etc.\n\nCurrently there are only 2 functions exposed, [`getSemanticDiagnosticsForFile`](./src/api/getSemanticDiagnostics.ts) and [`isPluginDiagnostic`](./src/api/isPluginDiagnostic.ts). You can import them via `ts-migrating/api`, e.g.\n\n```ts\nimport { getSemanticDiagnosticsForFile, isPluginDiagnostic } from 'ts-migrating/api';\n\ngetSemanticDiagnosticsForFile('path/to/file.ts') // returns all diagnostics using your new tsconfig, including non-plugin ones\n  .filter(isPluginDiagnostic) // removes all non-plugin diagnostics\n```\n\nYou could technically also import from `ts-migrating/cli` and `ts-migrating` (the ts plugin itself) too.\n\n## 📣 Shoutout\n\nThis project wouldn't be possible without inspiration from:\n\n* [allegro/typescript-strict-plugin](https://github.com/allegro/typescript-strict-plugin):\n  Especially for revealing the undocumented [`updateFromProject` option](https://github.com/allegro/typescript-strict-plugin/blob/master/src/plugin/utils.ts#L28-L32) which helped fix a critical issue with the standalone script. [You can find out more here](./src/plugin/mod.ts#L31)).\n\n## 👤 Author\n\nYCM Jason\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fycmjason%2Fts-migrating","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fycmjason%2Fts-migrating","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fycmjason%2Fts-migrating/lists"}