https://github.com/privatenumber/fix-verbatim-module-syntax
CLI tool to auto-fix verbatimModuleSyntax errors
https://github.com/privatenumber/fix-verbatim-module-syntax
Last synced: 3 months ago
JSON representation
CLI tool to auto-fix verbatimModuleSyntax errors
- Host: GitHub
- URL: https://github.com/privatenumber/fix-verbatim-module-syntax
- Owner: privatenumber
- License: mit
- Created: 2024-12-24T11:24:56.000Z (10 months ago)
- Default Branch: develop
- Last Pushed: 2024-12-26T06:04:18.000Z (10 months ago)
- Last Synced: 2025-06-27T14:00:04.829Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 77.1 KB
- Stars: 80
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fix-verbatim-module-syntax
CLI tool to auto-fix [`verbatimModuleSyntax`](https://www.typescriptlang.org/tsconfig/verbatimModuleSyntax.html) errors in your TypeScript project:
```
error TS1484: 'SomeType' is a type and must be imported using a type-only import when 'verbatimModuleSyntax' is enabled.
```
### Why?
`verbatimModuleSyntax` is a TypeScript config introduced in [v5](https://devblogs.microsoft.com/typescript/announcing-typescript-5-0/#--verbatimmodulesyntax). Enabling it is highly recommended as it enforces explicit type imports/exports, ensuring predictable compilation.
Previously, TypeScript automatically detected and removed type-only imports/exports during compilation. But this could lead to runtime issues if the imported modules had side effects. To address this, `verbatimModuleSyntax` was introduced to require explicitly marked type imports/exports, making the code more maintainable and resilient against unexpected behavior during compilation.
However, enabling `verbatimModuleSyntax` may initially produce many errors related to missing type annotations. Fixing these manually can be tedious so this command-line tool automates the process for you.
## Usage
Ensure TypeScript v5 is installed in your project, then run the following command in the project directory, specifying the path to your `tsconfig.json`.
> [!WARNING]
> This command will modify your files. Be sure to back up or commit your changes beforehand.
```sh
npx fix-verbatim-module-syntax ./tsconfig.json
```
After running the command, add [`"verbatimModuleSyntax": true`](https://www.typescriptlang.org/tsconfig/verbatimModuleSyntax.html) to your `tsconfig.json`.
### Dry-run mode
To preview changes without modifying files, use the `--dry` flag:
```sh
npx fix-verbatim-module-syntax --dry ./tsconfig.json
```
### ESLint integration
You can enforce and auto-fix type-only imports directly in your ESLint setup by using `typescript-eslint`'s [`consistent-type-imports`](https://typescript-eslint.io/rules/consistent-type-imports/) rule.
Here's how they compare:
| | `fix-verbatim-module-syntax` | `@typescript-eslint/consistent-type-imports` |
|-|-|-|
| **Type detection** | Uses TypeScript's type-checker for precise identification | Analyzes code usage to infer types |
| **Usage** | TypeScript-powered CLI tool | Works within ESLint for broader linting coverage |
| **Scope** | Files matching the `tsconfig.json` configuration | Files passed to ESLint |
#### When to use which?
Both tools complement each other and can help ensure your project adheres to clean, modern TypeScript standards.
- Use `fix-verbatim-module-syntax` for a one-time, comprehensive fix of your project when enabling `verbatimModuleSyntax`.
- Use `consistent-type-imports` for ongoing auto-fixable enforcement of type-only imports during development.
> [!TIP]
> Along with `verbatimModuleSyntax`, it's recommended to enable the [`@typescript-eslint/no-import-type-side-effects`](https://typescript-eslint.io/rules/no-import-type-side-effects/) ESLint rule to discourage using side-effects from imported modules.
## Sponsors
