Imports in .d.ts files break wildcard modules declarations

[zuzusik]

TypeScript Version: 3.1.3

Search Terms:

import d.ts wildcard module

Code

main.ts

/// <reference path="./typings.d.ts" />

import template from './template.html';

typings.d.ts

import * as _angular from 'angular';

declare module '*.html' {
  const content : string;
  export default content;
}

{
  "name": "ts-bug",
  "version": "1.0.0",
  "dependencies": {
    "angular": "^1.7.5"
  }
}

Compile with:

tsc main.ts

Expected behavior:

Compiled without errors.

Actual behavior:
Compiled with error

main.ts:3:22 - error TS2307: Cannot find module './template.html'.

3 import template from './template.html';
                       ~~~~~~~~~~~~~~~~~

Removing import * as _angular from 'angular'; fixes the issue.

Side Note 1

Regular module declarations work regardless of imports being present.

Side Note 2
import * as _angular from 'angular'; is needed to later do:

declare global {
  const angular : typeof _angular;
}

to workaround #10178

[weswigham]

An import makes a file a module, which consequently makes the module statement a module augmentation and not a module declaration. A module augmentation differs in that it only adds to existing modules in the compilation. Maybe we could issue a more useful error (or related span) here? Like "a module augmentation exists which matches this import, however no module file or declaration does"?

[Istar-Eldritch]

I've faced this issue before. It would really help for beginners writing their first modules having a good error message like the one you propose @weswigham.

I'm happy to work on this if no one else is doing it already.

[cloverich]

A module augmentation differs in that it only adds to existing modules in the compilation.

I wonder if it could be an error to augment a module that does not exist, if the compilation (apparently) cannot use the augmented file?

[ghost]

Helped me greatly.
I tried to import signalR as an ambient variable and this worked.

import  * as _signalR from "./signalr/index";

declare global {
    const signalR: typeof _signalR;
}

[EddyVinck]

Maybe offtopic but... I came across this thread when I was looking for a way to import all files in a directory that ended with .png or .jpg. I need to do this because Parcel.js hashes the filenames in my builds so I cannot know the exact path of a file before compilation.

Someone recommended that I could use wildcard modules for this, but I don't think that is the case.

This is how I fixed my issue:

Before converting my project to typescript, I had this line:

import imageUrls from "../../img/*.*";

I was kind of disappointed that this did no longer work.

I replaced it with this:

const imageUrls = require("../../img/*.*");

and then I installed @types/node because TypeScript doesn't know what require does by default. I then included it in my tsconfig.json

{
  "compilerOptions": {
    "lib": ["es2017", "dom"],
    "allowSyntheticDefaultImports": true
  },
  "typeRoots": ["./node_modules/@types", "./js/types"],
  "include": ["js"],
  "exclude": ["node_modules"]
}

I hope this helps someone who might run into a similar issue.

If there is a way to do this with a wildcard module I would love to know, though. I'm new to TypeScript.

[benmosher]

Not sure if this helps others but I was just trying to import to get a type from a dependency, and stumbled into this clearer but not-obvious (to me anyway) alternative. Apparently you can import within the module declarations themselves and this compiles the same (AFAICT) as no-imports declarations. Not sure if this satisfies OP's desired outcome but this does what I was looking for:

/**
 * GraphQL query files.
 */
declare module "*.gql" {
  // import is tucked into (and scoped only within?) the module declaration
  import { gql } from 'graphql-tag'
  // currently `any` but could be well-defined in a future graphql-tag release
  const doc: ReturnType<typeof gql>
  export = doc
}

[meyer]

@weswigham sorry to ping this ancient thread. A coworker of mine just encountered this same issue, and I’ve personally helped quite a few people debug their d.ts files only to find that it’s this very issue. For people who are new to TypeScript it can be quite a frustrating pitfall.

I see this issue is in the backlog—is there anything that needs to be done to boost its visibility/priority a bit? Some sort of warning here would really go a long way to help folks debug mysterious typing issues.

[weswigham]

It's tagged Help Wanted - we're open to anyone opening a PR with an error like the one I described here to help clarify the situation.

[meyer]

@weswigham rad, thank you 🙏

[cecilemuller]

If someone stumbles on this thread from search, you can also use import():

declare type MyType = {
  myproperty: (param: import("example-library").ExampleType) => any;
};

See https://devblogs.microsoft.com/typescript/announcing-typescript-2-9-2/#import-types

[nettybun]

This is a huge pitfall and causes a lot of headaches, especially since benmosher's code above works (#28097 (comment)) but only because the module they're declaring isn't the same as the module being imported. Wanting to extend the same module doesn't work:

// (as an example: converting a named export to a default export)
declare module '@x/y/z' {
  import type { DataSource } from '@x/y/z'
  export default DataSource
}

The above will make any TS files who import DataSource from '@x/y/z'; to have any type. It's any because it's referring to itself. The original type in your node_modules is lost...

Somehow this doesn't happen when the import statement is outside/before the "declare module", but then you can't have other declarations in that file. It's...yeah. Lots of trial and error 😅

[djfm]

Holy cow that's true, I had been trying to debug why my .d.ts file wasn't picked up for over an hour, thanks :)

[XieJiSS]

Gently pinging - is there any plan to fix this in typescript 5.0? Thanks!