Import Sorter

1. Import Statement Fundamentals

Import statements form the foundational entry points of modern modular software architecture. In JavaScript, TypeScript, and ECMAScript Modules (ESM), an import declaration brings exported bindings from external packages, internal utilities, or standard library modules into the current lexical scope. Organising these declarations systematically ensures that application dependencies are explicit, maintainable, and readable.

The ECMAScript 2015 (ES6) specification introduced native module syntax to replace legacy script tag inclusions and asynchronous module definition wrappers. In an ES module, static import declarations are hoisted during compilation and evaluated before any top-level module code executes. Understanding the distinct syntactic variations of static imports is essential for configuring clean code formatting pipelines:

Module resolution algorithms determine how specifier strings (such as "react" or "@/components/Button") resolve to exact file system paths. Node.js uses a resolution algorithm that searches node_modules directories for bare specifiers and checks absolute or relative paths for file references. TypeScript extends this by resolving configured path aliases (such as @/*) defined in tsconfig.json.

2. Why Import Sorting Matters

As software applications grow in complexity, single files routinely import dozens of dependencies spanning framework modules, third-party packages, internal path aliases, relative utility files, TypeScript types, and stylesheet assets. Without automated import organization, module headers degenerate into chaotic, unorganized lists that impair developer productivity and introduce code quality hazards.

Adopting a deterministic import sorting strategy provides significant engineering advantages across the entire software development lifecycle:

3. Import Sorting Principles & Supported Classification Rules

ToolMono Import Sort Preview implements a deterministic, multi-tiered sorting model designed to reflect modern JavaScript, TypeScript, Python, Go, and Java best practices. Understanding how module specifiers are classified and ordered within each language ecosystem ensures predictable results.

4. Step-by-Step Tutorial: Using the Import Sort Preview Tool

ToolMono Import Sort Preview allows developers to instantly paste, analyze, sort, and inspect source code import blocks without installing local CLI tools or modifying project configurations. Follow this 6-step practical guide:

5. Practical Practical Before & After Examples

Review real-world examples demonstrating how ToolMono transforms disorganized import statements into clean, structured module headers across popular frameworks:

import { useState, useEffect } from "react";
import "./styles.css";
import { Button } from "@/components/ui/Button";
import fs from "fs";
import axios from "axios";
import { helper } from "../utils/helper";
import Link from "next/link";

import fs from "fs";

import axios from "axios";
import Link from "next/link";
import { useEffect, useState } from "react";

import { Button } from "@/components/ui/Button";

import { helper } from "../utils/helper";

import "./styles.css";

import { redirect } from "next/navigation";
import path from "node:path";
import { TOOL_MAP } from "@/metadata/tools";
import type { Metadata } from "next";
import { Card } from "@/components/ui/Card";
import { parseData } from "./utils";
import React from "react";

import path from "node:path";

import type { Metadata } from "next";
import { redirect } from "next/navigation";
import React from "react";

import { Card } from "@/components/ui/Card";
import { TOOL_MAP } from "@/metadata/tools";

import { parseData } from "./utils";

6. Production Code Examples: Programmatic AST Import Sorters

The following working code snippets illustrate how to build custom AST import parsers and sorters in JavaScript, TypeScript, and native ES Modules. These standalone examples demonstrate token classification logic without UI rendering code.

/**
 * JavaScript ES Module Import Parsing & Sorting Engine
 * Demonstrates AST token extraction, group classification, and alphabetical sorting.
 */
function parseAndSortJsImports(sourceCode) {
  const lines = sourceCode.split('\n');
  const importLines = [];
  const nonImportLines = [];

  // 1. Extract import statements vs non-import lines
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    const trimmed = line.trim();
    if (trimmed.startsWith('import ') || trimmed.startsWith('import"')) {
      // Extract module specifier
      const match = trimmed.match(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/);
      const modulePath = match ? (match[1] || match[2]) : '';
      const isSideEffect = !trimmed.includes('from') && !trimmed.includes('{');
      
      importLines.push({
        raw: line,
        modulePath,
        isSideEffect,
        originalIndex: i
      });
    } else {
      nonImportLines.push(line);
    }
  }

  // 2. Classify imports into groups
  const groups = {
    builtin: [],
    thirdParty: [],
    alias: [],
    relative: [],
    sideEffect: []
  };

  const builtins = new Set(['fs', 'path', 'crypto', 'http', 'https', 'events', 'os', 'stream', 'util']);

  importLines.forEach(item => {
    const mod = item.modulePath;
    if (item.isSideEffect) {
      groups.sideEffect.push(item);
    } else if (mod.startsWith('node:') || builtins.has(mod)) {
      groups.builtin.push(item);
    } else if (mod.startsWith('@/') || mod.startsWith('~/') || mod.startsWith('#')) {
      groups.alias.push(item);
    } else if (mod.startsWith('.')) {
      groups.relative.push(item);
    } else {
      groups.thirdParty.push(item);
    }
  });

  // 3. Sort each group alphabetically by module path
  const sortFn = (a, b) => a.modulePath.localeCompare(b.modulePath);
  groups.builtin.sort(sortFn);
  groups.thirdParty.sort(sortFn);
  groups.alias.sort(sortFn);
  groups.relative.sort(sortFn);

  // 4. Combine sorted groups with blank line separators
  const blocks = [];
  if (groups.builtin.length) blocks.push(groups.builtin.map(i => i.raw).join('\n'));
  if (groups.thirdParty.length) blocks.push(groups.thirdParty.map(i => i.raw).join('\n'));
  if (groups.alias.length) blocks.push(groups.alias.map(i => i.raw).join('\n'));
  if (groups.relative.length) blocks.push(groups.relative.map(i => i.raw).join('\n'));
  if (groups.sideEffect.length) blocks.push(groups.sideEffect.map(i => i.raw).join('\n'));

  return blocks.join('\n\n');
}

/**
 * TypeScript AST Import Classifier & Specifier Formatter
 * Formats TypeScript value imports and explicit type-only imports into organized blocks.
 */
export interface TSImportEntry {
  statement: string;
  moduleSpecifier: string;
  isTypeOnly: boolean;
  isSideEffect: boolean;
  kind: 'builtin' | 'third-party' | 'internal-alias' | 'relative' | 'side-effect';
}

export function classifyTypeScriptImports(importStatements: string[]): Record<string, string[]> {
  const result: Record<string, string[]> = {
    'Built-in Modules': [],
    'Third-party Packages': [],
    'Internal Aliases': [],
    'Relative Imports': [],
    'Side-effect Imports': []
  };

  const builtinModules = new Set(['fs', 'path', 'os', 'crypto', 'http', 'https', 'util']);

  for (const stmt of importStatements) {
    const trimmed = stmt.trim();
    const match = trimmed.match(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/);
    const mod = match ? (match[1] || match[2]) : '';
    const isSideEffect = !trimmed.includes('from') && !trimmed.includes('{');

    let category = 'Third-party Packages';
    if (isSideEffect) {
      category = 'Side-effect Imports';
    } else if (mod.startsWith('node:') || builtinModules.has(mod)) {
      category = 'Built-in Modules';
    } else if (mod.startsWith('@/') || mod.startsWith('~/') || mod.startsWith('#')) {
      category = 'Internal Aliases';
    } else if (mod.startsWith('.')) {
      category = 'Relative Imports';
    }

    result[category].push(stmt);
  }

  // Sort each array alphabetically by module string
  for (const cat in result) {
    result[cat].sort((a, b) => {
      const modA = (a.match(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/) || [])[1] || '';
      const modB = (b.match(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/) || [])[1] || '';
      return modA.localeCompare(modB);
    });
  }

  return result;
}

/**
 * Native ES Modules Static Import Block Formatter
 * Demonstrates clean module specifier sorting and blank line group separation.
 */
export function formatESMImportBlock(rawImports) {
  const parsed = rawImports.map(line => {
    const isSideEffect = line.trim().startsWith('import "') || line.trim().startsWith("import '");
    const moduleMatch = line.match(/from\s+['"]([^'"]+)['"]|import\s+['"]([^'"]+)['"]/);
    const moduleName = moduleMatch ? (moduleMatch[1] || moduleMatch[2]) : '';
    return { line, moduleName, isSideEffect };
  });

  // Separate side effects from value imports
  const sideEffects = parsed.filter(p => p.isSideEffect);
  const regularImports = parsed.filter(p => !p.isSideEffect);

  // Sort regular imports alphabetically by module name
  regularImports.sort((a, b) => a.moduleName.localeCompare(b.moduleName));

  const sortedLines = [...regularImports.map(p => p.line)];
  if (sideEffects.length > 0) {
    sortedLines.push(''); // blank line separator
    sortedLines.push(...sideEffects.map(p => p.line));
  }

  return sortedLines.join('\n');
}

7. Common Problems in Unorganized Import Headers

Unstructured import blocks degrade developer efficiency and introduce subtle bugs. Understanding common import code smells enables development teams to write cleaner, more resilient software:

8. Edge Cases & Complex Syntax Scenarios

Production software codebases present complex syntax edge cases that import sorters must handle safely:

• Very Large Source Files & Hundreds of Imports: Large index files or generated API client files can contain hundreds of import declarations. Sorters must process long import lists without blocking the browser thread.
• Unicode File Names & Non-ASCII Specifiers: Internationalized file paths or module specifiers containing Unicode characters require proper UTF-8 string comparison during alphabetical sorting.
• Path Aliases (`@/`, `~/`, `#subpath`): Node.js package subpath imports configured under "imports" in package.json and TypeScript aliases must be recognized as internal modules rather than third-party packages. Inspect your dependencies with the Package JSON Explorer.
• Mixed JavaScript and TypeScript Types: Files containing both runtime value imports and explicit import type declarations must categorize types cleanly to optimize transpilation.
• CSS and Asset Imports: Stylesheets (.css, .scss) and static media assets imported without specifiers are classified into dedicated side-effect or asset tiers.
• Comment Preservation: JSDoc blocks and inline comments attached to import statements must remain bound to their respective parent declarations during sorting movements.

9. Computational Performance & Browser Memory Management

ToolMono Import Sort Preview executes all AST parsing and import sorting tasks client-side within your web browser runtime. Understanding the performance characteristics of in-browser static analysis ensures smooth operation even when working with massive source files.

10. Best Practices for Codebase Import Management

Adhere to these developer best practices to maintain clean, organized import headers across your projects:

11. Frequently Asked Questions

12. Technical References & Official Specifications

For deeper technical study on ECMAScript modules, TypeScript type-only imports, and language module resolution specifications, consult these authoritative resources:

• ECMAScript Modules Specification: ECMA-262 Language Specification — Import Declarations (TC39 Standard)
• MDN JavaScript Modules Documentation: Mozilla Developer Network (MDN) — JavaScript Modules Guide
• TypeScript Handbook (Modules): Microsoft TypeScript Documentation — Modules & Type-Only Imports
• Node.js ES Modules Documentation: Node.js v20+ Documentation — ECMAScript Modules & Subpath Imports