Import Polisher

Automatically beautify and reorganize import statements while guaranteeing zero changes to runtime behavior.

Features

• Smart Import Grouping — Organizes imports by category (builtin, external, sibling, parent, internal, side-effect)
• Named Import Sorting — Sorts members inside { } braces by length (shorter first)
• Multi-Language Support — TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C/C++, Ruby, Scala, Elixir
• AST-Based Parsing — Uses syntax trees for accurate import detection (falls back to regex if AST fails)
• Comment Preservation — Comments attached to imports remain attached after reordering
• Zero Runtime Changes — Never modifies executable code
• Deterministic Output — Running multiple times produces the same result
• Format on Save — Automatically beautifies imports when you save (Ctrl+S)
• Format on Paste — Optionally beautifies imports after pasting (Ctrl+V)

Default Behavior

With default settings (sortOrder: "length", sortNamedImports: true, groupByCategory: false), Import Polisher:

1. Sorts imports by length (shorter module names first)
2. Sorts named imports inside { } by length
3. Puts all imports together (no group separation)

Example: Default Changes

Before:

import { z, a, m } from 'zod';
import fs from 'fs';
import { sortImports } from './utils';
import path from 'path';
import express from 'express';
import { helper } from '@/helpers';
import './polyfills';

After:

import fs from 'fs';
import './polyfills';
import path from 'path';
import { a, m, z } from 'zod';
import express from 'express';
import { helper } from '@/helpers';
import { sortImports } from './utils';

What changed:

• fs and path moved to the top (shorter names)
• { z, a, m } became { a, m, z } (sorted by length)
• All imports sorted together by module name length

Example: Python

Before:

from mypackage.utils import helper, formatter
import json
from .models import User
import sys
from typing import Optional, List, Dict

After:

import json
import sys
from mypackage.utils import formatter, helper
from typing import Dict, List, Optional
from .models import User

What changed:

• Builtins (json, sys) moved to the top
• Named imports sorted by length (Dict, List, Optional)

Example: With Group Spacing

Enable groupSpacing: true to add blank lines between import groups:

Before:

import { z, a, m } from 'zod';
import fs from 'fs';
import { sortImports } from './utils';
import path from 'path';
import express from 'express';
import { helper } from '@/helpers';

After:

import fs from 'fs';
import path from 'path';

import express from 'express';

import { a, m, z } from 'zod';

import { helper } from '@/helpers';

import { sortImports } from './utils';

Example: Alphabetical Sort

Set sortOrder: "alphabetical" for A-Z ordering:

Before:

import { zebra, apple, mango } from 'fruits';
import express from 'express';
import path from 'path';

After:

import path from 'path';
import express from 'express';
import { apple, mango, zebra } from 'fruits';

Example: TypeScript with Type Imports

Before:

import { useState, useEffect, type ReactNode, type FC } from 'react';
import express from 'express';
import { z } from 'zod';
import fs from 'fs';

After:

import fs from 'fs';
import express from 'express';
import { z } from 'zod';
import { FC, ReactNode, useEffect, useState, type FC, type ReactNode } from 'react';

How Import Polisher Rearranges Imports

Import Polisher uses a two-phase sorting algorithm:

Phase 1: Group Classification

Each import is classified into one of 6 groups based on the module specifier:

Phase 2: Sorting Within Groups

After grouping, imports are sorted within each group based on the sortOrder setting:

Phase 3: Named Specifier Sorting

If sortNamedImports is true, members inside { } braces are also sorted:

Before:

import { zebra, apple, mango } from 'fruits';

After:

import { apple, mango, zebra } from 'fruits';

Configuration Options

Settings JSON

Add to your settings.json:

{
  "importPolisher.sortOrder": "length",
  "importPolisher.groupByCategory": false,
  "importPolisher.groupOrder": [
    "builtin",
    "external",
    "sibling",
    "parent",
    "internal",
    "side-effect"
  ],
  "importPolisher.groupSpacing": false,
  "importPolisher.sortNamedImports": true,
  "importPolisher.useAST": true,
  "importPolisher.debug": false,
  "importPolisher.enabledLanguages": []
}

Usage

Keyboard Shortcuts

Commands

Open the Command Palette (Ctrl+Shift+P) and type:

Supported Languages

Installation

From .vsix

code --install-extension import-polisher-0.0.1.vsix

From Source

git clone https://github.com/your-username/import-polisher.git
cd import-polisher
npm install
npm run build-extension
code --install-extension import-polisher-0.0.1.vsix

Or press F5 in VS Code to launch the Extension Development Host.

Architecture

src/
├── extension.ts           # Extension entry point
├── commands/              # VS Code command handlers
│   └── beautify.ts        # Beautify imports command
├── models/                # Data models and interfaces
│   └── import.ts          # Import types, groups, config
├── parsers/               # Language-specific parsers
│   ├── typescript-parser.ts  # TS/JS/TSX/JSX (AST)
│   ├── python-parser.ts      # Python (regex)
│   └── generic-parser.ts     # Other languages (regex)
├── sorters/               # Import and specifier sorting
│   └── import-sorter.ts      # Sorting algorithms
├── languages/             # Language registry
│   └── registry.ts        # Language configuration
├── services/              # Core services
│   └── formatter.ts       # Main formatting logic
├── settings/              # Configuration management
│   └── settings.ts        # VS Code settings reader
└── utils/                 # Utility functions
    └── logger.ts          # Debug logging

Development

npm install
npm run compile          # Compile once
npm run watch            # Watch mode (auto-recompile)
npm run lint             # Lint source files
npm run build-extension  # Package as .vsix

After packaging, install the built extension locally:

code --install-extension import-polisher-0.0.1.vsix

Contributing

We welcome contributions! For detailed instructions on development setup, testing, debugging, and publishing, see docs/CONTRIBUTING.md.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see LICENSE for details.