Importing files and libraries in TypeSpec
Imports are used to include files or libraries into your TypeSpec program. When compiling a TypeSpec file, you specify the path to your root TypeSpec file, typically named "main.tsp". From this root file, any imported files are added to your program. If a directory is imported, TypeSpec will search for a main.tsp
file within that directory.
The path specified in the import must either start with "./"
or "../"
, or be an absolute path. The path should either point to a directory, or have an extension of either ".tsp" or ".js". The examples below illustrate how to use imports to assemble a TypeSpec program from multiple files:
Importing a TypeSpec file
import "./models/foo.tsp";
Importing a JavaScript file
import "./decorators.js";
Importing a library
The import value can be the name of one of the package dependencies.
import "/rest";
// ./node_modules/@typespec/rest/package.json
{
"exports": {
".": { "typespec": "./lib/main.tsp" }
}
}
This results in ./node_modules/@typespec/rest/lib/main.tsp
being imported.
Package resolution algorithm
When trying to import a package TypeSpec follows the following logic
- Parse the package name from the import specificier into
pkgName
andsubPath
(e.g.@scope/lib/named
=> pkgName:@scope/lib
subpath:named
) - Look to see if
pkgName
is itself(Containing package) - Otherwise lookup for a parent folder with a
node_modules/${pkgName}
sub folder - Reading the
package.json
of the package a. Ifexports
is defined respect the ESM logic to resolve thetypespec
condition(TypeSpec will not respect thedefault
condition) b. Ifexports
is not found or for back compat the.
export is missing thetypespec
condition fallback to checkingtspMain
ormain
Importing a directory
If the import value is a directory, TypeSpec will check if that directory is a Node package and follow the npm package lookup logic, or if the directory contains a main.tsp
file.
import "./models"; // equivalent to `import "./models/main.tsp";
import "./path/to/local/module"; // Assuming this path is a TypeSpec package, it will load it using the tspMain file.