@unlrn/naming-convention

Hybrid naming-convention package for TypeScript projects using Oxlint + ESLint.

• Use Oxlint (with JS plugins) for import-export-alias-naming.
• Use ESLint as fallback for type-aware @typescript-eslint/naming-convention.

Why

@typescript-eslint/naming-convention handles most naming policy needs, but it does not target renamed import/export aliases precisely. This package adds that missing alias rule while keeping your existing naming-convention policy.

Install

bun add -D @unlrn/naming-convention

Public Exports

• @unlrn/naming-convention/plugin — ESLint-compatible plugin (also usable by Oxlint JS plugins)
• @unlrn/naming-convention/eslint — ESLint flat-config presets and composable helpers
• @unlrn/naming-convention/oxlint — typed helpers for oxlint.config.ts

Note: files in dist/ other than these export targets are internal build artifacts.

Oxlint (Primary)

Use oxlint.config.ts and load the plugin via jsPlugins.

// oxlint.config.ts
import { defineConfig } from "oxlint";
import { createOxlintNamingConfig } from "@unlrn/naming-convention/oxlint";

const naming = createOxlintNamingConfig();

export default defineConfig({
  jsPlugins: naming.jsPlugins,
  rules: {
    ...naming.rules,
  },
});

By default this enables:

• plugin alias: naming
• rule: naming/import-export-alias-naming
• options: { selector: ['importAlias', 'exportAlias'], format: ['snake_case', 'UPPER_CASE'] }

ESLint

Three composable exports are available from @unlrn/naming-convention/eslint.

Combined preset (default)

Includes both @typescript-eslint/naming-convention and import-export-alias-naming.

// eslint.config.mjs
import namingConfig from "@unlrn/naming-convention/eslint";

export default [...namingConfig];

Or use createEslintNamingConfig to customise or opt out of either rule:

import { createEslintNamingConfig } from "@unlrn/naming-convention/eslint";

export default createEslintNamingConfig({
  // customise alias rule options
  alias: {
    selector: ["importAlias", "exportAlias"],
    format: ["snake_case"],
  },
  // or disable alias rule entirely
  // alias: false,

  // disable @typescript-eslint/naming-convention
  // ts: false,
});

Alias rule only

Just the import-export-alias-naming rule, without @typescript-eslint/naming-convention. Useful if you already have a ts naming config elsewhere.

import { createEslintAliasConfig } from "@unlrn/naming-convention/eslint";

export default createEslintAliasConfig({
  selector: ["importAlias", "exportAlias"],
  format: ["snake_case"],
});

@typescript-eslint/naming-convention only

Just the ts naming preferences, without the alias rule.

import { createEslintTsNamingConfig } from "@unlrn/naming-convention/eslint";

export default createEslintTsNamingConfig();

Rule API — import-export-alias-naming (v1)

Targets renamed import and export aliases only. Non-renamed specifiers (import { foo } from ...) are ignored.

Options

| Option | Type | Default | | ---------- | ---------------------------------------------- | -------------------------------- | | selector | 'importAlias' \| 'exportAlias' \| Array<...> | ['importAlias', 'exportAlias'] | | format | Array<NamingFormat> \| null | ['snake_case', 'UPPER_CASE'] | | custom | { regex: string; match: boolean } | — | | filter | string \| { regex: string; match: boolean } | — |

NamingFormat values: camelCase · strictCamelCase · PascalCase · StrictPascalCase · snake_case · UPPER_CASE

• format: null — disables format checking (useful when using custom alone)
• filter — only check aliases whose name matches (string is treated as a regex pattern)
• custom — additional regex constraint applied after format

Reserved keys (leadingUnderscore, trailingUnderscore, prefix, suffix) are accepted for forward compatibility but reported as unsupported in v1.

Examples

// importAlias only, camelCase or PascalCase
{ selector: 'importAlias', format: ['camelCase', 'PascalCase'] }

// exportAlias only, custom regex must match
{ selector: 'exportAlias', format: null, custom: { regex: '^[a-z]', match: true } }

// skip aliases that start with underscore
{ selector: ['importAlias', 'exportAlias'], format: ['snake_case'], filter: { regex: '^_', match: false } }

Development

bun run build
bun run check
bun run test