Skip to content

The end-to-end solution for configuring, refactoring, maintaining and using path aliases

License

Notifications You must be signed in to change notification settings

davestewart/alias-hq

Repository files navigation

Alias HQ

tests npm version npm downloads License

The end-to-end solution for configuring, refactoring, maintaining and using path aliases

Alias HQ logo

Abstract

Path "aliases" are special identifiers (starting with @ or ~ ) that point to specific folders.

Using them in your codebase makes your imports easier to read and maintain:

// from this
import { fooify } from '../../../core/services/foo' 

// to this
import { fooify } from '@services/foo' 

They are widely supported in the JavaScript ecosystem, however:

  • libraries have incompatible formats so require separate configurations
  • maintaining duplicate configurations is fiddly and error-prone
  • migrating source code is laborious and long-winded

Overview

Alias HQ is build-time tool which:

  • uses ts/jsconfig.json as the single source of configuration
  • provides one-liner integrations to popular bundlers, frameworks and libraries
  • has a CLI for quick configuration, and even source code migration

Begin by configuring aliases in your project's ts/jsconfig.json:

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

Use the API to sync your toolchain, frameworks, even your IDE:

// webpack.config.js
config.resolve.alias = hq.get('webpack')

// jest.config.js
config.moduleNameMapper = hq.get('jest')

// etc...

Use the CLI to migrate or maintain your source code:

? What do you want to do?
  - Configure paths
  - Setup integrations
❯ - Update source code
  - Help
  - Exit

For a list of all supported frameworks, see the integrations doc.

Benefits

If you are already using aliases:

If you are thinking about using aliases:

You can configure and migrate any project in less than a minute by:

  • installing the package
  • running the CLI
  • following the prompts

Getting started

Install via your package manager of choice:

npm i --save-dev alias-hq
yarn add -D alias-hq

To jump in without much reading:

For step-by-step instructions:

For a short video:

Wanna support the project?