Skip to content

Removal of TypeScript Path Aliases and Transition to Relative Imports Across Project

Choose a tag to compare

View all tags
released this 28 Jul 05:27
· 51 commits to working since this release
v4.4.26
ae87a91

This release is focused on removing all custom TypeScript path aliases and updating the codebase to use explicit relative imports throughout production source files and tests. The primary motivation is to simplify the project's configuration, eliminate aliasing inconsistencies, and ensure compatibility and portability across different development and deployment environments.

Overview

The changes in this release are centered on refactoring the module resolution approach used in the project. Custom path aliases (such as @/api, @examples/*, @fjell/http-api) have been fully removed from both TypeScript and Vitest configurations. All import statements in both the core source files and test suites have been updated to exclusively use relative paths. This enhances portability, eases onboarding, and prevents potential bugs caused by misaligned or unresolved path aliases across tooling and deployment platforms.

Configuration Changes

  • TypeScript Configuration (tsconfig.json)

    • Removed all entries from the paths configuration:
      • @/* alias for src/ files
      • @examples/* alias for examples/ directory
      • @fjell/http-api alias
    • No longer relies on path aliasing for TypeScript builds; Node.js/EcmaScript relative paths are now used throughout.

  • Vitest Configuration (vitest.config.ts)

    • Removed resolve.alias property and related logic that mapped aliases for tests.
    • All test imports now reference target files via relative paths, enhancing test portability and simplicity.

Source Code and Test Refactoring

  • Production Source Files (src/api/*.ts, etc.)

    • Replaced all aliased imports (e.g., @/api, @/logger, @/errors) with direct relative imports (e.g., ../api, ../logger, ../errors).
    • Ensures that all modules rely solely on built-in/relative path resolution, reducing complexity and build tooling dependency.

  • Test Suites (tests/**/*.test.ts, tests/example/*.test.ts)

    • Updated all import statements from aliased forms (e.g., @/api/getMethod, @examples/...) to explicit relative paths (e.g., ../../src/api/getMethod, ../../examples/...).
    • Updated all Vitest mocking calls to use relative imports.
    • Ensured mock, spy, and test setup code remains functionally equivalent, with only import path adjustments.

Dependency Source Adjustments

  • Dependency Restoration for NPM Registry Consistency
    • Restored references to @fjell/logging, @fjell/eslint-config, and @fjell/docs-template from local file: links or backup registries back to their appropriate npm registry versions in package.json and docs/package.json.
    • Removed .kodrdriv-link-backup.json that previously tracked local link status.
    • Guarantees all dependencies are now resolved from the npm registry, supporting standard install and publish workflows.

Rationale and Impact

  • Why These Changes?

    • The move away from aliases addresses compatibility issues that can arise in various environments where custom path mapping is not consistently respected (e.g., some build systems, editor integrations, and CI/CD platforms).
    • Simplifies understanding and maintaining import statements—developers can now directly infer file locations from import paths.
    • Encourages a more portable and tool-agnostic project structure, easing onboarding for new contributors.

  • Potential Impacts

    • Any custom build, dev, or test scripts that previously depended on alias-based imports must now reference files using relative paths or be updated accordingly.
    • Downstream consumers building against this package should see improved reliability, with module resolution matching the on-disk structure at all times.

Detailed List of Changes

TypeScript and Testing Configuration

  • Removed all paths entries from tsconfig.json (@/*, @examples/*, @fjell/http-api).
  • Eliminated resolve.alias from vitest.config.ts.
  • Now relies on standard Node.js and ECMAScript relative import resolution for both source and tests.

Import Path Refactoring

  • Rewrote all production and test imports to use relative paths. Examples include:
    • import { ApiParams } from "@/api"; → import { ApiParams } from "../api";
    • import { getMethod } from "@/api/getMethod"; → import { getMethod } from "../../src/api/getMethod";
    • Mock statements like vi.mock("@/api/http") updated to vi.mock("../../src/api/http").

Test File Updates

  • Adjusted all example integration tests, such as those in tests/example/, to import example modules using ../../examples/... instead of the aliased @examples/....
  • Ensured all references to core modules and utility functions within test files now use the correct relative paths, matching the source folder structure.
  • Maintained all mock and spy setup for console output suppression in test environments, ensuring no behavioral changes aside from import resolution.

Dependency Declaration Normalization

  • Updated package.json dependency declarations:
    • @fjell/logging and @fjell/eslint-config now use the npm registry (with appropriate version ranges) instead of prior file: links.
    • @fjell/docs-template in docs/package.json also references the published npm version.
  • Removed .kodrdriv-link-backup.json used for prior local dependency tracking.

Guidance for Users & Developers

  • All development, testing, and publishing workflows should now work identically or more reliably in all environments, as all imports are resolved via standard Node.js/ESM mechanisms.
  • External users of this package should not experience breaking changes if they depend on distributed (built) output; those using source imports may need to update any alias-based import statements in their own code or tests to match the new structure.
  • Any scripts or tools that set up or expect custom path aliases should be reviewed and updated to use direct/relative references if needed.

No Breaking API or Behavioral Changes

  • There are no API-level changes, logic modifications, or user-facing feature additions in this release beyond the import and configuration structural adjustments described above.
Assets 2
Loading