format-imports

library4.0.8jsnpmunverified

A CLI and library to format JavaScript/TypeScript import/export statements with grouping, sorting, deduplication, and unused import removal. Current stable version is 4.0.8, released with support for Import Attributes, ArkTS, and async config resolution. Unlike similar tools (e.g., eslint-plugin-import), it works as a standalone formatter with ESLint, Prettier, and EditorConfig compatibility, and can be used in CI/CD or integrated into IDEs via its VSCode and IntelliJ plugins. Actively maintained with monthly releases.

testing

npm install format-imports

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · FORMAT-IMPORTS

format-imports

testingjavascriptv4.0.8

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatImports

✓ import { formatImports } from 'format-imports'

✗ const formatImports = require('format-imports').formatImports

ESM-only since v4; no default export.

resolveConfigForFile

✓ import { resolveConfigForFile } from 'format-imports'

✗ const { resolveConfigForFile } = require('format-imports')

As of v4.0.0, this function is async; requires await.

FormatOptions

✓ import type { FormatOptions } from 'format-imports'

Type-only import; use import type for type checking.

Demonstrates reading a TypeScript file, resolving configuration, formatting imports, and writing the formatted output back.

import { formatImports, resolveConfigForFile } from 'format-imports'; import { readFile, writeFile } from 'fs/promises'; async function formatFile(filePath: string): Promise<void> { const source = await readFile(filePath, 'utf-8'); const config = await resolveConfigForFile(filePath, { // Add custom configuration options here // For example, resolve aliases }); const result = formatImports({ source, filePath, ...config, }); if (result.code !== 0) { console.error('Error formatting:', filePath); return; } await writeFile(filePath, result.output, 'utf-8'); } // Usage: formatFile('./src/index.ts');

Debug

Known issues

breakingresolveConfigForFile is now async (v4.0.0). Previous versions were synchronous.

fix

Use await when calling resolveConfigForFile, or handle the returned Promise.

affects: >=4.0.0

gotchaThe package is ESM-only since v4; CommonJS require() will fail.

fix

Use import statements or set type: 'module' in package.json.

affects: >=4.0.0

deprecatedThe old CLI flag --output is deprecated in favor of -o shorthand in v4.

fix

Use -o or --output as before, but the old --output with equals sign may stop working in future.

affects: >=4.0.0

gotchaWhen reading from STDIN, no file path is available, so some configuration resolution may fail.

fix

Provide a dummy file path via --config if needed, or pass options directly via API.

affects: >=1.0.0

gotchaType-only imports and exports (import type, export type) are only supported when the TypeScript language service is available (requires typescript dependency).

fix

Install typescript in your project if you use type-only imports/exports.

affects: >=4.0.0

Errors

Common errors & fixes

Error: Cannot find module 'format-imports'

Package not installed or ESM-only module imported via require.

fix

Run 'npm install -D format-imports' and ensure using import instead of require().

TypeError: resolveConfigForFile is not a function

Using older version or incorrect import (wrong named export).

fix

Use `import { resolveConfigForFile } from 'format-imports'` and verify package version >=4.0.0.

SyntaxError: Unexpected token 'export'

Running format-imports CLI on a file that is not a module (e.g., CommonJS file with exports).

fix

Ensure the file is valid JavaScript/TypeScript; format-imports expects module files.

Error: Configuration file not found

No configuration file (e.g., .importsorter) exists in the project root.

fix

Create a configuration file, or use the API with explicit options.

Upgrade

Version history

4.0.8latest on npm

Audit

Dependencies

@typescript/vfsrequiredUsed for TypeScript type checking and type-only import detection.

prettieroptionalOptional dependency for Prettier integration when formatting config files.

Agent activity

29 hits · last 30 days

Bingbot

node

Resources

githubhttps://github.com/daidodo/format-imports ↗

packageformat-imports ↗

homepagehttps://github.com/daidodo/format-imports#readme ↗