or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

category-organization.md component-bundling.md component-documentation.md content-loading.md index.md theme-engine.md typedef-import.md typescript-support.md

tile.json

TypeDef Import Plugin

TypeScript-style import type cleanup plugin that removes import type declarations from source code before JSDoc processing.

Capabilities

Import Type Cleanup

Removes TypeScript-style import type declarations that would cause JSDoc parsing errors.

interface TypeDefImportHandlers {
  /**
   * Processes source code before JSDoc parsing to remove import type declarations
   * @param {Object} e - Parse event containing source code
   */
  beforeParse(e: ParseEvent): void;
}

interface ParseEvent {
  /** Source file name */
  filename: string;
  /** Source code content */
  source: string;
}

Usage Patterns

Basic Import Type Removal

The plugin automatically removes TypeScript-style import type declarations during JSDoc parsing:

TypeScript Input:

/** @typedef {import('./some-other-file').ExportedType} ExportedType */

/**
 * User service that works with exported types
 * @param {ExportedType} data - Data of exported type
 */
function processData(data) {
  // Implementation
}

Processed Output:

/**
 * User service that works with exported types
 * @param {ExportedType} data - Data of exported type
 */
function processData(data) {
  // Implementation
}

Complex Import Patterns

Handles various import type declaration patterns:

/** @typedef {import('./types/user').User} User */
/** @typedef {import('./types/api').ApiResponse} ApiResponse */
/** @typedef {import('external-lib').LibType} LibType */

/**
 * API service with typed responses
 * @param {User} user - User data
 * @returns {Promise<ApiResponse>} API response
 */
async function callApi(user) {
  // Implementation
}

All @typedef {import(...)} declarations are automatically removed before JSDoc processing.

Integration with TypeScript Plugin

Works seamlessly with the TypeScript plugin to provide complete TypeScript support:

{
  "plugins": [
    "node_modules/better-docs/typescript",
    "node_modules/better-docs/typedef-import"
  ]
}

The typedef-import plugin cleans up import declarations while the TypeScript plugin converts TypeScript constructs to JSDoc format.

Configuration

Enable the typedef-import plugin in JSDoc configuration:

{
  "plugins": [
    "node_modules/better-docs/typedef-import"
  ]
}

No additional configuration is required - the plugin automatically processes all source files during JSDoc parsing.

Use Cases

Legacy TypeScript Support

When working with older TypeScript codebases that use import type declarations in JSDoc comments:

/**
 * Legacy service with import types
 * @typedef {import('./legacy-types').OldType} OldType
 * @param {OldType} data - Legacy data structure
 */
function legacyFunction(data) {
  // Implementation
}

Mixed Codebases

In projects mixing JavaScript and TypeScript where some files use import type declarations:

// mixed-service.js
/**
 * @typedef {import('./types.ts').ServiceConfig} ServiceConfig
 * @param {ServiceConfig} config - Service configuration
 */
function initializeService(config) {
  // Implementation
}

External Library Types

When referencing types from external libraries in JSDoc comments:

/**
 * @typedef {import('express').Request} ExpressRequest
 * @typedef {import('express').Response} ExpressResponse
 * 
 * Express route handler
 * @param {ExpressRequest} req - Express request
 * @param {ExpressResponse} res - Express response
 */
function routeHandler(req, res) {
  // Implementation
}

Processing Details

Regex Pattern

The plugin uses a specific regex pattern to identify and remove import type declarations:

/\/\*\*\s*?@typedef\s*?{\s*?import.*\*\//g

This pattern matches:

JSDoc comment blocks starting with /**
@typedef tags
Import declarations in curly braces {import(...)}
Complete comment blocks ending with */

Multi-line Support

Handles single-line and multi-line import type declarations:

/** @typedef {import('./types').Type} Type */

/**
 * @typedef {import('./complex-types').ComplexType} ComplexType
 */

/**
 * Multi-line typedef with import
 * @typedef {import('./deep/nested/types').DeepType} DeepType
 * Some additional documentation
 */

All patterns are automatically detected and removed.

Best Practices

Prefer TypeScript Plugin

For new projects, use the TypeScript plugin instead of manual import type declarations:

// Recommended: Use TypeScript plugin
interface UserData {
  name: string;
  email: string;
}

// Avoid: Manual import type declarations
/** @typedef {import('./types').UserData} UserData */

Clean Migration

When migrating from import type declarations to full TypeScript support:

Enable both plugins initially
Gradually convert import declarations to native TypeScript
Remove typedef-import plugin once migration is complete

Documentation Consistency

Keep type documentation consistent across the codebase:

// Good: Clear type documentation
/**
 * Processes user data
 * @param {UserData} data - User information object
 * @returns {ProcessedUser} Processed user data
 */

// Avoid: Mixed approaches
/**
 * @typedef {import('./types').UserData} UserData
 * @param {UserData} data - User information
 */