Tag: node_modules

JSDoc difficulties when referencing from npm package.

I have been satisfied with JSDoc for typing over full TypeScript for a while due to being able to do pretty much anything TypeScript can do. Especially when importing from a .ts file is also possible.

However, the following issue around referencing and building types from npm packages has become too much of an issue and waste of time to work around that I can only recommend full TypeScript at this point.

I have included the AI conversation I had to try and resolve this, but the solution in the end is really to just use TypeScript instead.

When I try to use JSDoc types from a file in a library I installed locally via npm, it does not work(in VSCode). Is there no way to get this working?

I’m here to help you get those JSDoc types working in VS Code!

Here are the approaches you can take:

1. Check for Type Declaration Files (.d.ts):

  • If the library includes .d.ts files, VS Code should automatically recognize the types.
  • If not, proceed to the next steps.

2. Generate Type Declaration Files:

  • If the library doesn’t have .d.ts files, you can generate them:
    • Use tools like dts-gen or api-extractor to create them from the library’s source code or JSDoc comments.

3. Reference Types Directly:

  • If you know the specific types you need, reference them directly in your code:

    JavaScript
    /**
 * @param {LibraryName.Type} param - Description of the parameter
 */
function myFunction(param) {
    // ...
}

4. Manually Create a Declaration File:

  • If the above options aren’t feasible, create a .d.ts file manually:

    TypeScript
    declare module 'library-name' {
    // Define the types here
}

5. Configure VS Code:

  • Check JSDoc support: Ensure “JavaScript and TypeScript: Use JSDoc for IntelliSense” is enabled in VS Code settings.

  • Include additional type roots: If the library types are outside your project, add the path to jsconfig.json or tsconfig.json:

    JSON
    {
    "compilerOptions": {
        "typeRoots": ["./node_modules/@types", "./path/to/library/types"]
    }
}

Additional Troubleshooting:

  • Check for syntax errors: Make sure your JSDoc comments are correct.
  • Restart VS Code: Sometimes a restart fixes type recognition issues.
  • Update extensions: Keep VS Code and related extensions updated.

If you continue to face issues, please provide more details about:

  • The specific library you’re using
  • Your project setup
  • Any error messages you’re encountering

I’ll offer more tailored guidance based on the specific context.

know I can convert to ts, but what about when keeping as JSDoc?

While TypeScript offers superior type safety and integration with VS Code, there are ways to use JSDoc for type definitions in your project even if you prefer to remain in JavaScript:

1. Consider the Approaches Mentioned Previously:

  • Check for existing type declaration files: If the library provides them, VS Code should recognize the types automatically.
  • Manually create a type declaration file: This method requires writing a separate .d.ts file to define the types for the library (explained earlier).
  • Reference types directly: If you know the specific types you need, reference them directly in your code using JSDoc annotations (also explained previously).

2. Ensure JSDoc Support in VS Code:

  • Go to Settings (or Preferences on macOS) and search for “JavaScript and TypeScript: Use JSDoc for IntelliSense.” Make sure it’s checked.
  • This enables VS Code to use JSDoc comments for type information.

3. Address Limitations:

  • Limited IntelliSense: Compared to TypeScript, JSDoc offers less comprehensive IntelliSense. You might encounter scenarios where the code completion or type checking is less robust.
  • Manual Maintenance: Manually maintaining JSDoc comments and ensuring their accuracy can be more work compared to the type checking offered by TypeScript.

In conclusion, while using JSDoc is still an option for type definitions in JavaScript projects, it’s important to be aware of its limitations and potential drawbacks compared to TypeScript. Consider these factors when deciding which approach best suits your project needs and preferences.

It seems VSCode settings do not help and that I need to generate .d.ts files. How can I generate .d.ts file into the library in node_modules.

It’s important to understand that modifying files directly within node_modules is generally not recommended. This directory is managed by npm and changes made to it could be overwritten during future package updates.

Instead, consider the following approaches for generating type declarations without modifying the library in node_modules:

1. Use a Dedicated Folder:

  • Create a separate folder within your project, for example, typings.

  • Use a tool like dts-gen or api-extractor to generate the .d.ts files in this folder.

  • Configure your project (e.g., in tsconfig.json) to include this folder as a source for type definitions:

    JSON
    {
    "compilerOptions": {
        "typeRoots": ["./typings", "./node_modules/@types"]
    }
}

2. Use a Global Typings Repository:

  • Check if the library already has type definitions available in a global repository like @types.

  • If so, install the corresponding package:

    Bash
    npm install --save-dev @types/library-name

3. Create a Local Declaration File:

  • Create a .d.ts file within your project and define the types for the library manually.
  • While this approach offers more control, it requires maintaining the type definitions yourself and ensuring they stay in sync with the library.

Remember:

  • Choose the method that best suits your project needs and maintenance preferences.
  • Avoid modifying files directly within node_modules to prevent potential issues.
  • If you decide to create local declarations, consider using a versioning system to track changes.

I am trying to use tsc in the cli on files in node_modules. Are files in node_modules excluded by default? What should I do?

I am trying to use tsc in the cli on files in node_modules. Are files in node_modules excluded by default? What should I do?

Yes, files in the node_modules directory are excluded by default when using the tsc compiler in the CLI. This is because the node_modules folder typically contains third-party libraries written in JavaScript, which don’t require type checking by the TypeScript compiler.

Here are your options to include files from node_modules:

1. Not Recommended:

  • Directly including node_modules: While technically possible to include the entire node_modules directory in your compilation, it’s strongly discouraged. This can significantly slow down compilation due to the large number of files and potential conflicts with your own project’s code.

2. Recommended approach:

  • Use type definitions: Most popular libraries in node_modules have corresponding type definition packages available on npm (https://www.npmjs.com/). These packages usually start with the @types prefix, followed by the library name (e.g., @types/express). Install the relevant type definition package using npm install @types/<library-name>. This provides type information for the library without including the actual source code.

3. Specific file inclusion (for rare cases):

  • In rare cases, you might need to include specific files from node_modules. While not ideal, you can achieve this by using the --include flag with tsc. However, this should be used with caution, as it can potentially introduce conflicts and dependencies on the external library’s implementation details.

Remember, the best practice is to leverage type definitions whenever possible. They provide type information without unnecessary compilation overhead and maintain a clear separation between your project code and external libraries.

For the command I am using there is little reason to have excluded directories, how can I remove all excluded directories from the settings in tsc cli? No tsconfig.json please.

While you can’t directly remove excluded directories from the CLI, you can achieve a similar effect using the --noResolve flag.

Here’s how to compile a file without any exclusion logic:

Bash
tsc --noResolve your_file.ts

Key points:

  • --noResolve tells the compiler to not perform module resolution, meaning it won’t consider any exclusion patterns or include directives.
  • It’ll only compile the specified file(s) directly.
  • It’s crucial to note that --noResolve has broader implications:
    • No module resolution: References to other modules won’t be resolved, potentially leading to errors if your code depends on external modules.
    • No type checking from included files: Type information from other files won’t be considered, potentially affecting type checking accuracy.

To include specific files:

  • If you need to include files from excluded directories like node_modules, use the --include flag:
Bash
tsc --noResolve --include node_modules/some-library/file.ts your_file.ts

Best practices:

  • Use --noResolve judiciously, as it can bypass intended project structure and type checking.
  • For most scenarios, creating a tsconfig.json file with appropriate include and exclude sections is recommended for better control and maintainability.