How Can I Define My TypeScript Variables with Type Aliases and Interfaces Within In Declaration Files In The Project?

Question

Suppose the following folder/directory structure below.

[src: App]
  |
 + tsconfig.json
 + [@types]
      |
      + index.d.ts   (collection of type aliases and interfaces for App)
 + AppSharedCode.ts   (code commonly used by the *.ts files in subdirectories)
 + [ThingCreator]
      |
      + ThingCreator.ts
      + tsconfig.ts
 + [ThingUser]
      |
      + ThingUser.ts
      + tsconfig.ts

[Lib]
  |
  + tsconfig.json
  + [@types]
     |
     + index.d.ts  (collection of type aliases and interfaces for Lib)
  + [src]
     |
     + myLib.ts (actually its several *.ts files, but this should suffice)

Only *.ts, *.d.ts, and tsconfig.json files are shown (*.aspx, *.css, *.html others omitted). The project contains two web app components of something that creates a thing (the thing is a meeting agenda) and then another which uses the thing (the created meeting agenda). This was necessary to separate the main *.ts into subdirectories with their own tsconfig.json files because the VS Code IDE found names/functions in conflict, and this was the solution. There are four tsconfig files total.

I put some informative info in parentheses within that directory structure. The @types folder with index.d.ts file naming was thought to fix my difficulty in understanding TypeScript use in VS Code as I re-code JS projects to TS, so that nomenclature was used. It didn't help.

My *.ts files can type the variables representing HTML DOM elements without having to use import statements of the DOM library declarations lib.dom.d.ts.

    let taElem: HTMLTextAreaElement;

Suppose my index.d.ts file under the App src/@types contains the following:

    declare module "AgendaTypes" {
        interface IAgendaItem {
            headline: string;
            children: IAgendaItem[];
            meetingNote: string;
        }
    }

and my AppShareCode.ts file:

    import AgendaTypes from "AgendaTypes";

In order to utilize IAgendaItem within the ts source, I have to use dot notation. I suppose that would be true especially if I made declarations a namespace (?).

    let anItem: AgendaTypes.IAgendaItem;

Questions:

1. What is proper way to declare/export type aliases/interfaces in declaration files? I have looked at *node_modules/@types .d.ts files and the lib.dom.d.ts to get an idea, but there is no discernable pattern. Can all the interface and type alias definitions be wrapped in braces that make them visible to the entire project for the compiler? The goal is to use the type alias | interface name should be used directly without dot notation for namespaces or "module" just like HTMLTextAreaElement is used without dot notation for the library.
2. On the *.ts source file side, what is the proper way to make the sources see the names of type aliases, interfaces? Is there a tsconfig setting, or must it be import statement. This is between files in the App and in the Lib sources.
3. Global variables are included in this project. They are DEFINED often in source files where they are initialized or mostly used, although referenced by other *.ts files. Should I collect them in a single *.ts file? Or should they be collected and defined and declared with type aliases and interfaces in the *.d.ts file?

And I have been entirely unable to import the Lib code. I have composite set true on all tsconfig files and the root tsconfig file has references set to the paths of the other three tsconfig files.

I am just learning TypeScript and involved in an extensive re-coding effort of all JavaScript projects built over the years. I should have learned this a few years ago because I very much appreciate the discipline TS puts on JS now.

Another note: I had a TL;DR version of this post that I scrapped and revised...believe it or not.

There were many similarly related posts that had only comments or were answered without the poster designating them as answered. The one answered somewhat close:

Answered Post in this forum

Answer 1

I don't really understand your folder structure, nor the multitude of tsconfig.json files littering your project. If this is a refactoring, then I recommend you rethink what you are really trying to accomplish. Most projects require at most two tsconfig.json files and the majority of projects do not put a tsconfig config file inside the source (src) folder.

Nevertheless, your questions seem to focus more on typescript, so let me try to answer those.

What is proper way to declare/export type aliases/interfaces in declaration files? I have looked at *node_modules/@types .d.ts files and the lib.dom.d.ts to get an idea, but there is no discernable pattern. Can all the interface and type alias definitions be wrapped in braces that make them visible to the entire project for the compiler? The goal is to use the type alias | interface name should be used directly without dot notation for namespaces or "module" just like HTMLTextAreaElement is used without dot notation for the library.

Simply make sure that Typescript can see your *.d.ts file (i.e. it is part of your included files or visible from typeroots) and it should be no problem to declare the types globally. You also won't need to import them, nor can you, unless you put them in a *.ts file.

On the *.ts source file side, what is the proper way to make the sources see the names of type aliases, interfaces? Is there a tsconfig setting, or must it be import statement. This is between files in the App and in the Lib sources.

Just the same way you handle the declaration files: Simply make sure they are all included in the tsconfig.json corresponding to the folder you are interested in.

Global variables are included in this project. They are DEFINED often in source files where they are initialized or mostly used, although referenced by other *.ts files. Should I collect them in a single *.ts file? Or should they be collected and defined and declared with type aliases and interfaces in the *.d.ts file?

This depends on your preference, but most projects will usually have a constants.ts file somewhere in the source folder, and everything just imports the constants from those files.

Note: You cannot declare constants in declaration files, because like I said above, you cannot import things from declaration files.