Creating custom Typescript types for my code in a separate directory

Question

Creating custom Typescript types for my code in a separate directory

My goal is to develop a library that automatically generates Typescript types for user code. I'd prefer to keep these type definitions in a separate folder for organizational purposes, while still allowing IDEs to recognize them.

While it's feasible with Typescript modules, I've been unable to figure out how to define types for an "ambient" module. Here's a simplified example of the desired file structure:

// src/pages/WelcomePage.ts
export const message = 'hi'

// src/index.ts
import { message } from './pages/WelcomePage'
console.log(message) // message should be of type "Message", not "string".

// types/pages/WelcomePage.d.ts
// This approach does not work.
// Is there a way to make it work?
declare module "pages/WelcomePage" {
    type Message = string
    export const message: Message
}

tldr: I want all my generated types to reside in types/... and define types for src/....

typescript

Answer 1

Answer №1

By incorporating path aliases along with the guidance from this answer on Stack Overflow, I was able to successfully get it up and running:

My approach involved utilizing the "transformers" variant from the aforementioned answer, alongside using @ as an alias for the src directory:

// src/pages/WelcomePage.ts
export const message = "aaa";

// src/index.ts
import { message } from "@/pages/WelcomePage"
console.log(message)

// types/pages/WelcomePage.d.ts
declare module "@/pages/WelcomePage" {
    type Message = string
    export const message: Message
}

Additionally, here is the setup for the project: tsconfig.json

{
    "compilerOptions": {
        "module": "CommonJS",
        "moduleResolution": "Node",
        "outDir": "./dist",
        "baseUrl": ".",
        "paths": {
            "@/*": ["src/*"]
        },
        "plugins": [
            {
                "transform": "@zerollup/ts-transform-paths"
                "exclude": ["*"]
            }
        ]
    },
    "include": ["./types/**/*", "./src/**/*"]
}

package.json

{
    "scripts": {
        "build": "ttsc -p ."
    },
    "devDependencies": {
        "@zerollup/ts-transform-paths": "^1.7.18",
        "ttypescript": "^1.5.13",
        "typescript": "~4.4.0"
    }
}

How does this method work? Firstly, the declaration files are included which results in the declaration of the @/pages/WelcomePage module. This declaration is then utilized by TypeScript for verification during import within index.ts.

During the compilation process, the ts-transform-paths is executed and modifies the path @/pages/WelcomePage to the resolved

./pages/WelcomePage</code) ensuring that the final code functions correctly.</p>
<p>However, a downside of this solution is that there is no validation if <code>src/pages/WelcomePage.ts

actually exports what types/pages/WelcomePage.d.ts specifies.

Answer 2

By incorporating path aliases along with the guidance from this answer on Stack Overflow, I was able to successfully get it up and running:

My approach involved utilizing the "transformers" variant from the aforementioned answer, alongside using @ as an alias for the src directory:

// src/pages/WelcomePage.ts
export const message = "aaa";

// src/index.ts
import { message } from "@/pages/WelcomePage"
console.log(message)

// types/pages/WelcomePage.d.ts
declare module "@/pages/WelcomePage" {
    type Message = string
    export const message: Message
}

Additionally, here is the setup for the project: tsconfig.json

{
    "compilerOptions": {
        "module": "CommonJS",
        "moduleResolution": "Node",
        "outDir": "./dist",
        "baseUrl": ".",
        "paths": {
            "@/*": ["src/*"]
        },
        "plugins": [
            {
                "transform": "@zerollup/ts-transform-paths"
                "exclude": ["*"]
            }
        ]
    },
    "include": ["./types/**/*", "./src/**/*"]
}

package.json

{
    "scripts": {
        "build": "ttsc -p ."
    },
    "devDependencies": {
        "@zerollup/ts-transform-paths": "^1.7.18",
        "ttypescript": "^1.5.13",
        "typescript": "~4.4.0"
    }
}

How does this method work? Firstly, the declaration files are included which results in the declaration of the @/pages/WelcomePage module. This declaration is then utilized by TypeScript for verification during import within index.ts.

During the compilation process, the ts-transform-paths is executed and modifies the path @/pages/WelcomePage to the resolved

./pages/WelcomePage</code) ensuring that the final code functions correctly.</p>
<p>However, a downside of this solution is that there is no validation if <code>src/pages/WelcomePage.ts

actually exports what types/pages/WelcomePage.d.ts specifies.

Answer 3

Answer №2

It appears that a custom tsconfig and npm command could potentially solve the issue at hand, assuming I have grasped the question correctly. The tsconfig file can define input/output directories and specify that only declaration files should be generated:

// tsconfig.special.json:

{
    "compilerOptions": {
        "compiler_options": "go_here",
        "emitDeclarationOnly": true, // will only emit .d.ts files
        "outDir": "types"
    },
    "include": ["src/**/*.ts"],
    "exclude": ["node_modules"]
}

This configuration instructs TypeScript to compile all .ts files within the src directory into .d.ts files exclusively, which will be stored in the types directory.

Your npm command within the "scripts" section might resemble the following:

"compile": "tsc --p tsconfig.special.json"

As you mentioned this is intended for a library to be installed by other developers, they will need to create their own npm script to execute this one. Instructions on how to achieve this are available here: How do I run an npm script of a dependent package.

To ensure that TypeScript reads from the correct src folder (i.e., user_project/src instead of

user_project/node_modules/your_library/src

) and outputs to the proper directory (e.g., user_project/types rather than

user_project/node_modules/your_library/types

), adjustments may need to be made to the tsconfig file and npm command. Feel free to ask for further details if needed. Additionally, users implementing your library must include the generated /types directory in their project's tsconfig.json to ensure proper detection of the generated .d.ts files.

I hope this guidance aligns with the help you seek.

Answer 4

It appears that a custom tsconfig and npm command could potentially solve the issue at hand, assuming I have grasped the question correctly. The tsconfig file can define input/output directories and specify that only declaration files should be generated:

// tsconfig.special.json:

{
    "compilerOptions": {
        "compiler_options": "go_here",
        "emitDeclarationOnly": true, // will only emit .d.ts files
        "outDir": "types"
    },
    "include": ["src/**/*.ts"],
    "exclude": ["node_modules"]
}

This configuration instructs TypeScript to compile all .ts files within the src directory into .d.ts files exclusively, which will be stored in the types directory.

Your npm command within the "scripts" section might resemble the following:

"compile": "tsc --p tsconfig.special.json"

As you mentioned this is intended for a library to be installed by other developers, they will need to create their own npm script to execute this one. Instructions on how to achieve this are available here: How do I run an npm script of a dependent package.

To ensure that TypeScript reads from the correct src folder (i.e., user_project/src instead of

user_project/node_modules/your_library/src

) and outputs to the proper directory (e.g., user_project/types rather than

user_project/node_modules/your_library/types

), adjustments may need to be made to the tsconfig file and npm command. Feel free to ask for further details if needed. Additionally, users implementing your library must include the generated /types directory in their project's tsconfig.json to ensure proper detection of the generated .d.ts files.

I hope this guidance aligns with the help you seek.

Creating custom Typescript types for my code in a separate directory

Answer №1

Answer №2

Similar questions

Tips for transferring errors from effects to actions within NGRX

Exploring Computed Properties in Angular Models

Attribute specified does not belong to type 'DetailedHTMLProps<ButtonHTMLAttributes

Unable to locate the 'typescript' module at <Path>. However, the tsc -v command displays logs

Error encountered with default theme styling in Material-UI React TypeScript components

Implementing React with CSS styling is a popular way to provide

Encountering errors when examining local variables during unit testing on an Angular component

How to convert typescript path aliases into relative paths for NPM deployment?

How to specify in TypeScript that if one key is present, another key must also be present, without redundantly reproducing the entire structure

Accessing data from an object of type Request in NodeJS using Typescript

Steer clear of using Typescript to exclude certain sections of code from compilation

Can we destruct and type the properties of a function parameter object that are already known?

Using React-Bootstrap with TypeScript in your project

Is it possible to establish a default or recommend a specific folder arrangement when conducting a direct download without the need for a zip file?

The NestJS framework encountered an error due to a method being undefined in the

I've encountered an issue where my React website functions correctly on the development server but not on the live website. Where should I start investigating to find the cause of this discrepancy?

The custom native date adapter is facing compatibility issues following the upgrade of Angular/Material from version 5 to 6

The error message thrown is: "Unable to assign value to property 'formGroup' as it is not defined

What causes arrays to unexpectedly change in Angular?

Developing a function that determines its return type based on the presence of an optional parameter