typescript-import-style

TypeScript Import Style Guidelines (Merge Conflict Reduction)

Import formatting and ordering rules to minimize merge conflicts when multiple developers or parallel agents modify the same file.

CRITICAL: One Import Per Line

When importing multiple items from a module, put EACH import on its own line:

// CORRECT - merge-friendly (each on separate line)
import {
  alpha,
  beta,
  gamma,
} from 'some-module';

// WRONG - causes merge conflicts
import { alpha, beta, gamma } from 'some-module';

This is enforced by Prettier with printWidth: 80. With one-per-line, Git can merge imports from parallel changes without conflicts.

Import Order (Top to Bottom)

1. Node.js built-ins (e.g., import fs from 'fs', import path from 'path')
2. External packages (e.g., import React from 'react', import express from 'express')
3. Internal aliases (e.g., import { util } from '@/utils')
4. Parent directory imports (e.g., import { Parent } from '../Parent')
5. Sibling imports (e.g., import { Sibling } from './Sibling')
6. Index imports (e.g., import { thing } from './index')
7. Type-only imports (e.g., import type { MyType } from './types')

Within Each Group

• Sort imports alphabetically by module path (case-insensitive)
• Sort named imports alphabetically within braces
• Sort export statements alphabetically

Spacing

• Add one blank line between import groups
• No blank lines within a group

Complete Example

// Node.js built-ins
import fs from 'fs';
import path from 'path';

// External packages
import express from 'express';
import React from 'react';

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

// Parent imports
import { BaseService } from '../BaseService';

// Sibling imports (one per line when multiple)
import {
  helperA,
  helperB,
  helperC,
} from './helpers';
import { utils } from './utils';

// Type imports (one per line when multiple)
import type { Config } from '@/types';
import type {
  Request,
  Response,
} from 'express';