or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

Prettier Plugin Sort Imports

@ianvs/prettier-plugin-sort-imports is a Prettier plugin that automatically sorts import declarations according to customizable Regular Expression patterns while preserving side-effect import order. It extends the functionality of @trivago/prettier-plugin-sort-imports with enhanced features including the ability to combine imports from the same source, merge type and value imports for TypeScript 4.5.0+, group type imports with

<TYPES>

keyword, prioritize Node.js builtin modules with

<BUILTIN_MODULES>

keyword, handle comments around imports correctly, and provide flexible import order separation.

Package Information

Package Name: @ianvs/prettier-plugin-sort-imports
Package Type: npm
Language: TypeScript

Installation:

npm install @ianvs/prettier-plugin-sort-imports

Core Imports

This is a Prettier plugin, so it doesn't export functions for direct import. Instead, it integrates with Prettier's plugin system automatically when installed and configured.

Basic Usage

Installation and Configuration

Add to your Prettier configuration:

{
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
  "importOrder": [
    "^@core/(.*)$",
    "^@server/(.*)$", 
    "^@ui/(.*)$",
    "^[./]"
  ]
}

Example Input/Output

Input:

import { logger } from '@core/logger';
import React, { FC, useEffect } from 'react';
import { reduce, debounce } from 'lodash';
import { Alert } from '@ui/Alert';
import { Message } from '../Message';
import { createServer } from '@server/node';

Output:

import { debounce, reduce } from 'lodash';
import React, { FC, useEffect } from 'react';

import { createServer } from '@server/node';

import { logger } from '@core/logger';

import { Alert } from '@ui/Alert';

import { Message } from '../Message';

Capabilities

Plugin Configuration Options

The plugin accepts these configuration options through Prettier's options system:

interface PluginConfig {
  /**
   * A collection of Regular expressions in string format.
   * Default: ["<BUILTIN_MODULES>", "<THIRD_PARTY_MODULES>", "^[.]"]
   */
  importOrder?: string[];

  /**
   * Version of TypeScript in use in the project. Determines some output syntax.
   * Default: "1.0.0"
   */
  importOrderTypeScriptVersion?: string;

  /**
   * Should capitalization be considered when sorting imports?
   * Default: false
   */
  importOrderCaseSensitive?: boolean;

  /**
   * A collection of plugins for babel parser. The plugin uses prettier itself 
   * to figure out the parser but if that fails, you can use this field.
   * Default: ["typescript", "jsx"]
   */
  importOrderParserPlugins?: ImportOrderParserPlugin[];

  /**
   * Array of globs for side-effect-only imports that are considered safe to sort.
   * Default: []
   */
  importOrderSafeSideEffects?: string[];
}

type ImportOrderParserPlugin = 
  | Extract<ParserPlugin, string>
  | `[${string},${string}]`;

Import Order Patterns

The

importOrder

option accepts an array of regex patterns with special keywords:

/**
 * Special keywords for import ordering:
 */
type SpecialKeywords = 
  | "<BUILTIN_MODULES>"     // Node.js builtin modules (fs, path, etc.)
  | "<THIRD_PARTY_MODULES>" // Third-party packages from node_modules
  | "<TYPES>";              // TypeScript type-only imports

/**
 * Default import order configuration
 */
const DEFAULT_IMPORT_ORDER: string[] = [
  "<BUILTIN_MODULES>",
  "<THIRD_PARTY_MODULES>", 
  "^[.]" // Relative imports
];

Parser Configuration

The plugin extends Prettier's built-in parsers with import sorting preprocessing:

/**
 * Available parsers with sorting support
 */
interface ExtendedParsers {
  babel: Parser;         // JavaScript with Babel
  "babel-ts": Parser;    // TypeScript with Babel
  typescript: Parser;    // TypeScript
  flow: Parser;          // Flow
  vue: Parser;           // Vue SFC
  "ember-template-tag": Parser; // Ember (requires prettier-plugin-ember-template-tag)
  oxc: Parser;           // Oxc parser (requires @prettier/plugin-oxc)
  "oxc-ts": Parser;      // Oxc TypeScript (requires @prettier/plugin-oxc)
}

/**
 * Available printers
 */
interface ExtendedPrinters {
  "estree-oxc": Printer; // Oxc ESTree printer (requires @prettier/plugin-oxc)
}

Plugin Integration

The plugin automatically integrates with Prettier when installed. It exports the standard Prettier plugin interface:

/**
 * Main plugin exports for Prettier integration
 */
interface PrettierPlugin {
  /** Plugin configuration options schema */
  options: Record<keyof PluginConfig, SupportOption>;
  
  /** Extended parsers with import sorting preprocessing */
  parsers: ExtendedParsers;
  
  /** Extended printers for specific syntax support */
  printers: ExtendedPrinters;
}

Types

Core Configuration Types

/**
 * Combined configuration type for Prettier integration
 */
type PrettierConfig = PluginConfig & Config;

/**
 * Parser plugin specification for Babel
 */
type ImportOrderParserPlugin =
  | Extract<ParserPlugin, string>
  | `[${string},${string}]`;

Internal Processing Types

/**
 * Prettier options extended with plugin configuration
 */
interface PrettierOptions extends Required<PluginConfig>, RequiredOptions {}

/**
 * Subset of options that need normalization
 */
type NormalizableOptions = Pick<
  PrettierOptions,
  | 'importOrder'
  | 'importOrderParserPlugins'
  | 'importOrderTypeScriptVersion'
  | 'importOrderCaseSensitive'
  | 'importOrderSafeSideEffects'
> & Pick<Partial<PrettierOptions>, 'filepath'>;

/**
 * Import declarations grouped by type
 */
interface ImportChunk {
  nodes: ImportDeclaration[];
  type: ChunkType;
}

type ChunkType = 'other' | 'unsortable';

/**
 * Mapping of import groups to their declarations
 */
type ImportGroups = Record<string, ImportDeclaration[]>;

Module Declaration

The plugin extends Prettier's Options interface with its configuration:

declare module 'prettier' {
  interface Options extends PluginConfig {}
}

Configuration Examples

Basic Configuration

{
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
  "importOrder": [
    "^@core/(.*)$",
    "^@server/(.*)$",
    "^@ui/(.*)$", 
    "^[./]"
  ]
}

Advanced Configuration with Type Separation

{
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
  "importOrder": [
    "<TYPES>",
    "<TYPES>^[./]",
    "<BUILTIN_MODULES>",
    "<THIRD_PARTY_MODULES>",
    "^@core/(.*)$",
    "^[./]"
  ],
  "importOrderCaseSensitive": true,
  "importOrderTypeScriptVersion": "4.5.0",
  "importOrderParserPlugins": ["typescript", "jsx", "decorators-legacy"]
}

Safe Side Effects Configuration

{
  "plugins": ["@ianvs/prettier-plugin-sort-imports"],
  "importOrder": [
    "<BUILTIN_MODULES>",
    "<THIRD_PARTY_MODULES>",
    "^[./]"
  ],
  "importOrderSafeSideEffects": [
    "^server-only$",
    "^reflect-metadata$"
  ]
}

Preventing Import Sorting

Use

// prettier-ignore

to prevent specific imports from being sorted:

// prettier-ignore
import { sideEffectModule } from "./side-effect-module";

import { regularImport } from "./regular-module";