Add <BUILTIN_MODULES> option for Node.js builtin modules

[sdotson]

Description

Implements the feature requested in #71 to add support for sorting Node.js builtin modules using the <BUILTIN_MODULES> placeholder in the importOrder array.

This PR introduces support for the <BUILTIN_MODULES> special word that allows users to explicitly control where Node.js builtin modules (both traditional fs, path etc. and new node:fs, node:path prefixed variants) appear in their import order.

Changes

• Special Word Support: Added <BUILTIN_MODULES> placeholder for use in importOrder array
• Builtin Detection: Created utility function to detect Node.js builtin modules using module.builtinModules
• Support for both formats: Handles both traditional (fs) and modern (node:fs) import styles
• Flexible Positioning: Users have full control over where builtin modules appear in their import order

Implementation Details

1. Detection Logic: Uses require('module').builtinModules to identify all Node.js builtin modules
2. Format Support: Recognizes both fs and node:fs import formats
3. Opt-in Behavior: Builtin modules are only sorted separately when <BUILTIN_MODULES> is included in importOrder
4. Flexible Placement: Can be positioned anywhere in the import order for maximum flexibility

Example Usage

Builtin modules at the top:

{
  "importOrder": ["<BUILTIN_MODULES>", "<THIRD_PARTY_MODULES>", "^@core/(.*)$", "^[./]"],
  "importOrderSeparation": true,
  "importOrderSortSpecifiers": true
}

Builtin modules after third-party:

{
  "importOrder": ["<THIRD_PARTY_MODULES>", "<BUILTIN_MODULES>", "^@core/(.*)$", "^[./]"]
}

Before:

import { app } from '@server/app';
import fs from 'fs';
import path from 'path';
import { readFile } from 'node:fs';
import express from 'express';
import { Button } from '@ui/Button';
import { logger } from './logger';

After (with builtin modules at top):

import fs from 'fs';
import { readFile } from 'node:fs';
import path from 'path';

import express from 'express';

import { app } from '@server/app';
import { Button } from '@ui/Button';

import { logger } from './logger';

Testing

• ✅ Comprehensive test coverage with 30 test suites
• ✅ Tests for builtin modules with placeholder
• ✅ Tests for builtin modules disabled (no placeholder)
• ✅ Tests for custom ordering scenarios
• ✅ Tests for both traditional and node: prefixed imports
• ✅ All tests passing (143 tests)

Backward Compatibility

This change is fully backward compatible:

• Without <BUILTIN_MODULES> in importOrder, builtin modules are treated as regular third-party imports
• Existing configurations continue to work unchanged
• No breaking changes to existing APIs

Documentation

• Updated type definitions with full JSDoc documentation
• Added comprehensive examples in README.md
• Updated CHANGELOG.md with usage examples
• Added .js extensions for ESM compatibility (v6)

Fixes #71

Checklist

• Feature implementation complete
• Comprehensive test coverage added
• Type definitions updated
• Documentation updated
• All tests passing
• Backward compatibility maintained
• Follows existing code conventions
• Rebased on v6 branch

[vladislavarsenev]

Hello @sdotson! I really like this feature, I think it might be useful. I'm wondering, is it possible to keep only <BUILTIN_MODULES>, without special option importOrderBuiltinModulesToTop in config? If someone wants to see them on top, they just would write config like

importOrder: ['<BUILTIN_MODULES>', ....]

otherwise they wouldn't mention it in importOrder at all and plugin wouldn't group plugins by this trait.

[sdotson]

Hello @sdotson! I really like this feature, I think it might be useful. I'm wondering, is it possible to keep only <BUILTIN_MODULES>, without special option importOrderBuiltinModulesToTop in config? If someone wants to see them on top, they just would write config like

importOrder: ['<BUILTIN_MODULES>', ....]

otherwise they wouldn't mention it in importOrder at all and plugin wouldn't group plugins by this trait.

Had a few hiccups with the v6 branch but I think everything is good now @vladislavarsenev

[vladislavarsenev]

Thank you for the changes! In order to merge, could you please perform yarn prettify?

[sdotson]

Thank you for the changes! In order to merge, could you please perform yarn prettify?

Sure thing

[vladislavarsenev]

Merged it, thank you @sdotson!