#Declaration files

This chapter introduces what TypeScript Declaration Files are and how to generate declaration files in Rslib.

#What is declaration files

TypeScript Declaration Files provide type information for JavaScript code. Declaration files typically have a .d.ts extension. They allow the TypeScript compiler to understand the type structure of JavaScript code, enabling features like:

1. Type Checking: Provide type information for JavaScript code, helping developers catch potential type errors at compile time.
2. Code Completion: Enhance code editor features like autocomplete and code navigation.
3. Documentation Generation: Generate documentation for JavaScript code, providing better developer experience.
4. IDE Support: Improve the developer experience in IDEs like Visual Studio Code, WebStorm, and others.
5. Library Consumption: Make it easier for users to use and understand your library.

#What are bundle declaration files and bundleless declaration files

#Bundle declaration files

Bundle declaration files involves bundling multiple TypeScript declaration files into a single declaration file.

• Pros:

  • Simplified Management: Simplifies the management and referencing of type files.
  • Easy Distribution: Reduces the number of files users need to handle when using the library.

• Cons:

  • Complex Generation: Generating and maintaining a single bundle file can become complex in large projects.
  • Debugging Challenges: Debugging type issues may not be as intuitive as with separate files.

#Bundleless declaration files

Bundleless declaration files involves generating a separate declaration file for each module in the library, just like tsc does.

• Pros:

  • Modular: Each module has its own type definitions, making maintenance and debugging easier.
  • Flexibility: Suitable for large projects, avoiding the complexity of a single file.

• Cons:

  • Multiple Files: Users may need to handle multiple declaration files when using the library.
  • Complex Management: May require additional configuration to correctly reference all files.

#How to generate declaration files in Rslib

Rslib supports generating declaration files using both the TypeScript Compiler API and tsgo, and also supports bundling declaration files with API Extractor.

#Generate bundleless declaration files

Configure in the Rslib config file:

export default {
  lib: [
    {
      dts: true; 
      // or
      dts: {
        bundle: false;
      }
    },
  ],
};

#Generate bundle declaration files

1. Install @microsoft/api-extractor as a development dependency, which is the underlying tool used for bundling declaration files.

npm add @microsoft/api-extractor -D

yarn add @microsoft/api-extractor -D

pnpm add @microsoft/api-extractor -D

bun add @microsoft/api-extractor -D

deno add npm:@microsoft/api-extractor -D

2. Configure in the Rslib config file:

export default {
  lib: [
    {
      dts: {
        bundle: true;
      }
    },
  ],
};

#Generate declaration files with tsgo

1. Install @typescript/native-preview as a development dependency:

npm add @typescript/native-preview -D

yarn add @typescript/native-preview -D

pnpm add @typescript/native-preview -D

bun add @typescript/native-preview -D

deno add npm:@typescript/native-preview -D

2. Configure in the Rslib config file:

export default {
  lib: [
    {
      dts: {
        tsgo: true,
      },
    },
  ],
};

3. In order to ensure the consistency of local development, you need to install the corresponding VS Code Preview Extension and add the following configuration in the VS Code settings:

{
  "typescript.experimental.useTsgo": true
}

#Notes

During the generation of declaration files, Rslib will automatically enforce some configuration options in tsconfig.json to ensure that the TypeScript Compiler API or tsgo generates only declaration files.

{
  "compilerOptions": {
    "noEmit": false,
    "declaration": true,
    "emitDeclarationOnly": true
  }
}

The priority from highest to lowest of final output directory of declaration files:

• The configuration option dts.distPath
• The configuration option declarationDir in tsconfig.json
• The configuration option output.distPath or output.distPath.root

#Related configuration of declaration files