Skip to content

TypeScript types broken in ES Modules #363

@kyota-fujikura

Description

@kyota-fujikura

It looks like v0.7.1 has a TypeScript typings issue when used in an ES Modules project. The runtime API works, but the TypeScript types don’t match the runtime shape.

Summary

  • In v0.7.1, when using ESM, the default import (import iconv from "iconv-lite") is typed incorrectly: it doesn’t expose the expected members (e.g. encode, decode, etc.). As a result, TypeScript reports that iconv.encode / iconv.decode do not exist, even though they do at runtime.
  • A type-only workaround is iconv.default.encode(), but it fails at runtime (iconv.default is undefined).

Environment

  • iconv-lite: 0.7.1
  • TypeScript: 5.9.3

Steps to reproduce

  1. Create an ESM project (package.json includes "type": "module"):

package.json

{
  "type": "module",
  "dependencies": {
    "iconv-lite": "0.7.1"
  },
  "devDependencies": {
    "typescript": "5.9.3"
  }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "es2016",
    "module": "node18",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}
  1. Install iconv-lite@0.7.1.
  2. Add this code:
import iconv from "iconv-lite";

const input = "こんにちは";
const encoding = "shift_jis";

// Works at runtime, but TypeScript errors:
iconv.encode(input, encoding);

// The following PASSES typecheck but FAILS at runtime (iconv.default is undefined):
iconv.default.encode(input, encoding);
  1. Run tsc --noEmit.

Actual result

TypeScript errors:

TS2339: Property 'encode' does not exist on type 'typeof iconv'.

Expected result

TypeScript should allow iconv.encode(...) and iconv.decode(...) for the default import, consistent with runtime behavior.

Additional notes

  • If I change iconv-lite to 0.7.0, the same ESM configuration typechecks successfully.
  • If I keep 0.7.1 but switch the project to CommonJS (remove "type": "module"), it also typechecks.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions