Tag: typescript

Why do I need a TypeScript declaration file for a JavaScript library even though type checking works in VSCode in own library?

The following is an AI chat conversation regarding the topic stated in the title.
Depending on the quality of the conversation, modifications may have been made. Modifications may or may not be stated in this page.

Why do I need to generate a declaration file for a javascript library in order to get type hinting in VSCode when I use that library in another project? VSCode can already get types of JS file in the same project. So why does this change when importing from an external library?

Here’s a breakdown of why declaration files are required for type hinting in VSCode when using external JavaScript libraries:

1. JavaScript’s Dynamic Nature:

  • JavaScript is dynamically typed, meaning type information isn’t explicitly included in the code itself. This flexibility makes it harder for editors to infer types accurately, especially for external code.

2. VSCode’s Type Hinting Reliance:

  • VSCode heavily relies on type information for features like:
    • IntelliSense (code completion, suggestions)
    • Hover information
    • Parameter and type checking
    • Refactoring tools

3. Separate Project Scope:

  • When a library is in a separate project, VSCode can’t directly analyze its source code to infer types. Declaration files (.d.ts) bridge this gap.

4. Declaration Files:

  • They describe the types of variables, functions, and classes within a library.
  • They’re written in TypeScript, a superset of JavaScript with explicit typing.
  • VSCode can leverage them for type hinting even in JavaScript projects.

5. Type Acquisition Methods:

  • Automatic: VSCode tries to automatically fetch declaration files for popular libraries.
  • Manual: Install declaration files from DefinitelyTyped (a community repository): npm install --save-dev @types/<library-name>
  • Generating: Compile a library’s TypeScript source code or use tools to create .d.ts files from JSDoc comments.

Key Points:

  • Declaration files are essential for type-aware features in VSCode when using external JavaScript libraries.
  • They make your code more readable, maintainable, and less prone to type-related errors.
  • Consider using TypeScript for new projects to enjoy strong typing and type safety from the start.

Should I include code I want typed but not published in tsconfig.json ?

The following is an AI chat conversation regarding the topic stated in the title.
Depending on the quality of the conversation, modifications may have been made. Modifications may or may not be stated in this page.

Should I include code in my tsconfig.json file in “includes” if I want it to be typed, but it is not code for the actual delivered product? For example, if it is build code that I want to be typed.

Whether to include build code in the “includes” list of your tsconfig.json file depends on a few factors:

1. Type Checking and Build Process:

  • If you want type checking and language features for build code during development, include it.
  • If the code is executed as part of the build process (e.g., custom webpack plugins), include it for accurate type checking during build.

2. Performance and Build Size:

  • If type checking build code is unnecessary or impacts performance negatively, exclude it.
  • If including a large amount of build code unnecessarily increases the built JavaScript output, exclude it.

3. Organization and Clarity:

  • If inclusion makes project structure clearer and tooling easier to set up, include it.
  • If exclusion better organizes code for separation of concerns, exclude it.

Best Practices:

  • Separate build code into a dedicated directory for organization and clarity.
  • Use a separate tsconfig.json file specifically for build code, ensuring appropriate configurations without affecting main code.
  • Consider “files” property for explicit file lists instead of “include” for fine-grained control and clarity.

Example tsconfig.json for build code:

JSON
{
  "compilerOptions": {
    // Options tailored for build code
  },
  "include": ["build/**/*.ts"]
}

Recommendations:

  • If build code benefits from type checking or is part of the build process, include it.
  • If performance, build size, or code separation are primary concerns, exclude it.
  • Prioritize clarity, organization, and tooling convenience for effective development.

I want the build code to be included in type checking in VSCode. Would any parent tsconfig.json be detected? Must it be called tsconfig.json?

Here’s how parent tsconfig.json files and type checking in VS Code work:

1. Inheritance:

  • VS Code automatically detects and uses parent tsconfig.json files within the same workspace folder.
  • It merges configurations from parent files, allowing for shared settings and overrides in child files.

2. File Searching:

  • VS Code searches for tsconfig.json files in the following order:
    1. Current workspace folder
    2. Parent workspace folders (recursively)
    3. User-specified path (using the “typescript.tsconfig.autoDetect” setting)

3. File Name:

  • Yes, the file must be named tsconfig.json. VS Code specifically looks for this file name.

Recommendations for VS Code:

  • Position tsconfig.json files strategically: Place them in relevant workspace folders for desired inheritance and configuration sharing.
  • Consider separate files for build code: Isolate build-related configurations for better organization and tailored type checking.
  • Manually specify a parent tsconfig.json: If necessary, use the “typescript.tsconfig.autoDetect” setting to direct VS Code to a specific parent file.

Additional Tips:

  • Use the “extends” property: Explicitly reference a parent tsconfig.json for clarity and maintainability, even within the same workspace folder.
  • Customize workspace settings: Adjust VS Code’s TypeScript settings for specific needs in your project (e.g., enabling or disabling automatic detection).

Example:

  • If you have a top-level tsconfig.json for shared settings and a separate tsconfig.build.json for build code within a nested ‘build’ folder, inheritance and automatic detection will typically work as expected in VS Code.

Research notes regarding converting JSDoc to TypeScript types

A lot of my JS code had been typed with JSDoc comments.
JSDoc comments are very useful for typing JavaScript code, and also have the benefit of allowing inline TypeScript types and importing TypeScript types from ts files. Types can be checked easily in modern editors such as VSCode. For example, the code below, imports from a ts file and types the variable.

/**
* @type {import('tsfile.ts').MyType}
*
const myVariable = 'abc';

It is also possible to declare the type using @typedef to reuse within the file.

/**
* @typedef {import('tsfile.ts').MyType} MyType
*

/*
* @type {MyType}
*/
const myVariable = 'abc';

However, one big issue with JSDoc is that importing it from external libraries seems to not work.
TypeScript types seem to be usable without any processing by just referencing the file such as:

/**
* @typedef {import('my-library'/ts-file-location.ts).MyType} MyType
*/

For JSDoc, generate type declaration files seems to be required.
This is fine, and is expected for JS projects, but it is an extra step that needs to be prepared for all JS projects.

Considering, TypeScript can be imported into JSDoc in the first place, there is really no reason to store type files using JSDoc. The solution is then to isolate types into type only files in ts, and then export each type. This makes it easy to import into JSDoc and into other projects without and processing.

Searching for solutions to convert JSDoc to TypeScript did take my down and long-winding road of issues, that seems to not have been worth the trouble. I have written any significant information in the notes below, but the solution is to just use tsc from TypeScript. See below.

TypeScript tsc

  • Seems to work best. Just need to add exports if necessary and extract from generated file(s).
# Update [SOURCE] below.
# tsc [SOURCE] --declaration --emitDeclarationOnly --allowJs
#
# Notes:
# -- outFile [BUNDLE_DESTINATION] // Works for only some code, so use optionally. https://www.typescriptlang.org/tsconfig/#outFile
# .d.ts file is created in same location with same name before extension.
# To create ts file with exports, SHOULD remove the ".d" part for declaration file, and replace each "type " with "export type ".
# MAY do the same for "interface", but seems like not used (maybe if specifically specified in JSDOC as interface?).
# To prevent replacing wrong code within comments/strings, etc., check that "type" starts at beginning of line.

Notes

ts-migrate

ts-fix

TypeScript codefixes

Other