Registry / testing / prettier-plugin-organize-imports

prettier-plugin-organize-imports

library4.3.0jsnpmunverified

This Prettier plugin automates the organization of import statements within your JavaScript, TypeScript, JSX, TSX, and Vue files. It leverages the TypeScript language service API's `organizeImports` feature, which is the same logic used by VS Code's 'Organize Imports' action. The plugin sorts, combines, and removes unused imports, ensuring consistent import structures across your codebase and reducing merge conflicts related to import ordering. The current stable version is 4.3.0, with minor releases occurring periodically to address bug fixes, improve compatibility with `vue-tsc`, and introduce new configuration options like `organizeImportsTypeOrder`. A key differentiator is its reliance on the robust TypeScript language service for import logic, offering zero-config setup for Prettier v2 users and minimal configuration for Prettier v3. It acts by extending and overriding Prettier's built-in parsers, meaning it's incompatible with other plugins that attempt to do the same for `babel`, `typescript`, or `vue` parsers. It primarily manages peer dependencies `prettier`, `typescript`, and optionally `vue-tsc` for Vue.js support.

testing

npm install prettier-plugin-organize-imports

github ↗package ↗

INSTALL

IMPORT

SIG · PRETTIER-PLUGIN-OR

prettier-plugin-organize-imports

testingjavascriptv4.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

Prettier Plugin Configuration (Prettier v3+)

✓ { "plugins": [ "prettier-plugin-organize-imports" ] }

✗ /* No explicit configuration, relying on automatic discovery */

For Prettier v3 and later, automatic plugin discovery was removed. You must explicitly list `prettier-plugin-organize-imports` in your Prettier configuration's `plugins` array.

Prettier Plugin Configuration (Prettier v2)

✓ /* No explicit configuration needed for Prettier v2; automatic discovery is enabled by default. */

✗ { "plugins": [ "prettier-plugin-organize-imports" ] }

With Prettier v2, the plugin is automatically discovered if installed. Explicitly listing it is unnecessary unless using package managers like Yarn PnP that don't support automatic discovery.

Configuration Option: organizeImportsSkipDestructiveCodeActions

✓ { "organizeImportsSkipDestructiveCodeActions": true }

This option, when set to `true`, prevents destructive code actions such as removing unused imports, keeping only sorting and combining behavior.

This quickstart demonstrates installing the plugin and configuring Prettier v3 to automatically organize imports in a TypeScript project upon formatting.

{ "name": "my-project", "version": "1.0.0", "devDependencies": { "prettier": "^3.0.0", "typescript": "^5.0.0", "prettier-plugin-organize-imports": "^4.0.0" } } // .prettierrc.json { "plugins": [ "prettier-plugin-organize-imports" ] } // src/main.ts (before formatting) import { z } from "./utils"; import type { Bar } from './types'; import { foo } from "./helpers"; const myVar: Bar = foo + z; console.log(myVar); // Terminal command to format: // npx prettier --write "src/**/*.ts"

Debug

Known issues

breakingPrettier v3 removed automatic plugin discovery. Users must explicitly configure the plugin in their `.prettierrc` by adding `"prettier-plugin-organize-imports"` to the `plugins` array.

fix

Update your Prettier configuration file (e.g., `.prettierrc.json`) to include `{"plugins": ["prettier-plugin-organize-imports"]}`.

affects: >=3.0.0

breakingVersion 4.0.0 introduced a breaking change for Vue support, replacing `@volar/vue-typescript` and `@volar/vue-language-plugin-pug` with `vue-tsc` and `@vue/language-plugin-pug` respectively, as part of the Volar 2 upgrade.

fix

Remove `@volar/vue-typescript` and `@volar/vue-language-plugin-pug` from your dependencies and install `vue-tsc` and `@vue/language-plugin-pug` instead. Update your `vueCompilerOptions` if using Pug.

affects: >=4.0.0

breakingVersions 4.1.0 and 4.2.0 bumped the `vue-tsc` peer dependency range due to breaking changes in its API. Ensure `vue-tsc` is compatible with the installed plugin version.

fix

Upgrade `vue-tsc` simultaneously with `prettier-plugin-organize-imports` to meet the peer dependency requirements (e.g., `npm i -D prettier-plugin-organize-imports vue-tsc@^3.0.0`).

affects: >=4.1.0

gotchaThis plugin inherits, extends, and overrides Prettier's built-in parsers for `babel`, `babel-ts`, `typescript`, and `vue`. It is incompatible with other Prettier plugins that attempt to do the same, as only the last loaded plugin for a given parser will function.

fix

Ensure `prettier-plugin-organize-imports` is the only plugin overriding these specific parsers in your Prettier configuration. Adjust plugin order if necessary, understanding that the last one loaded wins.

affects: >=1.0.0

gotchaFor React projects, if `React` is imported but seemingly unused (only needed for JSX factory), the plugin might remove it. To prevent this, ensure `jsx` option is set to `react` in your `tsconfig.json`.

fix

Add or update the `jsx` compiler option in your `tsconfig.json` to `"react"`.

affects: >=1.0.0

gotchaWhen integrating with ESLint or other linters, disable any import order rules or plugins (e.g., `eslint-plugin-import`'s `order` rule) to avoid conflicts with Prettier's import organization.

fix

Consult Prettier's documentation on 'Integrating with Linters' and disable conflicting import-related rules in your linter configuration.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Prettier is unable to load the plugin 'prettier-plugin-organize-imports' because it uses a deprecated feature. Please update the plugin.

Prettier v3 no longer supports automatic plugin discovery; plugins must be explicitly configured.

fix

Add `prettier-plugin-organize-imports` to the `plugins` array in your Prettier configuration file (e.g., `.prettierrc.json`).

Imports used in Vue templates are being removed by the plugin.

Older versions of the plugin or `@volar/vue-typescript` had issues with template-only import detection.

fix

Ensure you are using `prettier-plugin-organize-imports` v3.1.1 or later, and that your `@volar/vue-typescript` (or `vue-tsc` for v4+) peer dependency meets the specified version requirements.

Volar compiler options not found or Vue files not being processed correctly.

Incompatible `vue-tsc` versions or incorrect Volar package setup after plugin v4.0.0.

fix

Ensure `vue-tsc` is installed and meets the plugin's peer dependency requirements (v2.1.0 or v3.0.0+). If using Pug templates, install `@vue/language-plugin-pug` and configure it in `vueCompilerOptions`.

Performance regression when formatting large files or many files.

A performance regression was introduced in `prettier-plugin-organize-imports` v3.2.0.

fix

Upgrade to `prettier-plugin-organize-imports` v3.2.2 or higher, which includes a fix for the performance regression.

Upgrade

Version history

4.3.0latest on npm

Audit

Dependencies

prettierrequiredRequired peer dependency for Prettier functionality.

typescriptrequiredRequired peer dependency as the plugin relies on the TypeScript language service API for import organization.

vue-tscoptionalOptional peer dependency for Vue.js file support, compatible with Vue 2 and 3.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/simonhaenisch/prettier-plugin-organize-imports ↗

packagehttps://www.npmjs.com/package/prettier-plugin-organize-imports ↗