ts-trim-declarations

Custom transformer for TypeScript that removes type declarations with /** @internal */ JSDoc comments (or whatever other tags you specify!). Inspired by @microsoft/api-extractor.

Custom transformers can't be (yet) used with plain typescript, you're encouraged to use ttypescript, or plugins to your build tool of choice, especially @wessberg/rollup-plugin-ts. For other build tools, refer to their documentation on how to use TypeScript Custom Transformers.

Effect

It will remove the declarions tagged with the specified JSDoc comments (/** @internal */ by default) from the .d.ts file output, so they will not be documented. Users of your library trying to use these methods, properties, exports, etc. will get a typechecking error, and automated documentation generators like @microsoft/api-documenter will not export their typings.

For example, this source.ts:

 class MyClass {
+  /** @internal */
   protected _foo() {
     return "very internal string"
   }

   bar() {
     const publicString = this._foo().toUpperCase()
     // Now it's ready for public usage!
     return publicString
   }
 }

will output the following source.d.ts:

 declare class MyClass {
-  protected _foo(): string
   bar(): string
 }

Installation

$ yarn add --dev ts-trim-declarations

or

$ npm install --save-dev ts-trim-declarations

then add the Custom Transformer to your build tool's configuration

ttypescript

Add this field to your tsconfig.json (only works from Node.js 12.7 onwards):

 {
   // ..
   "compilerOptions": {
     "plugins": [
        // ...
+       { "transform": "ts-trim-declarations/raw", "type": "raw" }
     ]
   }
 }

rollup and @wessberg/rollup-plugin-ts

Add this plugin to the object exported from rollup.config.js:

// ...
 import ts from "@wessberg/rollup-plugin-ts"
+import tsTrimDeclarations from "ts-trim-declarations"

 export default {
   // ...
   plugins: [
     // ...
     ts({
       // ...
       transpiler: "typescript",
       transformers: [
         // ...
+        tsTrimDeclarations(),
       ],
     }),
   ],
 }

TypeScript API

Check out this TypeScript's issue to learn about their API.

Other build tools

Please refer to your build tool's documentation for information on hwo to use TypeScript Custom Transformers

Options

Importing ts-trim-declarations will give you a function you can call with an array of JSDoc tags to remove. The default is ["internal"]-

import tsTrimDeclarations from "ts-trim-declarations"
// ...
tsTrimDeclarations(isBeta ? ["internal"] : ["internal", "beta"])
// Will remove all declarations with `/** @internal */, but will only remove
// the `/** @beta */` declarations when `isBeta === true`.

The ts-trim-declarations/raw import will forgo the function call and give you a straight Custom Transformer that removes only /** @internal */ tags.