alias-hq

Alias HQ

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

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:

{
  "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:

• The Alias API simplifies your tooling with a single config file and one-liner integrations

If you are thinking about using aliases:

• The Alias CLI migrates your project by configuring your paths and rewriting your imports

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:

• Quick start

For step-by-step instructions:

• Documentation

For a short video:

• Click here

Wanna support the project?

• Tweet or retweet about it :)

Changelog

[6.2.0] - 2023-04-25

Changed:

• Replace TypeScript dependency with JSON5 (#65) - closes #41