Encountering the dreaded “Error: ’types’ can only be used in a .ts file” in Visual Studio Code while leveraging @ts-check in JavaScript files can be a frustrating experience. This error typically surfaces when TypeScript syntax, particularly type annotations, is used within a JavaScript (.js) file that’s being type-checked by TypeScript’s @ts-check feature. While @ts-check is a powerful tool for adding type checking to JavaScript, it has certain limitations compared to working directly with TypeScript files. Understanding the root cause of this error, and knowing the appropriate solutions, is crucial for maintaining code quality and preventing unexpected runtime behavior. This article dives deep into why this error occurs and provides actionable steps to resolve it, ensuring a smoother development workflow when combining JavaScript and TypeScript.

Understanding the Error: Why It Occurs

The “Error: ’types’ can only be used in a .ts file” arises because the TypeScript compiler, even when invoked through @ts-check, expects full TypeScript syntax only within .ts or .tsx files. JavaScript files, even with @ts-check, are meant to use JSDoc comments for type annotations, a less strict and more JavaScript-centric approach to type hinting. When you directly use TypeScript-specific keywords like type, interface, or other advanced type constructs, the compiler flags it as an error because it’s outside of a designated TypeScript file. Effectively, you’re trying to use TypeScript features in a context where they aren’t fully supported.

Consider this scenario: You have a JavaScript file, myScript.js, and you’re using @ts-check to get some type safety. Inside this file, you define a type alias using the type keyword: type MyStringType = string;. Running the TypeScript compiler, even implicitly through VS Code with @ts-check enabled, will result in the aforementioned error. This is because the compiler interprets this line as invalid JavaScript syntax enhanced with TypeScript features outside of a .ts context. According to the TypeScript documentation, “The @ts-check option enables type checking in JavaScript files.” TypeScript Handbook This doesn’t mean you can use all TypeScript syntax, but rather a subset through JSDoc.

The key takeaway here is that @ts-check provides a way to gradually introduce type checking into existing JavaScript codebases, but it doesn’t magically transform JavaScript files into TypeScript files. It uses JSDoc comments to infer types and provide warnings, rather than relying on the full power of TypeScript’s type system. Using full TypeScript syntax requires migrating the file to a .ts file.

Resolving the “Types” Error: Practical Solutions

There are several ways to address the “Error: ’types’ can only be used in a .ts file”. The best approach depends on your project’s goals and the extent to which you want to embrace TypeScript.

1. Rename the File to .ts: This is the most straightforward solution if you intend to fully utilize TypeScript’s features. By renaming your .js file to .ts, you’re explicitly telling the TypeScript compiler that this file should be treated as a TypeScript file, allowing you to use all TypeScript syntax without errors. Remember to update any import statements or references to the file accordingly.
2. Use JSDoc Type Annotations: If you want to keep the file as a .js file but still benefit from type checking, use JSDoc comments to annotate your variables, function parameters, and return types. For instance, instead of type MyStringType = string;, you would use / @typedef {string} MyStringType /. This approach allows you to define types and provide type information to the TypeScript compiler without using native TypeScript syntax.
3. Declare Types in a .d.ts File: You can define your TypeScript types in a separate .d.ts (declaration) file. This file contains only type definitions and interfaces. Then, you can reference these types in your JavaScript file using JSDoc comments. This approach keeps your JavaScript code clean while still leveraging the power of TypeScript’s type system. For example, create a file named types.d.ts and declare your type. Then in your JS file, you can use / @type {MyType} / to utilize it.

Choosing the right solution depends on your project’s needs and your team’s familiarity with TypeScript. If you’re just starting to explore type checking, JSDoc annotations might be a good starting point. If you’re ready to fully embrace TypeScript, renaming the file to .ts is the most effective option. Regardless of the approach you choose, understanding the underlying principles of how TypeScript interacts with JavaScript is crucial for avoiding common errors and ensuring a smooth development experience.

Leveraging JSDoc for Type Annotations: A Detailed Guide

When you want to keep your files as .js but still benefit from type checking with @ts-check, mastering JSDoc type annotations is essential. JSDoc is a documentation standard for JavaScript, and TypeScript can interpret JSDoc comments to infer types and provide type checking. This allows you to add type information to your code without needing to convert your files to .ts.

Here’s an example of how to use JSDoc to define a type for an object: javascript / @typedef {object} User @property {string} name - The user’s name. @property {number} age - The user’s age. / / @param {User} user - The user object. / function greetUser(user) { console.log(Hello, ${user.name}! You are ${user.age} years old.); } In this example, we define a User type using the @typedef tag, specifying the properties and their types. We then use the @param tag to specify the type of the user parameter in the greetUser function. This allows TypeScript to perform type checking on the greetUser function, ensuring that the user parameter has the expected properties. According to a Stack Overflow survey, “JSDoc is widely adopted for documenting JavaScript code.” Stack Overflow

Here are some key JSDoc tags you should be familiar with:

• @typedef: Defines a custom type.
• @param: Specifies the type of a function parameter.
• @returns: Specifies the return type of a function.
• @type: Specifies the type of a variable or expression.
• @callback: Defines a callback function type.

Using JSDoc effectively allows you to gradually introduce type checking into your JavaScript codebase, improving code quality and maintainability without requiring a complete migration to TypeScript. It’s a powerful tool for enhancing your JavaScript development workflow. This featured snippet optimized paragraph explains how JSDoc comments enable gradual type-checking in JavaScript files with @ts-check. By using tags like @typedef, @param, and @returns, developers can define types and annotate variables, function parameters, and return types. This allows TypeScript to infer types and provide warnings, improving code quality and maintainability without fully migrating to TypeScript.

Best Practices for Avoiding Type Errors

Preventing the “Error: ’types’ can only be used in a .ts file” and other type-related issues requires adopting best practices in your development workflow. These practices not only help you avoid errors but also improve the overall quality and maintainability of your code.

• Consistent Type Annotations: Whether you’re using JSDoc or TypeScript syntax, ensure that you consistently annotate your variables, function parameters, and return types. This helps the TypeScript compiler infer types accurately and catch potential errors early on.
• Gradual Migration: If you’re migrating from JavaScript to TypeScript, do it gradually. Start by adding @ts-check to your JavaScript files and using JSDoc annotations. Then, progressively convert your files to .ts as you become more comfortable with TypeScript syntax.

Another important practice is to configure your TypeScript compiler options appropriately. The tsconfig.json file allows you to specify various compiler options, such as the target JavaScript version, module system, and strictness settings. Enabling strict mode ("strict": true) is highly recommended, as it enables all strict type checking options, helping you catch more potential errors. According to Google’s Angular style guide, “Enable strict mode in TypeScript to improve code quality.” Angular Style Guide

Furthermore, utilize linting tools like ESLint with the TypeScript plugin to enforce coding style and catch potential errors. ESLint can be configured to check for type-related issues, such as missing type annotations or incorrect type usage. By integrating these tools into your development workflow, you can proactively identify and fix type errors, preventing them from causing problems in production.

**Q: Can I use TypeScript features like generics in JavaScript files with `@ts-check`?**

A: While you can use some advanced type constructs through JSDoc, full support for features like generics is limited. You'll need to use JSDoc's equivalent syntax, which might not be as expressive or flexible as native TypeScript generics.

**Q: What's the difference between `@ts-check` and `// @ts-nocheck`?**

A: `@ts-check` enables type checking in a JavaScript file, while `// @ts-nocheck` disables type checking in a file. Use `@ts-check` to get type safety and `// @ts-nocheck` to temporarily ignore type errors in specific files.

**Q: How do I configure Visual Studio Code to automatically check JavaScript files with `@ts-check`?**

A: Visual Studio Code automatically detects `@ts-check` comments and enables type checking accordingly. Ensure that you have TypeScript installed and configured in your project for the best experience.

That “Error: ’types’ can only be used in a .ts file” doesn’t have to be a roadblock. By understanding the nuances of how TypeScript’s @ts-check interacts with JavaScript, you can choose the right strategy – whether it’s embracing TypeScript files, mastering JSDoc annotations, or a combination of both. Embrace these techniques, and you’ll not only resolve the immediate error but also elevate your code’s reliability and maintainability. Ready to take your JavaScript and TypeScript skills to the next level? Start experimenting with these solutions today, and discover the power of type-safe JavaScript! Consider exploring more advanced TypeScript concepts like conditional types and mapped types to further enhance your coding capabilities. Question & Answer :
I am starting to use TypeScript in a Node project I am working on in Visual Studio Code. I wanted to follow the “opt-in” strategy, similar to Flow. Therefore I put // @ts-check at the top of my .js file in hope to enable TS for that file. Ultimately I want the same experience of “linting” as Flow, therefore I installed the plugin TSLint so I could see Intellisense warnings/errors.

But with my file looking like:

// @ts-check module.exports = { someMethod: (param: string): string => { return param; }, }; 

and my tsconfig.json file looking like…

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

I get this error: [js] 'types' can only be used in a .ts file. as shown below in the image.

I saw this question which recommended disabling javascript validation in vscode but then that doesn’t show me any TypeScript Intellisense info.

I tried setting tslint.jsEnable to true in my vscode settings as mentioned in the TSLint extension docs but no luck there.

What is the correct setup in order to use .js files with TypeScript and get Intellisense so I know what the errors in my code are before I run any TS commands?

I’m using flow with vscode but had the same problem. I solved it with these steps:

1. Install the extension Flow Language Support

2. Disable the built-in TypeScript extension:

   1. Go to Extensions tab
   2. Search for @builtin TypeScript and JavaScript Language Features
   3. Click on Disable