Resolving 'types' can only be used in a .ts file Error with @ts-check in Visual Studio Code

Problem Background and Phenomenon Analysis

In the current web development landscape, TypeScript has gained significant popularity as a superset of JavaScript, offering robust type systems and development tool support. Many developers seek to gradually introduce TypeScript features into existing JavaScript projects through incremental migration strategies. Visual Studio Code, as a mainstream code editor, provides excellent TypeScript support, including enabling type checking in JavaScript files via the // @ts-check directive.

However, in practical applications, developers frequently encounter a typical error message: [js] 'types' can only be used in a .ts file.. This error commonly appears in configuration scenarios like:

// @ts-check

module.exports = {
  someMethod: (param: string): string => {
    return param;
  },
};

With a corresponding tsconfig.json configuration file that might look like:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "allowJs": true
  }
}

Deep Analysis of Error Root Causes

The core cause of this error lies in the limitations of Visual Studio Code's built-in TypeScript and JavaScript language features extension when handling mixed-type projects. Although the TypeScript compiler supports processing JavaScript files through the allowJs option, VS Code's language server imposes strict restrictions when parsing type annotations in JavaScript files.

From a technical implementation perspective, VS Code uses the TypeScript language service to provide IntelliSense functionality. When TypeScript type syntax is used in JavaScript files, the language service treats it as a syntax error because standard JavaScript syntax specifications do not support explicit type annotations. Even with the // @ts-check directive enabled, this limitation persists.

Solution Implementation Steps

Based on community-verified best practices, the most effective method to resolve this issue involves disabling VS Code's built-in TypeScript extension, with specific implementation steps as follows:

1. Open the Visual Studio Code editor
2. Navigate to the Extensions management panel (Ctrl+Shift+X shortcut)
3. Enter @builtin TypeScript and JavaScript Language Features in the search box
4. Locate the corresponding built-in extension entry
5. Click the disable button to deactivate this extension functionality

This solution works by disabling the built-in TypeScript processing mechanism, thereby avoiding its strict validation of type syntax in JavaScript files, while allowing other TypeScript-related extensions (such as TSLint) to normally provide code analysis and intelligent prompting functionality.

Configuration Optimization and Considerations

When implementing the above solution, several key configuration points require attention:

First, ensure that TypeScript-related development dependencies are properly installed and configured in the project. The package.json file should include TypeScript as a development dependency:

{
  "devDependencies": {
    "typescript": "^4.0.0"
  }
}

Second, the tsconfig.json file configuration requires appropriate settings. The allowJs option must be set to true to allow the TypeScript compiler to process JavaScript files. Additionally, configuring the checkJs option is recommended to enable type checking for JavaScript files:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "allowJs": true,
    "checkJs": true
  }
}

Comparative Analysis of Alternative Solutions

Beyond the built-in extension disabling approach, several alternative solutions exist in the community, each with distinct advantages and disadvantages:

Alternative 1: Disabling JavaScript Validation
This involves setting "javascript.validate.enable": false to turn off VS Code's JavaScript validation functionality. While this approach can eliminate type error prompts, it simultaneously loses basic JavaScript syntax checking, potentially introducing other underlying issues.

Alternative 2: Using JSDoc Annotations
Providing type information through JSDoc comments represents a JavaScript standards-compliant approach:

// @ts-check

/**
 * @param {string} param
 * @returns {string}
 */
module.exports.someMethod = function(param) {
  return param;
};

This method offers better compatibility but has relatively limited type expression capabilities.

Best Practice Recommendations

Based on practical project experience, the following best practices are recommended to optimize TypeScript usage in mixed projects:

Version Management Consistency: Ensure the TypeScript version used by VS Code matches the project dependency version. Use the command palette (Ctrl+Shift+P) to execute the TypeScript: Select TypeScript Version command and select the workspace version.

Server Process Management: When encountering persistent type errors, try restarting the TypeScript language server. Execute the TypeScript: Restart TS Server command through the command palette to reinitialize the language service process.

Incremental Migration Strategy: For large JavaScript projects, adopt an incremental migration approach. Begin by enabling type checking in critical modules, gradually expanding coverage to avoid development resistance caused by introducing excessive type constraints simultaneously.

In-Depth Technical Principle Discussion

From an underlying implementation perspective, Visual Studio Code's TypeScript support is based on the Language Server Protocol (LSP). The language server runs as an independent process responsible for code analysis, type checking, and intelligent prompting functionalities.

When TypeScript type syntax is used in JavaScript files, the language server faces syntax parsing conflicts. Standard JavaScript parsers cannot recognize TypeScript-specific type annotation syntax, resulting in the 'types' can only be used in a .ts file error.

The built-in extension disabling solution proves effective because it bypasses VS Code's default strict syntax checking mechanism, allowing third-party TypeScript toolchains to handle type-related functionalities, thereby maintaining development experience while avoiding syntax conflicts.

Conclusion and Future Outlook

By disabling Visual Studio Code's built-in TypeScript and JavaScript language features extension, developers can effectively resolve type syntax errors encountered when using // @ts-check in JavaScript files. This solution provides enhanced type checking experience while maintaining code intelligence functionality.

As the TypeScript ecosystem continues to evolve, more comprehensive solutions may emerge in the future. Currently, this extension management-based approach has been validated as reliable and effective through numerous practical projects, making it worthy of promotion in similar development scenarios.