Import Processing

Core preprocessing functionality that analyzes and sorts import statements according to configured patterns using Babel AST processing.

Main Preprocessor Functions

preprocessor

Core preprocessing logic that sorts imports according to configuration options.

function preprocessor(code: string, options: PrettierOptions): string

Parameters:

• code: Source code string to process
• options: Prettier options including plugin configuration

Returns: Processed code string with sorted imports

The core preprocessing function that:

1. Parses code using Babel parser with configured plugins
2. Extracts import declarations and directives from AST
3. Applies configured sorting and grouping rules
4. Generates formatted code with sorted imports

Usage Example

import { preprocessor } from '@trivago/prettier-plugin-sort-imports';

const sortedCode = preprocessor(sourceCode, {
  importOrder: ["^@core/(.*)$", "^[./]"],
  importOrderSeparation: true,
  importOrderSortSpecifiers: true,
  // ... other Prettier options
});

defaultPreprocessor

Default preprocessor that handles most file types while skipping Vue and Svelte files.

function defaultPreprocessor(code: string, options: PrettierOptions): string

Parameters:

• code: Source code string to process
• options: Prettier options including filepath information

Returns: Processed code string or original code for Vue/Svelte files

Conditional preprocessor that:

• Returns original code unchanged for .svelte and .vue files
• Calls main preprocessor function for all other file types

This allows framework-specific preprocessors to handle their respective file types.

Processing Pipeline

AST Extraction

The preprocessor uses Babel to parse source code and extract relevant nodes:

interface ASTExtractionResult {
  importNodes: ImportDeclaration[];
  directives: Directive[];
}

function extractASTNodes(ast: Program): ASTExtractionResult

Extracts import declarations and directives (like "use strict") from the parsed AST while preserving their original positions and comments.

Import Sorting

Core sorting logic that groups and orders imports according to configuration:

type GetSortedNodes = (
  nodes: ImportDeclaration[],
  options: Pick<
    PrettierOptions,
    | 'importOrder'
    | 'importOrderCaseInsensitive' 
    | 'importOrderSeparation'
    | 'importOrderGroupNamespaceSpecifiers'
    | 'importOrderSortSpecifiers'
    | 'importOrderSideEffects'
  >
) => ImportOrLine[]

function getSortedNodes(
  importNodes: ImportDeclaration[], 
  options: SortingOptions
): ImportOrLine[]

Processing Steps:

1. Group Matching: Matches imports against importOrder patterns
2. Third-party Handling: Identifies and positions unmatched imports
3. Specifier Sorting: Sorts named imports if enabled
4. Namespace Grouping: Groups namespace imports if enabled
5. Separation: Adds newline nodes between groups if enabled

Code Generation

Final step that generates formatted code from sorted AST nodes:

function getCodeFromAst(
  nodes: Statement[],
  directives: Directive[],
  originalCode: string,
  interpreter?: InterpreterDirective | null,
  options?: Pick<PrettierOptions, 'importOrderImportAttributesKeyword'>
): string

Parameters:

• nodes: AST statement nodes including imports and newline separators
• directives: Preserved directives from original code
• originalCode: Original source code for fallback
• interpreter: Shebang or interpreter directive
• options: Code generation options

Returns: Final formatted code string

Utility Functions

Parser Plugin Processing

function getExperimentalParserPlugins(
  importOrderParserPlugins?: ImportOrderParserPlugin[]
): ParserPlugin[]

Processes plugin configuration and returns Babel parser plugins, handling both simple plugin names and plugins with options.

Sort Ignore Detection

function isSortImportsIgnored(importNodes: ImportDeclaration[]): boolean

Checks if import sorting should be skipped based on the presence of // sort-imports-ignore comments.

Comment Adjustment

function adjustCommentsOnSortedNodes(
  sortedNodes: ImportOrLine[],
  originalNodes: ImportDeclaration[],
  sourceCode: string
): ImportOrLine[]

Preserves and repositions comments associated with import statements after sorting to maintain code documentation.

Import Specifier Sorting

function getSortedImportSpecifiers(
  importDeclaration: ImportDeclaration,
  options: Pick<PrettierOptions, 'importOrderSortSpecifiers'>
): ImportDeclaration

Sorts named imports within individual import statements when importOrderSortSpecifiers is enabled.

Import Node Extraction

function getImportNodes(code: string, options?: ParserOptions): ImportDeclaration[]

Parameters:

• code: Source code string to parse
• options: Optional Babel parser configuration options

Returns: Array of import declaration AST nodes

Parses source code and extracts all import declarations, excluding imports inside TypeScript module declarations. Useful for custom import processing outside the main plugin workflow.

Usage Example

import { getImportNodes } from '@trivago/prettier-plugin-sort-imports';

const importNodes = getImportNodes(sourceCode, {
  plugins: ['typescript', 'jsx']
});

Node Removal Utility

function removeNodesFromOriginalCode(
  code: string,
  nodes: (Statement | CommentBlock | Directive | CommentLine | ImportDeclaration | InterpreterDirective)[]
): string

Parameters:

• code: Original source code string
• nodes: Array of AST nodes to remove from the code

Returns: Modified code string with specified nodes removed

Removes specified AST nodes from the original source code by matching their text content. Used internally for clean code generation but can be useful for custom preprocessing.

Natural Sorting Utility

export { naturalSort };

Re-exported natural sorting function from the javascript-natural-sort library, used internally for import sorting but available for custom sorting needs.

Processing Constants

Special Keywords

const THIRD_PARTY_MODULES_SPECIAL_WORD = '<THIRD_PARTY_MODULES>';
const THIRD_PARTY_TYPES_SPECIAL_WORD = '<THIRD_PARTY_TS_TYPES>';  
const TYPES_SPECIAL_WORD = '<TS_TYPES>';

Special placeholder strings used in importOrder configuration to control positioning of automatically detected import groups.

Parser Plugin Constants

const flow: ParserPlugin = 'flow';
const typescript: ParserPlugin = 'typescript';
const jsx: ParserPlugin = 'jsx';

Predefined parser plugin constants for common Babel plugins used in import processing.

Node Type Identifiers

const chunkSideEffectNode = 'side-effect-node';
const chunkSideOtherNode = 'other-node';

Constants used internally to categorize different types of import nodes during processing.

Formatting Constants

const newLineCharacters = '\n\n';
const sortImportsIgnoredComment = 'sort-imports-ignore';

const newLineNode: ExpressionStatement;

Constants for consistent formatting and special comment detection. The newLineNode is an AST node representing blank line separators between import groups.

Error Handling

The preprocessor includes comprehensive error handling and safety mechanisms:

Framework Dependency Fallbacks

Svelte Parser Loading:

function createSvelteParsers(): { parsers?: any } | {}

Gracefully handles missing Svelte dependencies:

try {
  var { parsers } = require('prettier-plugin-svelte');
} catch {
  return {}; // Returns empty object if plugin unavailable
}

Parser Plugin Configuration Errors

JSON Parsing Safety:

function getExperimentalParserPlugins(
  importOrderParserPlugins: string[]
): ParserPlugin[]

Validates plugin configuration with detailed error messages:

try {
  plugin = JSON.parse(pluginNameOrJson) as ParserPluginWithOptions;
} catch (e) {
  throw Error('Invalid JSON in importOrderParserPlugins: ' + pluginNameOrJson);
}

Processing Safety Mechanisms

• Empty Import Check: Returns original code unchanged if no imports are found
• Ignore Comment Check: Skips processing when // sort-imports-ignore comment is present
• TypeScript Module Exclusion: Safely excludes imports inside TypeScript module declarations
• Parser Error Handling: Falls back to original code on Babel parse errors
• AST Generation Safety: Preserves original structure on code generation failures

Framework-Specific Error Handling

• Missing Vue Dependencies: Graceful fallback when @vue/compiler-sfc unavailable
• Missing Svelte Dependencies: Graceful fallback when prettier-plugin-svelte unavailable
• Invalid SFC Structure: Handle malformed Vue or Svelte component files safely
• Framework Parse Errors: Preserve original code on framework-specific parse failures

Configuration Validation

• Invalid RegExp Patterns: Reports clear errors for malformed importOrder patterns
• Plugin Option Validation: Validates JSON strings in parser plugin configurations
• Type Safety: Comprehensive TypeScript typing prevents configuration mismatches

Integration with Prettier

The preprocessor integrates seamlessly with Prettier's pipeline:

1. Parser Registration: Extends existing Prettier parsers
2. Option Integration: Uses Prettier's option system
3. File Type Handling: Respects Prettier's file type detection
4. Source Map Preservation: Maintains debugging information where possible