Prettier Plugin: Organize Imports

4.3.0 · active · verified Sun Apr 19

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.

Common errors

```
Error: Prettier is unable to load the plugin 'prettier-plugin-organize-imports' because it uses a deprecated feature. Please update the plugin.
```
cause 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.
```
cause 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.
```
cause 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.
```
cause 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.

Warnings

breaking Prettier 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"]}`.
breaking Version 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.
breaking Versions 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`).
gotcha This 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.
gotcha For 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"`.
gotcha When 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.

Install

npm install prettier-plugin-organize-imports npm
yarn add prettier-plugin-organize-imports yarn
pnpm add prettier-plugin-organize-imports pnpm

Imports

Prettier Plugin Configuration (Prettier v3+)
wrong:
```
/* No explicit configuration, relying on automatic discovery */
```
correct:
```
{
  "plugins": [
    "prettier-plugin-organize-imports"
  ]
}
```
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)
wrong:
```
{
  "plugins": [
    "prettier-plugin-organize-imports"
  ]
}
```
correct:
```
/* No explicit configuration needed for Prettier v2; automatic discovery is enabled by default. */
```
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.

Quickstart

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"

view raw JSON →