In TypeScript v2.2.2, how do you create a definition file for a Javascript library that doesn't have a tsd?
I'm looking for a complete example, or at least best practices for creating a definition file (optional, must be a tsd) for a JavaScript library that doesn't have one in @types or is bundled.
So far I've managed to put together a basic solution here , but it doesn't seem to follow the exact directions in the Definitions section of the TypeScript website.
In the repository above, I am using a package @google-cloud/datastore
which from what I know does not yet have a tsd file. The documentation is good enough that I can create a description file manually for the parts of interest, but I am having a hard time figuring out what is best for exporting definitions like this manually.
Specifically from here , it says:
/*~ This is the module template file for class modules.
*~ You should rename it to index.d.ts and place it in a folder with the same name as the module.
*~ For example, if you were writing a file for "super-greeter", this
*~ file should be 'super-greeter/index.d.ts'
*/
/*~ Note that ES6 modules cannot directly export class objects.
*~ This file should be imported using the CommonJS-style:
*~ import x = require('someLibrary');
*~
*~ Refer to the documentation to understand common
*~ workarounds for this limitation of ES6 modules.
*/
/*~ If this module is a UMD module that exposes a global variable 'myClassLib' when
*~ loaded outside a module loader environment, declare that global here.
*~ Otherwise, delete this declaration.
*/
From the instructions above, it sounds like I should leave a file index.d.ts
in a folder outside of my directory node_modules/@types
that mimics the same folder structure as my module. For example, in my repository, I have a top-level directory @google-cloud/datastore
that contains an index.ts file, but from the documentation it sounds like I should be using the index.d.ts file; however my modules and compiler can't find it. Do I need a compiler option for this?
Secondly, this is the correct approach I have taken in the repository. This method is not documented on their website and I should have guessed it before proceeding with the solution. I am essentially importing a JavaScript bundle google-cloud/datastore
into index.ts, adding my typings, and then exporting it for my modules to use. However, my modules have to reference the package to ./@google-cloud/datastore
, since that is the actual location of the TypeScript definitions.
Long story short, in TypeScript v2.2.2, what's the best way to create small local TypeScript files for JavaScript libraries that don't contain a tsd?
Aftermath
I have updated my repository with the solution suggested by Alex and everything works as expected. I would like to point out that this seems to work as well by simply adding a parameter { "baseUrl": "types" }
, but I was not clear why that would be the right thing to do, so I went with the suggested approach. The flag is --traceResolution
very useful for this.
In this example, I also included another module with a TypeScript definition lodash
to make sure the normal module resolution is still correct.
My directory / file structure:
+ js
...
+ node_modules
+ @google-cloud
+ datastore
+ lodash
+ @types
+ lodash
+ ...
+ types
+ @google-cloud
- index.d.ts
+ datastore
- index.d.ts
- index.ts
- package.json
- tsconfig.json
Trace resolution
Just for the curious, I want to post an example of wrong / correct result when called tsc --traceResolution
. I have abbreviated the results for clarity.
Invalid without a paths
TypeScript parameter resolves @google-cloud/datastore
to a file index.js
, which is incorrect.
======== Module name '@google-cloud/datastore' was successfully resolved to 'C:/Users/Kory/Documents/Repos/playground/manual-typescript-definition/node_modules/@google-cloud/datastore/src/index.js'. ========
Correct with parameter paths
. Note that it @google-cloud/datastore
allows a file index.d.ts
, not a JavaScript file.
======== Module name '@google-cloud/datastore' was successfully resolved to 'C:/Users/Kory/Documents/Repos/playground/manual-typescript-definition/types/@google-cloud/datastore/index.d.ts'. ========
source to share
You can use compilerOptions paths
and typeRoots
to get tsc
custom file detection .d.ts
. It will search the listed directories for the folders that match your package (i.e. @google-cloud/datastore
)
for example
"paths": {
"*": [
"types/*"
]
},
"typeRoots": [
"./types"
]
Where types
is the folder at the root of your directory structure and you create the filetypes/@google-cloud/datastore/index.d.ts
You can use tsc --traceResolution
as a quick way to see what files / folders are tsc
being considered when looking for type definitions
source to share