typedoc-plugin-import-target

Table of contents

• 🍵 Introduction
• 🚀 Get started
• ⚙️ Options
• 🧬 Types
  • PluginOptions
  • Reflection
• 🧰 TSDoc configuration
• 🤝 Contribute
• 👑 Author
• ⚖️ License
• 📰 Changelog
• 🧱 Related packages

🍵 Introduction

This TypeDoc plugin allows you to map your exported module members to your package.json exports field. It adds support for @importTarget JSDoc tag to use in combination with @module tag.

Just add tag to the top-level JSDoc comment:

// foo.js

/**
 * @module
 * @importTarget ./foo
 */

export class Foo {}

export function foo () {}

The exported members Foo and foo will have auto-injected import code block in their description like:

```js
import { Foo } from 'example/foo'
```

Note that the exported members reflections will have the _importTarget property set. See Reflection type below.

🚀 Get started

npm install -D typedoc-plugin-import-target

Add the plugin in your typedoc.config.js file:

// typedoc.config.js

export default {
  entryPoints: [
    './src/index.ts'
  ],
  plugin: [
    'typedoc-plugin-import-target'
  ]
}

Let's run the typedoc command!

⚙️ Options

This plugin supports some options. See PluginOptions type below.

For example, in your typedoc.config.js file:

// typedoc.config.js

/**
 * @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-import-target').PluginOptions}
 */
export default {
  entryPoints: [
    './src/index.ts'
  ],
  plugin: [
    'typedoc-plugin-import-target'
  ],
  /**
   * typedoc-plugin-import-target options
   */
  importTarget: {
    // Force "ts" language for code blocks
    codeBlockLang: 'ts',
    // Ignore package.json "exports" field
    ignorePackageExports: true,
    // Write your own injection logic
    inject (reflection, name, importTarget, lang) {
      // ...
    }
  }
}

💡 You don't need to add "@importTarget" to TypeDoc blockTags option

🧬 Types

PluginOptions

export interface PluginOptions {
  /**
   * typedoc-plugin-import-target specific options.
   */
  importTarget?: {
    /**
     * The language to use in markdown code blocks.
     * Note that this option **does not affect** code blocks for any
     * type reflection (always "ts"). Default: `js`
     */
    codeBlockLang?: 'js' | 'ts'
    /**
     * Ignore package.json "exports" field. Default: `false`
     */
    ignorePackageExports?: boolean
    /**
     * Provide your own function to inject import code block
     * @param reflection - The reflection
     * @param name - The exported member name
     * @param lang - The code block language
     */
    inject?: (reflection: Reflection, name: string, importTarget: string, lang?: string) => void
  }
}

Reflection

export interface Reflection extends TypeDoc.Reflection {
  /**
   * The resolved import target as string
   */
  _importTarget?: string
}

🧰 TSDoc configuration

If you use a tsdoc.json configuration file in your project, you can extend your own config with this plugin TSDoc config file:

// tsdoc.json
{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "@microsoft/api-extractor/extends/tsdoc-base.json",
    "typedoc/tsdoc.json",
    "typedoc-plugin-import-target/extends/tsdoc.json"
  ]
}

👀 See also the TypeDoc tags documentation.

🤝 Contribute

You would like to contribute to this project? You are welcome!

First, please check:

• the contribution guide
• the code of conduct

👑 Author

Made with ❤ by Hervé Perchec

⚖️ License

GPL-3.0-only

📰 Changelog

See all changes to this project in the CHANGELOG.md file.

🧱 Related packages

• typedoc

README.md - this file was auto generated with juisy README templater. Don't edit it.