README.md

typescript-plugin-namespace-import

A TypeScript Language Service Plugin to auto-complete and insert Namespace Import.

Motivation

日本語の記事 / Japanese Article

We often use an object as a namespace.

// someLogics.ts
export const someLogics = {
  calculate() { ... },
  print() { ... },
};

// main.ts
import { someLogics } from "./someLogics.ts";

someLogics.calculate()
// `someLogics` is auto-completable without import!

This is good way in developer experience, but it obstruct tree-shaking. In this case, someLogics.print will be included in bundle although it's not used.

To keep tree-shaking working, we can use Namespace Import.

// someLogics.ts
export function calculate() { ... }
export function print() { ... }

// main.ts
import * as someLogics from "./someLogics.ts";

someLogics.calculate()
// `someLogics` is NOT auto-completable without import :(

Now we can tree-shake someLogics.print. However, developer experience get worse because we can't auto-complete someLogics without import statement. We need to write import statement by ourselves.

typescript-plugin-namespace-import resolves this problem by making Namespace Import auto-completable.

Installation

Install with npm/yarn.

npm install -D typescript-plugin-namespace-import
# or yarn add -D typescript-plugin-namespace-import

Then add this plugin in tsconfig.json.

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-namespace-import",
        "options": {
          "paths": ["src/logics"]
        }
      }
    ]
  }
}

paths option is required. See below for detail.

Options

paths (required)

Value: string[]

Specify directory in relative path to the project's root (tsconfig.json's dir). All .ts or .js files in the directories can be Namespace Imported with auto-completion.

Example:

"options": {
  "paths": ["src/logics"]
}

ignoreNamedExport

Value: boolean

If true, named export from files in paths won't be shown in auto-completion.

Example:

"options": {
  "paths": ["src/logics"],
  "ignoreNamedExport": true
}

nameTransform

Value: "upperCamelCase" | "lowerCamelCase"

Transform import name. If not set, the filename will be used as an import name.

Example:

"options": {
  "paths": ["src/logics"],
  "nameTransform": "lowerCamelCase"
}

Then SomeLogic.ts will be imported like import * as someLogic from "./SomeLogic".