Remark Plugin to Import TypeScript Code

Common errors

• Error: Cannot find module 'remark-typescript-code-import'

  cause The package `remark-typescript-code-import` has not been installed or the import path is incorrect.
  fix Run `npm install -D remark-typescript-code-import` (or `yarn add -D remark-typescript-code-import`) and verify the import statement `import remarkTypescriptCodeImport from 'remark-typescript-code-import';` is correct.

• TypeError: Unknown directive `typescript`

  cause The `remark-directive` plugin is not active in the Remark processing chain, or it is placed after `remark-typescript-code-import`.
  fix Ensure `remark-directive` is installed (`npm install -D remark-directive`) and included in your Remark usage *before* `remarkTypescriptCodeImport`: `.use(remarkDirective).use(remarkTypescriptCodeImport)`.

• Error: Cannot resolve file path: <rootDir>/your-file.tsx (or similar file not found error)

  cause The `rootDir` option is not correctly configured for paths starting with `<rootDir>/`, or the file simply does not exist at the resolved path.
  fix Verify the file path is correct. If using `<rootDir>/`, ensure the `rootDir` plugin option is set to the absolute path of your project root: `.use(remarkTypescriptCodeImport, { rootDir: process.cwd() })` or a specific absolute path like `path.join(__dirname, '..')`.

Warnings

• breaking Version 1.0.0 introduced breaking changes related to 'naming convention fixes'. Code written for `v0.x` might require updates to directive attributes or names to function correctly.
  Fix: Review your existing Markdown directives (e.g., `::typescript{...}`) and plugin options to align with the new naming conventions introduced in v1.0.0. Consult the changelog for specific details if migrating from `v0.x`.
• gotcha The `remark-typescript-code-import` plugin relies on `remark-directive` to parse its custom directives. If `remark-directive` is not installed and explicitly added to your Remark processing chain, the custom directives will not be recognized, and the plugin will not function.
  Fix: Ensure you install `remark-directive` (`npm install -D remark-directive`) and include it in your Remark processing chain *before* `remark-typescript-code-import`, e.g., `.use(remarkDirective).use(remarkTypescriptCodeImport)`.
• gotcha File paths for imports are relative to the Markdown file by default. When using `<rootDir>/` prefixes, the `rootDir` option must be correctly configured, or it defaults to `process.cwd()` which might not be the expected project root.
  Fix: If using `<rootDir>/` in your directives, explicitly set the `rootDir` option when configuring the plugin: `.use(remarkTypescriptCodeImport, { rootDir: path.resolve(__dirname, '../../') })` to ensure the correct base path is used for resolution.

Install

• npm install remark-typescript-code-import npm
• yarn add remark-typescript-code-import yarn
• pnpm add remark-typescript-code-import pnpm

Imports

• remarkTypescriptCodeImport
  wrong:

  const remarkTypescriptCodeImport = require('remark-typescript-code-import');

  correct:

  import remarkTypescriptCodeImport from 'remark-typescript-code-import';

  This package uses a default export. For CommonJS, append `.default` to the `require` call for correct interop.
• remark
  wrong:

  import remark from 'remark';

  correct:

  import { remark } from 'remark';

  The `remark` processor is a named export from the `remark` package.
• remarkDirective

  import remarkDirective from 'remark-directive';

  The `remark-directive` plugin uses a default export.

Quickstart

This quickstart demonstrates how to use the plugin with `remark` and `remark-directive` to import TypeScript code snippets into a Markdown file. It sets up example `.md` and `.tsx` files, then processes the Markdown to show the imported code blocks. It also illustrates the `rootDir` option.

import { remark } from 'remark';
import path from 'node:path';
import { readSync } from 'to-vfile';
import remarkDirective from 'remark-directive';
import remarkTypescriptCodeImport from 'remark-typescript-code-import';
import { writeFileSync, mkdirSync } from 'node:fs';

// Create dummy files for the example
mkdirSync('docs', { recursive: true });
writeFileSync('docs/example.md', '::typescript{file="./Component.tsx#ComponentProps"}\n::typescript{file="<rootDir>/src/types.ts#User"}');
writeFileSync('docs/Component.tsx', 'type ComponentProps = {\n  propA: string;\n}\n\nfunction Component(props: ComponentProps) {\n  // ...\n}');
mkdirSync('src', { recursive: true });
writeFileSync('src/types.ts', 'export type User = {\n  id: string;\n  name: string;\n};');

async function processMarkdown() {
  const result = await remark()
    .use(remarkDirective)
    .use(remarkTypescriptCodeImport, { rootDir: process.cwd() })
    .process(readSync(path.join(process.cwd(), 'docs', 'example.md')));

  console.log('--- Processed Markdown ---\n');
  console.log(String(result));
  console.log('\n--- End Processed Markdown ---');
}

processMarkdown();