Skip to content

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


Notifications You must be signed in to change notification settings


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


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


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.


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?