{"id":15632495,"url":"https://github.com/oklas/react-app-alias","last_synced_at":"2025-04-04T18:09:31.198Z","repository":{"id":37927535,"uuid":"242229087","full_name":"oklas/react-app-alias","owner":"oklas","description":":label: Alias and multiple src directory for craco or rewired create-react-app","archived":false,"fork":false,"pushed_at":"2023-05-06T02:14:28.000Z","size":1452,"stargazers_count":176,"open_issues_count":12,"forks_count":18,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-28T17:06:39.177Z","etag":null,"topics":["alias","cra","craco","create-react-app","monorepo","multi","multirepo","react","react-app-rewired","workaround"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oklas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["oklas"],"custom":"https://paypal.me/oklaspec"}},"created_at":"2020-02-21T20:55:54.000Z","updated_at":"2025-01-15T17:03:27.000Z","dependencies_parsed_at":"2024-06-18T13:56:38.172Z","dependency_job_id":"caa6ae7d-86ac-448a-ac54-6db3d5657f4f","html_url":"https://github.com/oklas/react-app-alias","commit_stats":{"total_commits":149,"total_committers":12,"mean_commits":"12.416666666666666","dds":"0.11409395973154357","last_synced_commit":"b8c5da9aaef361ec3dcbe0ec9276a4b156dff927"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oklas%2Freact-app-alias","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oklas%2Freact-app-alias/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oklas%2Freact-app-alias/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oklas%2Freact-app-alias/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oklas","download_url":"https://codeload.github.com/oklas/react-app-alias/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"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","cra","craco","create-react-app","monorepo","multi","multirepo","react","react-app-rewired","workaround"],"created_at":"2024-10-03T10:44:24.743Z","updated_at":"2025-04-04T18:09:31.177Z","avatar_url":"https://github.com/oklas.png","language":"JavaScript","funding_links":["https://github.com/sponsors/oklas","https://paypal.me/oklaspec"],"categories":[],"sub_categories":[],"readme":"# Alias solution for craco or rewired create-react-app\n\nThis is more than simple alias. This is also a multi-project `src`\ndirectory. Currently, `create-react-app` (CRA) does not support more than one\n`src` directory in the project. Monorepo, multi-repo and library projects with\nexamples require more than one directory like `src`.\n\nThis is merely an alias and multi-source solution for CRA\nand this is not a replacement for multi-package management tools like\n[Lerna](https://github.com/lerna/lerna).\n\nThis requires to modify the CRA webpack configuration in runtime\n(without ejecting) and works with one of:\n* **[react-app-rewired](https://github.com/timarney/react-app-rewired)**\n* **[customize-cra](https://github.com/arackaf/customize-cra)**\n* **[craco](https://github.com/gsoft-inc/craco)** (see [Using craco](#using-craco) below)\n\n[![Npm package](https://img.shields.io/npm/v/react-app-rewire-alias.svg?style=flat)](https://npmjs.com/package/react-app-rewire-alias)\n[![Npm downloads](https://img.shields.io/npm/dm/react-app-rewire-alias.svg?style=flat)](https://npmjs.com/package/react-app-rewire-alias)\n[![Dependency Status](https://david-dm.org/oklas/react-app-rewire-alias.svg)](https://david-dm.org/oklas/react-app-rewire-alias)\n[![Dependency Status](https://img.shields.io/github/stars/oklas/react-app-rewire-alias.svg?style=social\u0026label=Star)](https://github.com/oklas/react-app-rewire-alias)\n[![Dependency Status](https://img.shields.io/twitter/follow/oklaspec.svg?style=social\u0026label=Follow)](https://twitter.com/oklaspec)\n\n#### This allows:\n\n* quality and secure exports from outside `src`\n* absolute imports\n* any `./directory` at root outside of `src` with Babel/Typescript and all CRA features\n\n#### This is designed for:\n\n* monorepo projects\n* multi-repo projects\n* library projects with examples\n\n#### Advantages over other solutions:\n\n * provided fully functional aliases and allows the use of Babel, JSX, etc.\n   outside of `src` (outside of project `root` may be enbled with special way\n   see the section below)\n\n * provided fully secure aliases and uses the same module scope plugin from\n   the original create-react-app package for modules (instead of removing it),\n   to minimize the probability of including unwanted code\n\n#### Installation\n\n```sh\nyarn add --dev react-app-alias\n```\n\nor\n\n```sh\nnpm install --save-dev react-app-alias\n```\n\n### Usage\n\nBy default folders for alias may be near to **src** folder or in it.\nOutside of project `root` is implemented in `react-app-alias-ex` (suffix `-ex`).\n\nUsage steps:\n\n* enumerate aliases in *jsconfig.paths.json* or *tsconfig.paths.json*\n* include it in *jsconfig.json* or *tsconfig.json*\n* enable your favorite any of *react-app-rewired* or *craco*\n* apply react-app-alias in config\n\n#### Enumerate aliases in **jsconfig.paths.json** or **tsconfig.paths.json**\n\nCreate a separate file `jsconfig.paths.json` or `tsconfig.paths.json`, like this:\n\n```js\n// jsconfig.paths.json or tsconfig.paths.json\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"example/*\": [\"example/src/*\"],\n      \"@library/*\": [\"library/src/*\"]\n    }\n  }\n}\n```\n\n#### Add **extends** section to **jsconfig.json** or **tsconfig.json**\n\nThe **paths** section must not be configured directly in `jsconfig.json`\nor `tsconfig.json`, but in a separate extends file mentioned above.\nNow include this file in **extends** section, like this:\n\n```js\n// jsconfig.json or tsconfig.json\n{\n  \"extends\": \"./jsconfig.paths.json\", // or \"./tsconfig.paths.json\"\n  \"compilerOptions\": {\n    // ...\n  }\n}\n```\n\n### Configure plugin for craco or react-app-rewired\n\n* **`react-app-rewired`**\n\n```js\n// config-overrides.js\nconst {aliasWebpack, aliasJest} = require('react-app-alias')\n\nconst options = {} // default is empty for most cases\n\nmodule.exports = aliasWebpack(options)\nmodule.exports.jest = aliasJest(options)\n```\n\n* **`craco`**\n\n```js\n// craco.config.js\n\nconst {CracoAliasPlugin} = require('react-app-alias')\n\nconst options = {} // default is empty for most cases\n\nmodule.exports = {\n  plugins: [\n    {\n      plugin: CracoAliasPlugin,\n      options: {}\n    }\n  ]\n}\n```\n\n\n#### Enable craco or react-app-rewired\n\n* **`react-app-rewired`**\n\nIntegrating `react-app-rewired` into your project is simple\n(see [its documentation](https://github.com/timarney/react-app-rewired#readme)):\nCreate `config-overrides.js` mentioned above, in the project's root directory\n(the same including the `package.json` and `src` directory).\nInstall `react-app-rewired` \n\n```sh\nyarn add --dev react-app-rewired\n- or -\nnpm install --save-dev react-app-rewired\n```\nand rewrite the `package.json` like this:\n\n```diff\n  \"scripts\": {\n-   \"start\": \"react-scripts start\",\n+   \"start\": \"react-app-rewired start\",\n+   ... // same way\n  }\n```\n\n* **`craco`**\n\nAccording to [craco](https://github.com/gsoft-inc/craco/blob/master/packages/craco/README.md#installation)\ndocs install craco:\n\n```sh\nyarn add --dev craco\n- or -\nnpm install --save-dev craco\n``` \n\nand replace `react-scripts` in `package.json`:\n\n```diff\n  \"scripts\": {\n-   \"start\": \"react-scripts start\",\n+   \"start\": \"craco start\",\n+   ... // same way\n  }\n```\n\n\n#### Using baseUrl\n\n* **`baseUrl = '.'`**\n\n  * able to create alias outside of `src` (near `src`)\n  * for each directory in `src` alias **does not** created automatically (must be declared manually)\n\n* **baseUrl = 'src'**\n\n  * alias outside of `src` is not possible, only in directory specified in `baseUrl`\n  * for each folder in `src` alias created automatically with same name as folder\n\nSee also experimental [autoscan](https://github.com/oklas/react-app-alias/issues/70) feature\n\n### Using SWC etc\n\nAlias plugin must be aplied **after** SWC plugin.\n\nPlugin SWC must be declared in plugin section before alias plugn. This is because\nSWC plugn recreate SWC configuration instead of babel configuration. Both babel and\nswc configurations originally without alias configuration. So to configure alias,\n**alias plugin must be aplied after SWC plugin**:\n\n```js\nconst { CracoAliasPlugin } = require('react-app-alias');\nconst CracoSwcPlugin = require('craco-swc');\n\nmodule.exports = {\n  plugins: [\n    { plugin: CracoSwcPlugin },\n    { plugin: CracoAliasPlugin },\n  ],\n}\n```\n\n\n### API\n\n* **options**\n\n```ts\n  Options {\n    alias?: { [alias: string]: string }; // optional alias map\n    tsconfig?: string, // optional tsconfig.json path\n    jsconfig?: string, // optional jsconfig.json path\n    baseUrl?: string, // optional by default from config\n  }\n```\n\n  // optional alias map has following form:  \n  const alias = {\n    example: 'example/src',\n    '@library': 'library/src',\n  }\n\n\n* **aliasWebpack(options)(webpackConfig)**\n\nThe function `aliasWebpack()` accepts aliases declared in form:\n\n```js\nconst aliasMap = {\n  example: 'example/src',\n  '@library': 'library/src',\n}\n\nconst options = {\n  alias: aliasMap,\n}\n\nmodule.exports = aliasWebpack(options)\nmodule.exports.jest = aliasJest(options)\n```\n\nTo make all things worked, aliases must be declared in `jsconfig.json` or `tsconfig.json`.\nHowever, it must be declared in a separate extends file (see section `Workaround for\n\"aliased imports are not supported\"` below)\n\nThe result is a function which will modify Wepack config\n\n* **configPaths()**\n\nThe function `configPaths()` loads paths from file compatible with `jsconfig.json`\nor `tsconfig.json` and returns path in form acceptable for `aliasWebpack()` function.\nThe `tsconfig.json` is prioritized over the `jsconfig.json` in the loading sequence.\n\n```js\nconst aliasMap = configPaths('./tsconfig.paths.json')\n\nconst options = {\n  alias: aliasMap,\n}\n\nmodule.exports = aliasWebpack(aliasMap)\n```\n\n* **extendability**\n\nAs any `react-app-rewire` or `customize-cra` rewire extension this can be integrated\nwith another:\n\n```js\nmodule.exports = function override(config) {\n  const modifiedConfig = aliasWebpack(...)(config)\n  ...\n  return someElse(modifiedConfig)\n}\nmodule.exports.jest = function override(config) {\n  const modifiedConfig = aliasJest(...)(config)\n  ...\n  return modifiedConfig\n}\n```\n\n#### Workaround for \"aliased imports are not supported\"\n\nCRA [overwrites](/blob/v3.4.1/packages/react-scripts/scripts/utils/verifyTypeScriptSetup.js#L242)\nyour `tsconfig.json` at runtime and removes `paths` from the `tsconfig.json`,\nwhich is not officially supported, with this message:\n\n\u003e ```\n\u003e The following changes are being made to your tsconfig.json file:\n\u003e   - compilerOptions.paths must not be set (aliased imports are not supported)\n\u003e ```\n\nThe [suggested workaround](https://github.com/facebook/create-react-app/issues/5645#issuecomment-435201019)\nis to move the paths to a different `.json` file, e.g. `tsconfig.paths.json`, like this:\n\n```json\n/* tsconfig.paths.json */\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"example/*\": [\"example/src/*\"],\n      \"@library/*\": [\"library/src/*\"]\n    }\n  }\n}\n```\n\nwith that file's subsequent inclusion in the `tsconfig.json` using `extends`:\n\n```json\n/* tsconfig.json */\n{\n  \"extends\": \"./tsconfig.paths.json\"\n}\n```\n\n## Outside of root\n\nAlias folders outside of the root of the project currently fully functional and\nworks fine but are not recommended. It may bring hard-to-detect errors.\n\nAlias with support of **Outside of root** is implemented in separated library:\n\n`react-app-alias-ex`\n\nwith identical API, just install and add suffix `-ex` in import statement:\n\n```diff\n- const {aliasWebpack, CracoAliasPlugin} = require('react-app-alias')\n+ const {aliasWebpack, CracoAliasPlugin} = require('react-app-alias-ex')\n```\n\n## Tips\n\n* **keep only one `node_modules` directory**\n\nConfusions in deps versions may bring unclear errors or problems. For example, an application\nis not working without any error. Or another example is error in `react-router` - `\u003cRoute\u003e`\ncomponent do not see `\u003cRouter\u003e` when actually code is correct and it falls with:\n\n\u003e should not use Route or withRouter() outside a Router\n\nThis may be a result of some confusion in `node_modules` folders for multi-repo projects.\nSame take place in plain `create-react-app` if somehow one or more additional\n`node_modulest` directories appear in `src`.\n\nTo avoid this problem **use only one main project `node_modules` directory**.\n\n* **keep away from working with nested project**\n\nDefault bundler configuration doesn't assume your configuration and may mix deps from\n`node_modules` from different projects (top project and nested project) so this may\nbring mentioned above confusions with deps versions. To avoid problems:\n**do not install and run within nested project directly when it is nested or integrated\nin another one - but only independent top level configuration** Or consider to eject\nor configure Webpack manually.\n\n* **do not relay to deps versions synchronization**\n\nSome libraries use `instanceof` and other type comparisions. For example , two objects\ncreated with the same params in the same code of the same library version but installed in\ndifferent `node_modules` and bundled separately - will mostly have the same data and same\nbehaviour but different instance type. Such libraries will be unable to recognize their own\nobjects and will lead to unpredictable behaviour. So **use only one main project\n`node_modules` directory**.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foklas%2Freact-app-alias","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foklas%2Freact-app-alias","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foklas%2Freact-app-alias/lists"}