{"id":13486764,"url":"https://github.com/open-draft/dotalias","last_synced_at":"2026-01-22T19:43:16.712Z","repository":{"id":43725910,"uuid":"357941377","full_name":"open-draft/dotalias","owner":"open-draft","description":"A single configuration for path aliases to reuse across all your tools (TypeScript, Jest, webpack, Rollup, etc.).","archived":false,"fork":false,"pushed_at":"2022-02-21T15:43:54.000Z","size":258,"stargazers_count":91,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-13T17:53:59.411Z","etag":null,"topics":["alias","import","jest","path","resolve","rollup","typescript","webpack"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-draft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-04-14T14:50:36.000Z","updated_at":"2024-12-28T06:40:32.000Z","dependencies_parsed_at":"2022-09-12T11:12:36.303Z","dependency_job_id":null,"html_url":"https://github.com/open-draft/dotalias","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-draft%2Fdotalias","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-draft%2Fdotalias/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-draft%2Fdotalias/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-draft%2Fdotalias/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-draft","download_url":"https://codeload.github.com/open-draft/dotalias/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245927169,"owners_count":20695179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alias","import","jest","path","resolve","rollup","typescript","webpack"],"created_at":"2024-07-31T18:00:50.837Z","updated_at":"2026-01-22T19:43:16.706Z","avatar_url":"https://github.com/open-draft.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logo.png\" width=\"125\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003e.alias\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\nA single configuration for path aliases to reuse across all your tools (TypeScript, webpack, Jest, etc.)\n\u003c/p\u003e\n\n## Motivation\n\nPath alias is a powerful way to manage relative paths in your projects by replacing long import paths like this:\n\n```js\nimport result from '../../../../utils/getResult'\n```\n\nwith a defined alias like this:\n\n```js\nimport result from 'utils/getResult'\n```\n\n\u003e In this example, the `utils/` portion of the import is an _alias_ that resolves to the same relative directory.\n\nThe 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.\n\n### What does Dotalias do?\n\nDotalias 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.\n\n## Getting stated\n\n### Install\n\n```bash\n$ npm install dotalias\n# OR\n$ yarn add dotalias\n```\n\n### Create configuration\n\n```bash\n$ touch alias.config.js\n```\n\n```js\n// alias.config.js\nmodule.exports = {\n  myModule: './module.js',\n}\n```\n\n### Integrate with your tools\n\nRefer to the [integration examples](#integrations) to use this library with various bundlers or testing frameworks.\n\n## Configuration\n\nYou can write the alias configuration in any of the following files:\n\n- `.aliasrc`\n- `.aliasrc.json`\n- `.aliasrc.yaml`\n- `.aliasrc.yml`\n- `.aliasrc.js`\n- `.aliasrc.cjs`\n- `alias.config.js`\n- `alias.config.cjs`\n- `\"alias\"` key in your `package.json`\n\n\u003e 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.\n\n### Writing configuration\n\nThe configuration file consists of keys that represent _module names_ and values that stand for relative paths to resolve those module names.\n\n```js\n// alias.config.js\nmodule.exports = {\n  myModule: './module.js',\n}\n```\n\n\u003e Module paths are relative to the current working directory.\n\nIn 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:\n\n```js\n// Once you've configured your build tools,\n// this will resolve to \"./module.js\".\nimport result from 'myModule'\n```\n\nIn the same fashion, the configuration file can be written in [various formats](#configuration-file). Here's an example of the configuration in YAML:\n\n```yaml\nmyResult: './module.js'\n```\n\n## Features\n\n### Exact module name\n\n```js\n// alias.config.js\nmodule.exports = {\n  components: './src/components',\n}\n```\n\n### Dynamic module name\n\n```js\n// alias.config.js\nmodule.exports = {\n  'utils/*': './src/utils/*',\n}\n```\n\n### Fallback paths\n\nA single alias may specify multiple paths. The first matching path resolves.\n\n```js\n// alias.config.js\nmodule.exports = {\n  'utils/*': ['src/utils/*', 'utils/*'],\n}\n```\n\n## Integrations\n\nAll 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.\n\n### webpack\n\nIn order to support dynamic import paths (i.e. wildcards), this library exports a custom webpack plugin instead of the `resolve.alias` configuration object.\n\n```js\n// webpack.config.js\nconst { alias } = require('dotalias')\n\nmodule.exports = {\n  plugins: [new alias.WebpackPlugin()],\n}\n```\n\n### Rollup\n\n```js\n// rollup.config.js\nconst { alias } = require('dotalias')\nconst aliasPlugin = require('@rollup/plugin-alias')\n\nmodule.exports = {\n  plugins: [\n    aliasPlugin({\n      ...alias.rollup,\n    }),\n  ],\n}\n```\n\n\u003e Requires you to have the [@rollup/plugin-alias](https://github.com/rollup/plugins/tree/master/packages/alias) package installed.\n\n### Jest\n\n```js\n// jest.config.js\nconst { alias } = require('dotalias')\n\nmodule.exports = {\n  ...alias.jest,\n}\n```\n\n### TypeScript\n\nExecute the following command in your project's root directory:\n\n```bash\n$ npx dotalias ts\n```\n\nThis command will generate a `tsconfig.alias.json` partial TypeScript configuration file that you can later extend in your `tsconfig.json` to enable path aliases:\n\n```json\n{\n  \"extends\": \"./tsconfig.alias.json\"\n}\n```\n\n## Research\n\nWhen 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:\n\n| Feature         | TypeScript | webpack         | Rollup          | Jest | .alias |\n| --------------- | ---------- | --------------- | --------------- | ---- | ------ |\n| Exact paths     | ✅         | ✅              | ✅              | ✅   | ✅     |\n| Dynamic paths   | ✅         | ✅              | ✅              | ✅   | ✅     |\n| Fallbacks       | ✅         | ✅              | ❌ \u003csup\u003e1\u003c/sup\u003e | ✅   | ✅     |\n| RegExp          | ❌         | ❌ \u003csup\u003e2\u003c/sup\u003e | ✅              | ✅   | TBA    |\n| Custom resolver | ❌         | ❌ \u003csup\u003e2\u003c/sup\u003e | ✅              | ❌   | TBA    |\n\n\u003e \u003csup\u003e1\u003c/sup\u003e—possible with a custom resolver;\n\u003e \u003csup\u003e2\u003c/sup\u003e—possible with a custom plugin.\n\n### References\n\n- [TypeScript](https://www.typescriptlang.org/docs/handbook/module-resolution.html#path-mapping) (`paths`)\n- [webpack](https://webpack.js.org/configuration/resolve/#resolvealias) (`resolve.alias`)\n- [Rollup](https://www.npmjs.com/package/@rollup/plugin-alias) (`@rollup/plugin-alias`)\n- [Jest](https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring) (`moduleNameMapper`)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-draft%2Fdotalias","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-draft%2Fdotalias","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-draft%2Fdotalias/lists"}