Import Ordering

Import Ordering Fixes

Fixes for import statement organization. Consistent import ordering makes files scannable and dependency analysis easier.

Quick Start

Auto-fix all import ordering issues:

npx eslint --fix --rule 'import-x/order: error' src/

Or fix all files:

npx eslint --fix src/

Priority

P2 - Fix this sprint. Auto-fixable, improves code consistency.

Preferred Import Order

1. Node.js builtins (fs, path, crypto)
2. External packages (lodash, react, zod)
3. Internal aliases (@/utils, @/types, @/config)
4. Relative imports (./local, ../parent)
5. Type-only imports (last within each group)

Example

// 1. Node.js builtins
import fs from 'node:fs';
import path from 'node:path';

// 2. External packages
import lodash from 'lodash';
import { z } from 'zod';

// 3. Internal aliases
import { config } from '@/config';
import { logger } from '@/utils/logger';

// 4. Relative imports
import { helper } from './helper';
import { utils } from '../shared/utils';

// 5. Type-only imports
import type { Config } from '@/types';
import type { LocalType } from './types';

ESLint Configuration

Recommended Rule Config

// eslint.config.js
import importPlugin from 'eslint-plugin-import-x';

export default [
  {
    plugins: {
      'import-x': importPlugin,
    },
    rules: {
      'import-x/order': [
        'error',
        {
          groups: [
            'builtin',     // Node.js built-in modules
            'external',    // npm packages
            'internal',    // Aliased paths (@/)
            'parent',      // Parent imports (../)
            'sibling',     // Sibling imports (./)
            'index',       // Index imports (./)
            'type',        // Type imports
          ],
          pathGroups: [
            {
              pattern: '@/**',
              group: 'internal',
              position: 'before',
            },
          ],
          pathGroupsExcludedImportTypes: ['type'],
          'newlines-between': 'always',
          alphabetize: {
            order: 'asc',
            caseInsensitive: true,
          },
        },
      ],
    },
  },
];

Path Aliases Setup

Ensure your tsconfig.json has path aliases:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

Common Issues

Issue #13: import-x/order (14 occurrences)

Pattern: Imports not following group/alphabetical order.

// PROBLEM - wrong order
import { helper } from './helper';
import fs from 'fs';
import { config } from '@/config';
import lodash from 'lodash';

Fix: Auto-fix or manual reorder.

// SOLUTION
import fs from 'node:fs';

import lodash from 'lodash';

import { config } from '@/config';

import { helper } from './helper';

Scripts

Check Import Order

node scripts/check-imports.js /path/to/src

Fix Import Order

node scripts/fix-imports.js /path/to/file.ts

IDE Integration

VS Code Settings

Add to .vscode/settings.json:

{
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  },
  "typescript.preferences.importModuleSpecifier": "non-relative",
  "javascript.preferences.importModuleSpecifier": "non-relative"
}

WebStorm/IntelliJ

1. Settings > Editor > Code Style > TypeScript
2. Imports tab
3. Configure "Sort imports by groups"

Best Practices

Use Node Protocol

// GOOD - explicit Node.js module
import fs from 'node:fs';
import path from 'node:path';

// AVOID - ambiguous
import fs from 'fs';

Separate Type Imports

// GOOD - type imports separated
import { UserService } from './user-service';
import type { User, UserRole } from './types';

// AVOID - mixed
import { UserService, User, UserRole } from './user-service';

Avoid Deep Relative Imports

// AVOID - hard to read and maintain
import { config } from '../../../config/settings';

// GOOD - use path alias
import { config } from '@/config/settings';

Barrel File Imports

// GOOD - import from barrel
import { User, Order, Product } from '@/models';

// AVOID - importing from individual files
import { User } from '@/models/user';
import { Order } from '@/models/order';
import { Product } from '@/models/product';

Troubleshooting

ESLint Not Fixing Imports

1. Ensure eslint-plugin-import-x is installed
2. Check plugin is configured in flat config
3. Run with --fix flag

Path Aliases Not Recognized

1. Verify tsconfig.json paths
2. Add eslint-import-resolver-typescript if using TypeScript
3. Configure resolver in ESLint:

{
  settings: {
    'import-x/resolver': {
      typescript: {
        project: './tsconfig.json',
      },
    },
  },
}

Conflicting with Prettier

Use eslint-config-prettier to disable conflicting rules:

npm install --save-dev eslint-config-prettier

import prettierConfig from 'eslint-config-prettier';

export default [
  // ... other configs
  prettierConfig,
];