https://github.com/open-draft/dotalias
A single configuration for path aliases to reuse across all your tools (TypeScript, Jest, webpack, Rollup, etc.).
https://github.com/open-draft/dotalias
alias import jest path resolve rollup typescript webpack
Last synced: about 2 months ago
JSON representation
A single configuration for path aliases to reuse across all your tools (TypeScript, Jest, webpack, Rollup, etc.).
- Host: GitHub
- URL: https://github.com/open-draft/dotalias
- Owner: open-draft
- Created: 2021-04-14T14:50:36.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2022-02-21T15:43:54.000Z (about 3 years ago)
- Last Synced: 2025-03-13T17:53:59.411Z (2 months ago)
- Topics: alias, import, jest, path, resolve, rollup, typescript, webpack
- Language: TypeScript
- Homepage:
- Size: 252 KB
- Stars: 91
- Watchers: 2
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
.alias
A single configuration for path aliases to reuse across all your tools (TypeScript, webpack, Jest, etc.)
## Motivation
Path alias is a powerful way to manage relative paths in your projects by replacing long import paths like this:
```js
import result from '../../../../utils/getResult'
```
with a defined alias like this:
```js
import result from 'utils/getResult'
```
> In this example, the `utils/` portion of the import is an _alias_ that resolves to the same relative directory.
The issue is that different tools have different declaration format and capabilities of path aliases. This means that in order to reuse the same alias across development and testing you are likely to tweak multiple configuration with the setup you cannot directly reuse. This increases the maintenance cost of such setup, making aliasing expensive.
### What does Dotalias do?
Dotalias establishes a single configuration format for path aliases and compiles it to configurations that different tools can understand. Effectively, it abstracts all the hassle of having to configure various tools differently. By doing so, you can finally reuse **one** configuration to all the tools you're using.
## Getting stated
### Install
```bash
$ npm install dotalias
# OR
$ yarn add dotalias
```
### Create configuration
```bash
$ touch alias.config.js
```
```js
// alias.config.js
module.exports = {
myModule: './module.js',
}
```
### Integrate with your tools
Refer to the [integration examples](#integrations) to use this library with various bundlers or testing frameworks.
## Configuration
You can write the alias configuration in any of the following files:
- `.aliasrc`
- `.aliasrc.json`
- `.aliasrc.yaml`
- `.aliasrc.yml`
- `.aliasrc.js`
- `.aliasrc.cjs`
- `alias.config.js`
- `alias.config.cjs`
- `"alias"` key in your `package.json`
> We are using [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) to resolve the configuration file. Learn more about the way it gets resolved in the mentioned repository.
### Writing configuration
The configuration file consists of keys that represent _module names_ and values that stand for relative paths to resolve those module names.
```js
// alias.config.js
module.exports = {
myModule: './module.js',
}
```
> Module paths are relative to the current working directory.
In the example above, we've created a module alias for the `myModule` that will resolve to a local file at `./module.js` whenever imported in the code:
```js
// Once you've configured your build tools,
// this will resolve to "./module.js".
import result from 'myModule'
```
In the same fashion, the configuration file can be written in [various formats](#configuration-file). Here's an example of the configuration in YAML:
```yaml
myResult: './module.js'
```
## Features
### Exact module name
```js
// alias.config.js
module.exports = {
components: './src/components',
}
```
### Dynamic module name
```js
// alias.config.js
module.exports = {
'utils/*': './src/utils/*',
}
```
### Fallback paths
A single alias may specify multiple paths. The first matching path resolves.
```js
// alias.config.js
module.exports = {
'utils/*': ['src/utils/*', 'utils/*'],
}
```
## Integrations
All the integration examples below assume you have the [configuration file](#configuration-file) created at the root of your application. Whenever you import the `dotalias` package, it automatically reads the closest [configuration](#configuration) and returns the necessary bindings for the integration with other tools.
### webpack
In order to support dynamic import paths (i.e. wildcards), this library exports a custom webpack plugin instead of the `resolve.alias` configuration object.
```js
// webpack.config.js
const { alias } = require('dotalias')
module.exports = {
plugins: [new alias.WebpackPlugin()],
}
```
### Rollup
```js
// rollup.config.js
const { alias } = require('dotalias')
const aliasPlugin = require('@rollup/plugin-alias')
module.exports = {
plugins: [
aliasPlugin({
...alias.rollup,
}),
],
}
```
> Requires you to have the [@rollup/plugin-alias](https://github.com/rollup/plugins/tree/master/packages/alias) package installed.
### Jest
```js
// jest.config.js
const { alias } = require('dotalias')
module.exports = {
...alias.jest,
}
```
### TypeScript
Execute the following command in your project's root directory:
```bash
$ npx dotalias ts
```
This command will generate a `tsconfig.alias.json` partial TypeScript configuration file that you can later extend in your `tsconfig.json` to enable path aliases:
```json
{
"extends": "./tsconfig.alias.json"
}
```
## Research
When deciding on the optimal configuration format, I've researched the path alias configurations for the most common tools I use. Below you can see a table of those tools' capabilities when it comes to path aliases:
| Feature | TypeScript | webpack | Rollup | Jest | .alias |
| --------------- | ---------- | --------------- | --------------- | ---- | ------ |
| Exact paths | ✅ | ✅ | ✅ | ✅ | ✅ |
| Dynamic paths | ✅ | ✅ | ✅ | ✅ | ✅ |
| Fallbacks | ✅ | ✅ | ❌ 1 | ✅ | ✅ |
| RegExp | ❌ | ❌ 2 | ✅ | ✅ | TBA |
| Custom resolver | ❌ | ❌ 2 | ✅ | ❌ | TBA |
> 1—possible with a custom resolver;
> 2—possible with a custom plugin.
### References
- [TypeScript](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) (`paths`)
- [webpack](https://webpack.js.org/configuration/resolve/#resolvealias) (`resolve.alias`)
- [Rollup](https://www.npmjs.com/package/@rollup/plugin-alias) (`@rollup/plugin-alias`)
- [Jest](https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring) (`moduleNameMapper`)