prettier-plugin-imports

4.3.3 verified Sat Apr 25 auth: no javascript

A Prettier plugin for sorting import declarations by custom regular expression order, preserving side-effect import order, and combining imports from the same source. Based on @trivago/prettier-plugin-sort-imports with additional features like built-in module sorting, type import grouping, and improved comment handling. Version 4.3.3 (latest) supports Vue SFC, Astro files, and import assertions. Requires Prettier >=3 and optionally @vue/compiler-sfc for Vue support. Works with TypeScript, JavaScript, JSX, and Flow. Ships with TypeScript type definitions.

Common errors

error Cannot find module 'prettier-plugin-imports' ↓

cause The plugin is not installed or not correctly resolved.

fix

Ensure package is installed: npm install -D prettier prettier-plugin-imports

error TypeError: prettier-plugin-imports: unknown option `importOrderSeparation` ↓

cause Deprecated option still present in config.

fix

Remove importOrderSeparation; use empty strings in importOrder array to separate groups.

error Error: prettier-plugin-imports: `importOrderParsers` must be an array of strings ↓

cause The option is incorrectly set (e.g., a single string).

fix

Use array format: importOrderParsers: ['typescript', 'jsx']

error Module parse error: Unexpected token (1:0) (prettier-plugin-imports) ↓

cause The `importOrderParsers` does not include a parser that matches the file type (e.g., Vue files need 'vue').

fix

Add appropriate parser to importOrderParsers: e.g., 'vue' for .vue files.

Warnings

breaking v4.0 requires Prettier >=3. If you are on Prettier 2.x, upgrading to Prettier 3 is necessary. ↓

fix Upgrade Prettier to version 3 or later: npm install -D prettier@^3

breaking The option `importOrderSeparation` was removed in v4. Use empty strings in `importOrder` array to separate groups. ↓

fix Remove `importOrderSeparation` option and add empty strings in `importOrder` to create separation.

breaking The option `importOrderGroupNamespaceSpecifiers` was removed in v4. ↓

fix Remove the option; namespace imports are sorted with their groups.

deprecated Option `importOrderSortIndividualImports` is deprecated and will be removed in a future version. ↓

fix Remove the option; imports are sorted per group as defined in `importOrder`.

gotcha The plugin does not sort imports inside side-effect imports; those are preserved in order. ↓

fix Side-effect imports (e.g., `import 'module'`) remain in place; only named/default imports are sorted.

gotcha By default, 'node:builtin' imports are not sorted to the top unless `<BUILTIN_MODULES>` keyword is included in `importOrder`. ↓

fix Add `'<BUILTIN_MODULES>'` to the beginning of your `importOrder` array to move built-ins to top.

Install

npm install prettier-plugin-imports

yarn add prettier-plugin-imports

pnpm add prettier-plugin-imports

Imports

PrettierConfig

wrong

import { PrettierConfig } from 'prettier-plugin-imports'; (type only import is correct, value import is wrong)

correct

import type { PrettierConfig } from 'prettier-plugin-imports';

TypeScript users should use type-only import for the config type.

PrettierConfig (usage)

wrong

None common

correct

module.exports = /** @type {import('prettier-plugin-imports').PrettierConfig} */ ({...});

In JavaScript files, use JSDoc to type the config object as shown.

Plugin setup (CommonJS)

wrong

module.exports = { plugin: 'prettier-plugin-imports', ... }; (incorrect property name)

correct

module.exports = { plugins: ['prettier-plugin-imports'], ... };

The plugin is loaded by name; no explicit import is needed in Prettier config.

Plugin setup (ESM)

wrong

module.exports = { plugins: ['prettier-plugin-imports'], ... }; (if config is ESM)

correct

export default { plugins: ['prettier-plugin-imports'], ... };

Use ESM syntax (export default) when working with ESM Prettier config files.

Quickstart

Shows installation, Prettier config setup with importOrder and importOrderParsers, and a sample input/output demonstrating import sorting.

// Install: npm install -D prettier prettier-plugin-imports
// prettier.config.js
/** @type {import('prettier-plugin-imports').PrettierConfig} */
module.exports = {
  printWidth: 80,
  tabWidth: 2,
  semi: true,
  singleQuote: true,
  trailingComma: 'all',
  importOrder: [
    '^@core/(.*)$',
    '',
    '^@server/(.*)$',
    '^@ui/(.*)$',
    '',
    '^[./]'
  ],
  importOrderParsers: ['typescript', 'jsx', 'decorators-legacy'],
  importOrderTSVersion: '5.0.0'
};

// Input: 'src/index.ts'
import { logger } from '@core/logger';
import { createServer } from '@server/node';
import { Alert } from '@ui/Alert';
import { debounce } from 'lodash';
import { Message } from './Message';
import 'core-js/stable';

// Run: npx prettier --write src/index.ts
// Output will sort and group imports per importOrder, preserving side-effect order.