@microsoft/api-extractor

property program

readonly program: {};

• The TypeScript compiler's Program object, which represents a complete scope of analysis.

method create

static create: (
    extractorConfig: ExtractorConfig,
    options?: ICompilerStateCreateOptions
) => CompilerState;

• Create a compiler state for use with the specified IExtractorInvokeOptions.

property packageName

static readonly packageName: string;

• Returns the package name of the API Extractor NPM package.

property version

static readonly version: string;

• Returns the version number of the API Extractor NPM package.

method invoke

static invoke: (
    extractorConfig: ExtractorConfig,
    options?: IExtractorInvokeOptions
) => ExtractorResult;

• Invoke API Extractor using an already prepared ExtractorConfig object.

method loadConfigAndInvoke

static loadConfigAndInvoke: (
    configFilePath: string,
    options?: IExtractorInvokeOptions
) => ExtractorResult;

• Load the api-extractor.json config file from the specified path, and then invoke API Extractor.

property alphaTrimmedFilePath

readonly alphaTrimmedFilePath: string;

• See documentation for IConfigDtsRollup.alphaTrimmedFilePath.

property apiJsonFilePath

readonly apiJsonFilePath: string;

• See documentation for IConfigDocModel.apiJsonFilePath.

property apiReportEnabled

readonly apiReportEnabled: boolean;

• See documentation for IConfigApiReport.enabled.

property apiReportIncludeForgottenExports

readonly apiReportIncludeForgottenExports: boolean;

• See documentation for IConfigApiReport.includeForgottenExports.

property betaTrimmedFilePath

readonly betaTrimmedFilePath: string;

• See documentation for IConfigDtsRollup.betaTrimmedFilePath.

property bundledPackages

readonly bundledPackages: string[];

• See documentation for IConfigFile.bundledPackages.

property docModelGenerationOptions

readonly docModelGenerationOptions: IApiModelGenerationOptions;

• If specified, the doc model is enabled and the specified options will be used.

  Modifiers

  • @beta

property docModelIncludeForgottenExports

readonly docModelIncludeForgottenExports: boolean;

• See documentation for IConfigDocModel.includeForgottenExports.

property enumMemberOrder

readonly enumMemberOrder: EnumMemberOrder;

• See documentation for IConfigFile.enumMemberOrder.

property FILENAME

static readonly FILENAME: string;

• The config file name "api-extractor.json".

property jsonSchema

static readonly jsonSchema: JsonSchema;

• The JSON Schema for API Extractor config file (api-extractor.schema.json).

property mainEntryPointFilePath

readonly mainEntryPointFilePath: string;

• See documentation for IConfigFile.mainEntryPointFilePath.

property messages

readonly messages: IExtractorMessagesConfig;

• See documentation for IConfigFile.messages.

property newlineKind

readonly newlineKind: NewlineKind;

• Specifies what type of newlines API Extractor should use when writing output files. By default, the output files will be written with Windows-style newlines.

property omitTrimmingComments

readonly omitTrimmingComments: boolean;

• See documentation for IConfigDtsRollup.omitTrimmingComments.

property overrideTsconfig

readonly overrideTsconfig: {};

• See documentation for IConfigCompiler.overrideTsconfig.

property packageFolder

readonly packageFolder: string;

• The absolute path of the folder containing the package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

property packageJson

readonly packageJson: any;

• The parsed package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

property projectFolder

readonly projectFolder: string;

• See documentation for IConfigFile.projectFolder.

property projectFolderUrl

readonly projectFolderUrl: string;

• See documentation for IConfigDocModel.projectFolderUrl.

property publicTrimmedFilePath

readonly publicTrimmedFilePath: string;

• See documentation for IConfigDtsRollup.publicTrimmedFilePath.

property reportConfigs

readonly reportConfigs: readonly IExtractorConfigApiReport[];

• List of configurations for report files to be generated.

  Remarks

  Derived from IConfigApiReport.reportFileName and IConfigApiReport.reportVariants.

property reportFilePath

readonly reportFilePath: string;

• Gets the file path for the "complete" (default) report configuration, if one was specified. Otherwise, returns an empty string.

  Deprecated

  Use ExtractorConfig.reportConfigs to access all report configurations.

property reportFolder

readonly reportFolder: string;

• See documentation for IConfigApiReport.reportFolder.

property reportTempFilePath

readonly reportTempFilePath: string;

• Gets the temp file path for the "complete" (default) report configuration, if one was specified. Otherwise, returns an empty string.

  Deprecated

  Use ExtractorConfig.reportConfigs to access all report configurations.

property reportTempFolder

readonly reportTempFolder: string;

• See documentation for IConfigApiReport.reportTempFolder.

property rollupEnabled

readonly rollupEnabled: boolean;

• See documentation for IConfigDtsRollup.enabled.

property skipLibCheck

readonly skipLibCheck: boolean;

• See documentation for IConfigCompiler.skipLibCheck.

property testMode

readonly testMode: boolean;

• See documentation for IConfigFile.testMode.

property tsconfigFilePath

readonly tsconfigFilePath: string;

• See documentation for IConfigCompiler.tsconfigFilePath.

property tsdocConfigFile

readonly tsdocConfigFile: TSDocConfigFile;

• The tsdoc.json configuration that will be used when parsing doc comments.

property tsdocConfiguration

readonly tsdocConfiguration: TSDocConfiguration;

• The TSDocConfiguration loaded from ExtractorConfig.tsdocConfigFile.

property tsdocMetadataEnabled

readonly tsdocMetadataEnabled: boolean;

• See documentation for IConfigTsdocMetadata.enabled.

property tsdocMetadataFilePath

readonly tsdocMetadataFilePath: string;

• See documentation for IConfigTsdocMetadata.tsdocMetadataFilePath.

property untrimmedFilePath

readonly untrimmedFilePath: string;

• See documentation for IConfigDtsRollup.untrimmedFilePath.

method getDiagnosticDump

getDiagnosticDump: () => string;

• Returns a JSON-like string representing the ExtractorConfig state, which can be printed to a console for diagnostic purposes.

  Remarks

  This is used by the "--diagnostics" command-line option. The string is not intended to be deserialized; its format may be changed at any time.

method hasDtsFileExtension

static hasDtsFileExtension: (filePath: string) => boolean;

• Returns true if the specified file path has the ".d.ts" file extension.

method loadFile

static loadFile: (jsonFilePath: string) => IConfigFile;

• Performs only the first half of ExtractorConfig.loadFileAndPrepare, providing an opportunity to modify the object before it is passed to ExtractorConfig.prepare.

  Remarks

  Loads the api-extractor.json config file from the specified file path. If the "extends" field is present, the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.

method loadFileAndPrepare

static loadFileAndPrepare: (configJsonFilePath: string) => ExtractorConfig;

• Loads the api-extractor.json config file from the specified file path, and prepares an ExtractorConfig object.

  Remarks

  Loads the api-extractor.json config file from the specified file path. If the "extends" field is present, the referenced file(s) will be merged. For any omitted fields, the API Extractor default values are merged.

  The result is prepared using ExtractorConfig.prepare().

method prepare

static prepare: (options: IExtractorConfigPrepareOptions) => ExtractorConfig;

• Prepares an ExtractorConfig object using a configuration that is provided as a runtime object, rather than reading it from disk. This allows configurations to be constructed programmatically, loaded from an alternate source, and/or customized after loading.

method tryLoadForFolder

static tryLoadForFolder: (
    options: IExtractorConfigLoadForFolderOptions
) => IExtractorConfigPrepareOptions | undefined;

• Searches for the api-extractor.json config file associated with the specified starting folder, and loads the file if found. This lookup supports rig packages.

  Returns

  An options object that can be passed to ExtractorConfig.prepare, or undefined if not api-extractor.json file was found.

  Remarks

  The search will first look for a package.json file in a parent folder of the starting folder; if found, that will be used as the base folder instead of the starting folder. If the config file is not found in <baseFolder>/api-extractor.json or <baseFolder>/config/api-extractor.json, then <baseFolder/config/rig.json will be checked to see whether a rig package is referenced; if so then the rig's api-extractor.json file will be used instead. If a config file is found, it will be loaded and returned with the IExtractorConfigPrepareOptions object. Otherwise, undefined is returned to indicate that API Extractor does not appear to be configured for the specified folder.

property category

readonly category: ExtractorMessageCategory;

• The category of issue.

property handled

handled: boolean;

• If the IExtractorInvokeOptions.messageCallback sets this property to true, it will prevent the message from being displayed by API Extractor.

  Remarks

  If the messageCallback routes the message to a custom handler (e.g. a toolchain logger), it should assign handled = true to prevent API Extractor from displaying it. Assigning handled = true for all messages would effectively disable all console output from the Extractor API.

  If handled is set to true, the message will still be included in the count of errors/warnings; to discard a message entirely, instead assign logLevel = none.

property logLevel

logLevel: ExtractorLogLevel;

• Specifies how the message should be reported.

  Remarks

  If the IExtractorInvokeOptions.messageCallback handles the message (i.e. sets handled = true), it can use the logLevel to determine how to display the message.

  Alternatively, if API Extractor is handling the message, the messageCallback could assign logLevel to change how it will be processed. However, in general the recommended practice is to configure message routing using the messages section in api-extractor.json.

  To discard a message entirely, assign logLevel = none.

property messageId

readonly messageId: any;

• A text string that uniquely identifies the issue type. This identifier can be used to suppress or configure the reporting of issues, and also to search for help about an issue.

property properties

readonly properties: IExtractorMessageProperties;

• Additional contextual information about the message that may be useful when reporting errors. All properties are optional.

property sourceFileColumn

readonly sourceFileColumn: number;

• The column number where the issue occurred in the input source file. This is not used if sourceFilePath is undefined. The first column number is 1.

property sourceFileLine

readonly sourceFileLine: number;

• The line number where the issue occurred in the input source file. This is not used if sourceFilePath is undefined. The first line number is 1.

property sourceFilePath

readonly sourceFilePath: string;

• The absolute path to the affected input source file, if there is one.

property text

readonly text: string;

• The text description of this issue.

method formatMessageWithLocation

formatMessageWithLocation: (
    workingPackageFolderPath: string | undefined
) => string;

• Returns the message formatted with its identifier and file position.

  Remarks

  Example:

  src/folder/File.ts:123:4 - (ae-extra-release-tag) The doc comment should not contain more than one release tag.

method formatMessageWithoutLocation

formatMessageWithoutLocation: () => string;

property apiReportChanged

readonly apiReportChanged: boolean;

• Returns true if the API report was found to have changed.

property compilerState

readonly compilerState: CompilerState;

• The TypeScript compiler state that was used.

property errorCount

readonly errorCount: number;

• Reports the number of errors encountered during analysis.

  Remarks

  This does not count exceptions, where unexpected issues prematurely abort the operation.

property extractorConfig

readonly extractorConfig: ExtractorConfig;

• The API Extractor configuration that was used.

property succeeded

readonly succeeded: boolean;

• Whether the invocation of API Extractor was successful. For example, if succeeded is false, then the build task would normally return a nonzero process exit code, indicating that the operation failed.

  Remarks

  Normally the operation "succeeds" if errorCount and warningCount are both zero. However if IExtractorInvokeOptions.localBuild is true, then the operation "succeeds" if errorCount is zero (i.e. warnings are ignored).

property warningCount

readonly warningCount: number;

• Reports the number of warnings encountered during analysis.

  Remarks

  This does not count warnings that are emitted in the API report file.

property releaseTagsToTrim

releaseTagsToTrim: Set<ReleaseTag>;

• The release tags to trim.

property additionalEntryPoints

additionalEntryPoints?: string[];

• Additional .d.ts files to include in the analysis.

property typescriptCompilerFolder

typescriptCompilerFolder?: string;

• See documentation for IExtractorInvokeOptions.typescriptCompilerFolder.

property enabled

enabled: boolean;

• Whether to generate an API report.

property includeForgottenExports

includeForgottenExports?: boolean;

• Whether "forgotten exports" should be included in the API report file.

  Remarks

  Forgotten exports are declarations flagged with ae-forgotten-export warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.

property reportFileName

reportFileName?: string;

• The base filename for the API report files, to be combined with IConfigApiReport.reportFolder or IConfigApiReport.reportTempFolder to produce the full file path.

  Remarks

  The reportFileName should not include any path separators such as \ or /. The reportFileName should not include a file extension, since API Extractor will automatically append an appropriate file extension such as .api.md. If the IConfigApiReport.reportVariants setting is used, then the file extension includes the variant name, for example my-report.public.api.md or my-report.beta.api.md. The complete variant always uses the simple extension my-report.api.md.

  Previous versions of API Extractor required reportFileName to include the .api.md extension explicitly; for backwards compatibility, that is still accepted but will be discarded before applying the above rules.

property reportFolder

reportFolder?: string;

• Specifies the folder where the API report file is written. The file name portion is determined by the reportFileName setting.

  Remarks

  The API report file is normally tracked by Git. Changes to it can be used to trigger a branch policy, e.g. for an API review.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property reportTempFolder

reportTempFolder?: string;

• Specifies the folder where the temporary report file is written. The file name portion is determined by the reportFileName setting.

  Remarks

  After the temporary file is written to disk, it is compared with the file in the reportFolder. If they are different, a production build will fail.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property reportVariants

reportVariants?: ApiReportVariant[];

• The set of report variants to generate.

  Remarks

  To support different approval requirements for different API levels, multiple "variants" of the API report can be generated. The reportVariants setting specifies a list of variants to be generated. If omitted, by default only the complete variant will be generated, which includes all @internal, @alpha, @beta, and @public items. Other possible variants are alpha (@alpha + @beta + @public), beta (@beta + @public), and public (@public only).

  The resulting API report file names will be derived from the IConfigApiReport.reportFileName.

property overrideTsconfig

overrideTsconfig?: {};

• Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.

  Remarks

  The value must conform to the TypeScript tsconfig schema:

  http://json.schemastore.org/tsconfig

  If omitted, then the tsconfig.json file will instead be read from the projectFolder.

property skipLibCheck

skipLibCheck?: boolean;

• This option causes the compiler to be invoked with the --skipLibCheck option.

  Remarks

  This option is not recommended and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses for its analysis. Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.

property tsconfigFilePath

tsconfigFilePath?: string;

• Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.

  Remarks

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

  Note: This setting will be ignored if overrideTsconfig is used.

property apiJsonFilePath

apiJsonFilePath?: string;

• The output path for the doc model file. The file extension should be ".api.json".

  Remarks

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property enabled

enabled: boolean;

• Whether to generate a doc model file.

property includeForgottenExports

includeForgottenExports?: boolean;

• Whether "forgotten exports" should be included in the doc model file.

  Remarks

  Forgotten exports are declarations flagged with ae-forgotten-export warnings. See https://api-extractor.com/pages/messages/ae-forgotten-export/ to learn more.

property projectFolderUrl

projectFolderUrl?: string;

• The base URL where the project's source code can be viewed on a website such as GitHub or Azure DevOps. This URL path corresponds to the <projectFolder> path on disk.

  Remarks

  This URL is concatenated with the file paths serialized to the doc model to produce URL file paths to individual API items. For example, if the projectFolderUrl is "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor" and an API item's file path is "api/ExtractorConfig.ts", the full URL file path would be "https://github.com/microsoft/rushstack/tree/main/apps/api-extractor/api/ExtractorConfig.js".

  Can be omitted if you don't need source code links in your API documentation reference.

property releaseTagsToTrim

releaseTagsToTrim?: ReleaseTagForTrim[];

• Specifies a list of release tags that will be trimmed from the doc model.

property alphaTrimmedFilePath

alphaTrimmedFilePath?: string;

• Specifies the output path for a .d.ts rollup file to be generated with trimming for an "alpha" release.

  Remarks

  This file will include only declarations that are marked as @public, @beta, or @alpha.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property betaTrimmedFilePath

betaTrimmedFilePath?: string;

• Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.

  Remarks

  This file will include only declarations that are marked as @public or @beta.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property enabled

enabled: boolean;

• Whether to generate the .d.ts rollup file.

property omitTrimmingComments

omitTrimmingComments?: boolean;

• When a declaration is trimmed, by default it will be replaced by a code comment such as "Excluded from this release type: exampleMember". Set "omitTrimmingComments" to true to remove the declaration completely.

property publicTrimmedFilePath

publicTrimmedFilePath?: string;

• Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.

  Remarks

  This file will include only declarations that are marked as @public.

  If the path is an empty string, then this file will not be written.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property untrimmedFilePath

untrimmedFilePath?: string;

• Specifies the output path for a .d.ts rollup file to be generated without any trimming.

  Remarks

  This file will include all declarations that are exported by the main entry point.

  If the path is an empty string, then this file will not be written.

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

property apiReport

apiReport?: IConfigApiReport;

• See documentation for IConfigApiReport.

property bundledPackages

bundledPackages?: string[];

• A list of NPM package names whose exports should be treated as part of this package.

  Remarks

  Also supports glob patterns. Note: glob patterns will **only** be resolved against dependencies listed in the project's package.json file.

  * This is both a safety and a performance precaution.

  Exact package names will be applied against any dependency encountered while walking the type graph, regardless of dependencies listed in the package.json.

  Example 1

  Suppose that Webpack is used to generate a distributed bundle for the project library1, and another NPM package library2 is embedded in this bundle. Some types from library2 may become part of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly imports library2. To avoid this, we can specify:

    "bundledPackages": [ "library2" ],

  This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been local files for library1.

property compiler

compiler?: IConfigCompiler;

• See documentation for IConfigCompiler.

property docModel

docModel?: IConfigDocModel;

• See documentation for IConfigDocModel.

property dtsRollup

dtsRollup?: IConfigDtsRollup;

• See documentation for IConfigDtsRollup.

property enumMemberOrder

enumMemberOrder?: EnumMemberOrder;

• Specifies how API Extractor sorts members of an enum when generating the .api.json file.

  Remarks

  By default, the output files will be sorted alphabetically, which is "by-name". To keep the ordering in the source code, specify "preserve".

property extends

extends?: string;

• Optionally specifies another JSON config file that this file extends from. This provides a way for standard settings to be shared across multiple projects.

  Remarks

  If the path starts with ./ or ../, the path is resolved relative to the folder of the file that contains the extends field. Otherwise, the first path segment is interpreted as an NPM package name, and will be resolved using NodeJS require().

property mainEntryPointFilePath

mainEntryPointFilePath: string;

• Specifies the .d.ts file to be used as the starting point for analysis. API Extractor analyzes the symbols exported by this module.

  Remarks

  The file extension must be ".d.ts" and not ".ts". The path is resolved relative to the "projectFolder" location.

property messages

messages?: IExtractorMessagesConfig;

• See documentation for IExtractorMessagesConfig.

property newlineKind

newlineKind?: 'crlf' | 'lf' | 'os';

• Specifies what type of newlines API Extractor should use when writing output files.

  Remarks

  By default, the output files will be written with Windows-style newlines. To use POSIX-style newlines, specify "lf" instead. To use the OS's default newline kind, specify "os".

property projectFolder

projectFolder?: string;

• Determines the <projectFolder> token that can be used with other config file settings. The project folder typically contains the tsconfig.json and package.json config files, but the path is user-defined.

  Remarks

  The path is resolved relative to the folder of the config file that contains the setting.

  The default value for projectFolder is the token <lookup>, which means the folder is determined using the following heuristics:

  If the config/rig.json system is used (as defined by @rushstack/rig-package), then the <lookup> value will be the package folder that referenced the rig.

  Otherwise, the <lookup> value is determined by traversing parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder that contains a tsconfig.json file. If a tsconfig.json file cannot be found in this way, then an error will be reported.

property testMode

testMode?: boolean;

• Set to true when invoking API Extractor's test harness.

  Remarks

  When testMode is true, the toolVersion field in the .api.json file is assigned an empty string to prevent spurious diffs in output files tracked for tests.

property tsdocMetadata

tsdocMetadata?: IConfigTsdocMetadata;

• See documentation for IConfigTsdocMetadata.

property addToApiReportFile

addToApiReportFile?: boolean;

• When addToApiReportFile is true: If API Extractor is configured to write an API report file (.api.md), then the message will be written inside that file; otherwise, the message is instead logged according to the logLevel option.

property logLevel

logLevel: ExtractorLogLevel;

• Specifies whether the message should be written to the the tool's output log.

  Remarks

  Note that the addToApiReportFile property may supersede this option.

index signature

[messageId: string]: IConfigMessageReportingRule;

• The key is a message identifier for the associated type of message, or "default" to specify the default policy. For example, the key might be TS2551 (a compiler message), tsdoc-link-tag-unescaped-text (a TSDOc message), or ae-extra-release-tag (a message related to the API Extractor analysis).

property enabled

enabled: boolean;

• Whether to generate the tsdoc-metadata.json file.

property tsdocMetadataFilePath

tsdocMetadataFilePath?: string;

• Specifies where the TSDoc metadata file should be written.

  Remarks

  The path is resolved relative to the folder of the config file that contains the setting; to change this, prepend a folder token such as <projectFolder>.

  The default value is <lookup>, which causes the path to be automatically inferred from the tsdocMetadata, typings or main fields of the project's package.json. If none of these fields are set, the lookup falls back to tsdoc-metadata.json in the package folder.

property fileName

fileName: string;

• Name of the output report file.

  Remarks

  Relative to the configured report directory path.

property variant

variant: ApiReportVariant;

• Report variant. Determines which API items will be included in the report output, based on their tagged release levels.

property packageJsonLookup

packageJsonLookup?: PackageJsonLookup;

• An already constructed PackageJsonLookup cache object to use. If omitted, a temporary one will be constructed.

property rigConfig

rigConfig?: IRigConfig;

• An already constructed RigConfig object. If omitted, then a new RigConfig object will be constructed.

property startingFolder

startingFolder: string;

• The folder path to start from when searching for api-extractor.json.

property configObject

configObject: IConfigFile;

• A configuration object as returned by ExtractorConfig.loadFile.

property configObjectFullPath

configObjectFullPath: string | undefined;

• The absolute path of the file that the configObject object was loaded from. This is used for error messages and when probing for tsconfig.json.

  Remarks

  If configObjectFullPath and projectFolderLookupToken are both unspecified, then the api-extractor.json config file must explicitly specify a projectFolder setting rather than relying on the <lookup> token.

property ignoreMissingEntryPoint

ignoreMissingEntryPoint?: boolean;

• When preparing the configuration object, folder and file paths referenced in the configuration are checked for existence, and an error is reported if they are not found. This option can be used to disable this check for the main entry point module. This may be useful when preparing a configuration file for an un-built project.

property packageJson

packageJson?: INodePackageJson | undefined;

• The parsed package.json file for the working package, or undefined if API Extractor was invoked without a package.json file.

  Remarks

  If omitted, then the <unscopedPackageName> and <packageName> tokens will have default values.

property packageJsonFullPath

packageJsonFullPath: string | undefined;

• The absolute path of the file that the packageJson object was loaded from, or undefined if API Extractor was invoked without a package.json file.

  Remarks

  This is used for error messages and when resolving paths found in package.json.

  If packageJsonFullPath is specified but packageJson is omitted, the file will be loaded automatically.

property projectFolderLookupToken

projectFolderLookupToken?: string;

• The default value for the projectFolder setting is the <lookup> token, which uses a heuristic to guess an appropriate project folder. Use projectFolderLookupValue to manually specify the <lookup> token value instead.

  Remarks

  If the projectFolder setting is explicitly specified in api-extractor.json file, it should take precedence over a value specified via the API. Thus the projectFolderLookupToken option provides a way to override the default value for projectFolder setting while still honoring a manually specified value.

property tsdocConfigFile

tsdocConfigFile?: TSDocConfigFile;

• Allow customization of the tsdoc.json config file. If omitted, this file will be loaded from its default location. If the file does not exist, then the standard definitions will be used from @microsoft/api-extractor/extends/tsdoc-base.json.

property compilerState

compilerState?: CompilerState;

• An optional TypeScript compiler state. This allows an optimization where multiple invocations of API Extractor can reuse the same TypeScript compiler analysis.

property localBuild

localBuild?: boolean;

• Indicates that API Extractor is running as part of a local build, e.g. on developer's machine.

  Remarks

  This disables certain validation that would normally be performed for a ship/production build. For example, the *.api.md report file is automatically updated in a local build.

  The default value is false.

property messageCallback

messageCallback?: (message: ExtractorMessage) => void;

• An optional callback function that will be called for each ExtractorMessage before it is displayed by API Extractor. The callback can customize the message, handle it, or discard it.

  Remarks

  If a messageCallback is not provided, then by default API Extractor will print the messages to the STDERR/STDOUT console.

property showDiagnostics

showDiagnostics?: boolean;

• If true, API Extractor will print diagnostic information used for troubleshooting problems. These messages will be included as ExtractorLogLevel.Verbose output.

  Remarks

  Setting showDiagnostics=true forces showVerboseMessages=true.

property showVerboseMessages

showVerboseMessages?: boolean;

• If true, API Extractor will include ExtractorLogLevel.Verbose messages in its output.

property typescriptCompilerFolder

typescriptCompilerFolder?: string;

• Specifies an alternate folder path to be used when loading the TypeScript system typings.

  Remarks

  API Extractor uses its own TypeScript compiler engine to analyze your project. If your project is built with a significantly different TypeScript version, sometimes API Extractor may report compilation errors due to differences in the system typings (e.g. lib.dom.d.ts). You can use the "--typescriptCompilerFolder" option to specify the folder path where you installed the TypeScript package, and API Extractor's compiler will use those system typings instead.

property exportName

readonly exportName?: string;

• A declaration can have multiple names if it is exported more than once. If an ExtractorMessage applies to a specific export name, this property can indicate that.

  Remarks

  Used by ExtractorMessageId.InternalMissingUnderscore.

property compilerMessageReporting

compilerMessageReporting?: IConfigMessageReportingTable;

• Configures handling of diagnostic messages generating the TypeScript compiler while analyzing the input .d.ts files.

property extractorMessageReporting

extractorMessageReporting?: IConfigMessageReportingTable;

• Configures handling of messages reported by API Extractor during its analysis.

property tsdocMessageReporting

tsdocMessageReporting?: IConfigMessageReportingTable;

• Configures handling of messages reported by the TSDoc parser when analyzing code comments.

member ApiReportCopied

ApiReportCopied = 'console-api-report-copied'

• "You have changed the public API signature for this project. Updating ___"

member ApiReportCreated

ApiReportCreated = 'console-api-report-created'

• "The API report file was missing, so a new file was created. Please add this file to Git: ___"

member ApiReportFolderMissing

ApiReportFolderMissing = 'console-api-report-folder-missing'

• "Unable to create the API report file. Please make sure the target folder exists: ___"

member ApiReportNotCopied

ApiReportNotCopied = 'console-api-report-not-copied'

• "You have changed the public API signature for this project. Please copy the file ___ to ___, or perform a local build (which does this automatically). See the Git repo documentation for more info."

  OR

  "The API report file is missing. Please copy the file ___ to ___, or perform a local build (which does this automatically). See the Git repo documentation for more info."

member ApiReportUnchanged

ApiReportUnchanged = 'console-api-report-unchanged'

• "The API report is up to date: ___"

member CompilerVersionNotice

CompilerVersionNotice = 'console-compiler-version-notice'

• "The target project appears to use TypeScript ___ which is newer than the bundled compiler engine; consider upgrading API Extractor."

member Diagnostics

Diagnostics = 'console-diagnostics'

• Used for the information printed when the "--diagnostics" flag is enabled.

member FoundTSDocMetadata

FoundTSDocMetadata = 'console-found-tsdoc-metadata'

• "Found metadata in ___"

member Preamble

Preamble = 'console-preamble'

• "Analysis will use the bundled TypeScript version ___"

member UsingCustomTSDocConfig

UsingCustomTSDocConfig = 'console-using-custom-tsdoc-config'

• "Using custom TSDoc config from ___"

member WritingApiReport

WritingApiReport = 'console-writing-api-report'

• "Generating ___ API report: ___"

member WritingDocModelFile

WritingDocModelFile = 'console-writing-doc-model-file'

• "Writing: ___"

member WritingDtsRollup

WritingDtsRollup = 'console-writing-dts-rollup'

• "Writing package typings: ___"

member Error

Error = 'error'

• The message will be displayed as an error.

  Remarks

  Errors typically cause the build to fail and return a nonzero exit code.

member Info

Info = 'info'

• The message will be displayed as an informational message.

  Remarks

  Informational messages may contain newlines to ensure nice formatting of the output, however word-wrapping is the responsibility of the message handler.

member None

None = 'none'

• The message will be discarded entirely.

member Verbose

Verbose = 'verbose'

• The message will be displayed only when "verbose" output is requested, e.g. using the --verbose command line option.

member Warning

Warning = 'warning'

• The message will be displayed as an warning.

  Remarks

  Warnings typically cause a production build fail and return a nonzero exit code. For a non-production build (e.g. using the --local option with api-extractor run), the warning is displayed but the build will not fail.

member Compiler

Compiler = 'Compiler'

• Messages originating from the TypeScript compiler.

  Remarks

  These strings begin with the prefix "TS" and have a numeric error code. Example: TS2551

member Console

Console = 'console'

• Console messages communicate the progress of the overall operation. They may include newlines to ensure nice formatting. They are output in real time, and cannot be routed to the API Report file.

  Remarks

  These strings begin with the prefix "console-". Example: console-writing-typings-file

member Extractor

Extractor = 'Extractor'

• Messages related to API Extractor's analysis.

  Remarks

  These strings begin with the prefix "ae-". Example: ae-extra-release-tag

member TSDoc

TSDoc = 'TSDoc'

• Messages related to parsing of TSDoc comments.

  Remarks

  These strings begin with the prefix "tsdoc-". Example: tsdoc-link-tag-unescaped-text

member CyclicInheritDoc

CyclicInheritDoc = 'ae-cyclic-inherit-doc'

• "The @inheritDoc tag for ___ refers to its own declaration."

member DifferentReleaseTags

DifferentReleaseTags = 'ae-different-release-tags'

• "This symbol has another declaration with a different release tag."

member ExtraReleaseTag

ExtraReleaseTag = 'ae-extra-release-tag'

• "The doc comment should not contain more than one release tag."

member ForgottenExport

ForgottenExport = 'ae-forgotten-export'

• "The symbol ___ needs to be exported by the entry point ___."

member IncompatibleReleaseTags

IncompatibleReleaseTags = 'ae-incompatible-release-tags'

• "The symbol ___ is marked as ___, but its signature references ___ which is marked as ___."

member InternalMissingUnderscore

InternalMissingUnderscore = 'ae-internal-missing-underscore'

• "The name ___ should be prefixed with an underscore because the declaration is marked as @internal."

member InternalMixedReleaseTag

InternalMixedReleaseTag = 'ae-internal-mixed-release-tag'

• "Mixed release tags are not allowed for ___ because one of its declarations is marked as @internal."

member MisplacedPackageTag

MisplacedPackageTag = 'ae-misplaced-package-tag'

• "The @packageDocumentation comment must appear at the top of entry point *.d.ts file."

member MissingGetter

MissingGetter = 'ae-missing-getter'

• "The property ___ has a setter but no getter."

member MissingReleaseTag

MissingReleaseTag = 'ae-missing-release-tag'

• "___ is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)."

member PreapprovedBadReleaseTag

PreapprovedBadReleaseTag = 'ae-preapproved-bad-release-tag'

• "The @preapproved tag cannot be applied to ___ without an @internal release tag."

member PreapprovedUnsupportedType

PreapprovedUnsupportedType = 'ae-preapproved-unsupported-type'

• "The @preapproved tag cannot be applied to ___ because it is not a supported declaration type."

member SetterWithDocs

SetterWithDocs = 'ae-setter-with-docs'

• "The doc comment for the property ___ must appear on the getter, not the setter."

member Undocumented

Undocumented = 'ae-undocumented'

• "Missing documentation for ___."

  Remarks

  The ae-undocumented message is only generated if the API report feature is enabled.

  Because the API report file already annotates undocumented items with // (undocumented), the ae-undocumented message is not logged by default. To see it, add a setting such as:

  "messages": {
    "extractorMessageReporting": {
      "ae-undocumented": {
        "logLevel": "warning"
      }
    }
   }

member UnresolvedInheritDocBase

UnresolvedInheritDocBase = 'ae-unresolved-inheritdoc-base'

• "The @inheritDoc tag needs a TSDoc declaration reference; signature matching is not supported yet."

member UnresolvedInheritDocReference

UnresolvedInheritDocReference = 'ae-unresolved-inheritdoc-reference'

• "The @inheritDoc reference could not be resolved."

member UnresolvedLink

UnresolvedLink = 'ae-unresolved-link'

• "The @link reference could not be resolved."

member WrongInputFileType

WrongInputFileType = 'ae-wrong-input-file-type'

• "Incorrect file type; API Extractor expects to analyze compiler outputs with the .d.ts file extension. Troubleshooting tips: https://api-extractor.com/link/dts-error"