{"id":15437556,"url":"https://github.com/ianvs/ts-module-resolution-examples","last_synced_at":"2025-08-21T20:32:33.491Z","repository":{"id":82721788,"uuid":"573248146","full_name":"IanVS/ts-module-resolution-examples","owner":"IanVS","description":"Examples and explanations of TypeScript module resolution","archived":false,"fork":false,"pushed_at":"2024-08-12T14:09:28.000Z","size":44,"stargazers_count":36,"open_issues_count":4,"forks_count":9,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-18T10:44:25.439Z","etag":null,"topics":["bundlers","cjs","esm","nodejs","typescript"],"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/IanVS.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-12-02T02:35:08.000Z","updated_at":"2024-10-17T07:28:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"f9e3cc52-8a0e-4959-becc-3bf65f503161","html_url":"https://github.com/IanVS/ts-module-resolution-examples","commit_stats":{"total_commits":23,"total_committers":3,"mean_commits":7.666666666666667,"dds":"0.13043478260869568","last_synced_commit":"4f2023d2f57b53731cd650cc714d1ce108c8bad9"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IanVS%2Fts-module-resolution-examples","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IanVS%2Fts-module-resolution-examples/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IanVS%2Fts-module-resolution-examples/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/IanVS%2Fts-module-resolution-examples/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/IanVS","download_url":"https://codeload.github.com/IanVS/ts-module-resolution-examples/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230532448,"owners_count":18240792,"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":["bundlers","cjs","esm","nodejs","typescript"],"created_at":"2024-10-01T18:57:54.933Z","updated_at":"2024-12-20T04:07:43.327Z","avatar_url":"https://github.com/IanVS.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TypeScript Module Resolution Examples \u003c!-- omit from toc --\u003e\n\nA set of example projects exploring TypeScript module resolution with various settings and situations.\n\nTable of contents:\n\n- [About this project](#about-this-project)\n- [Introduction to TS module resolution](#introduction-to-ts-module-resolution)\n  - [Modules](#modules)\n  - [Module resolution](#module-resolution)\n- [TypeScript Options](#typescript-options)\n  - [`moduleResolution`](#moduleresolution)\n    - [New options in development](#new-options-in-development)\n  - [`baseUrl`](#baseurl)\n  - [`moduleSuffixes`](#modulesuffixes)\n  - [`resolution-mode`](#resolution-mode)\n- [Miscellaneous](#miscellaneous)\n  - [Ambient modules](#ambient-modules)\n- [TS V5](#ts-v5)\n  - [TS V5.0](#ts-v50)\n    - [Resolution Customization Flags](#resolution-customization-flags)\n    - [ModuleResolution Bundler](#moduleresolution-bundler)\n  - [TS V5.1](#ts-v51)\n    - [TypeRoots Are Consulted In Module Resolution](#typeroots-are-consulted-in-module-resolution)\n    - [Explicit TypeRoots Disables Upward Walks for node_modules/@types](#explicit-typeroots-disables-upward-walks-for-node_modulestypes)\n  - [TS V5.2](#ts-v52)\n    - [Module and moduleResolution Must Match Node.js Settings](#module-and-moduleresolution-must-match-nodejs-settings)\n    - [Type-Only Import Paths + TypeScript Implementation File Extensions](#type-only-import-paths--typescript-implementation-file-extensions)\n\n## About this project\n\nThis was initially created for [a talk](https://www.youtube.com/watch?v=MEl2R7mEAP8) at Michigan TypeScript Developers.\n\nThe repository is roughly organized around TypeScript settings, with subfolders for possible values for those settings\nand examples demonstrating various aspects of module resolution. There are `README.md` files in most examples to\nexplain the concept being demonstrated. Usually you can run `npm run build` in each example folder to generate\n`example.d.ts` type definition files and see a log of the module resolution process that TypeScript uses printed\nto the terminal.\n\nFeel free to submit issues or pull requests. I hope for this to be a learning resource for TypeScript developers who\nwant to understand the complex topic of TypeScript module resolution. So with that, let's start learning!\n\n## Introduction to TS module resolution\n\n### Modules\n\nLet's begin by defining what we mean by a \"module\". When we write TypeScript code,\nwe typically don't write everything in one single file. Instead, we break up our code\ninto smaller pieces and put these into files. JavaScript can treat each file as either\na \"script\" or a \"module\".\n\nBasically, a script file is a standard JavaScript file that does not import or require any other files\nand does not have any exports. It might operate on the global scope, or it might not.\n\nJavaScript Modules, on the other hand, generally come in two flavors, CommonJS (CJS) and\nES Modules (ESM). Node.js historically used CJS and has started supporting ESM since version 12.\nModern browsers also support ES modules, but they use slightly different rules for resolving\nimports from other modules. To learn more about ES modules in the browser, I recommend reading the\n[MDN article](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).\n\nIn TypeScript, most files you write will be considered a module. By default, any file that uses `import` or `export` is treated as a module. Starting in version 4.7, in some situations TypeScript will also check for a package.json file containing `\"type\": \"module\"`. The module detection behavior can be\nadjusted with the [`moduleDetection`](https://www.typescriptlang.org/tsconfig#moduleDetection) setting.\n\n### Module resolution\n\nWhen we need to use code from another TypeScript file than the one we are writing, we generally\nuse an `import` statement (or `import()` function). We might write something like:\n\n```ts\nimport foo from \"moduleA\";\n```\n\nTypeScript will then need to find what module we mean by \"moduleA\", in order to determine what type\n\"foo\" should have.\n\nThis is important. We are talking about _types_ when we talk about TypeScript module resolution.\n\nIt's true that TypeScript can also compile `.ts` files into `.js` files, converting our TypeScript into\nJavaScript that can run in Node.js, or browsers, or elsewhere. But it's the runtime that will perform\nthe actual imports, using its own module resolution algorithms. Module resolution rules are left up to the runtime to determine, it is not determined by the JavaScript specification.\n\nSo, TypeScript does its best to try to match the same module resolution rules that the final runtime\nwill use, so that the type information it gathers is complete and accurate. Because there are different\nruntimes with different rules, TypeScript exposes some options that we can set in order to match up with\nthe runtime environment.\n\n## TypeScript Options\n\nThese are some options which TypeScript uses to adjust its module resolution. Please see the\n[TypeScript config reference](https://www.typescriptlang.org/tsconfig) for details on each option\nand the minimum TypeScript version required for support.\n\nNote that some module-related options, such as `module` and `target` effect the emitted JavaScript files, but not module resolution (other than by changing the defaults for other options in some cases), so they are not explored here.\n\n### `moduleResolution`\n\n[Config reference](https://www.typescriptlang.org/tsconfig#moduleResolution)\n\nThis is the most direct way to change TypeScript's module resolution mode. It has three current possible values,\nand more are being developed to better meet the needs of bundlers and browser-native modules.\n\nThe currently-supported values are (as of TS 4.9):\n\n- `\"Classic\"`\n- `\"Node\"`\n- `\"Node16\"` or `\"NodeNext\"` (currently these mean the same thing)\n\n\"Classic\" mode is rarely used in modern projects, and is not explored in this repository. For details on how it works,\nsee the TypeScript [module resolution guide](https://www.typescriptlang.org/docs/handbook/module-resolution.html#classic).\n\n\"Node\" is likely the most commonly-used option, and mimics the behavior of Node 11 and below.\nSee the `moduleResolution/Node` examples and [README](moduleResolution/Node/README.md).\n\n\"NodeNext\" is intended to evolve as Node.js adds new versions and new features, but for now it is the same as \"Node16\",\nwhich adds support for the Node.js style of ES modules. There are some differences in TypeScript Module resolution\ncompared to \"Node\", and these are explored in `moduleResolution/Node16`.  \nSee the [README](moduleResolution/Node16/README.md) there to begin.\n\n#### New options in development\n\nThe TypeScript team identified that the current `moduleResolution` options are not flexible enough for those using\nbundlers or writing ESM to be directly consumed in browsers, so they are creating new options:\n\n- `\"Hybrid\"` (final naming TBD): designed primarily for bundlers, with some behavior customizable by settings.\n  - PR: https://github.com/microsoft/TypeScript/pull/51669\n- `\"Minimal\"`: A common-denominator for resolution features supported in browsers, Node, Deno, and bundlers.\n  - PR: https://github.com/microsoft/TypeScript/pull/50153\n\nThere are no examples of these in this repo, but I intend to add them once they are released.\n\n### `baseUrl`\n\n[Config reference](https://www.typescriptlang.org/tsconfig#baseUrl);\n\n_Examples TBD_\n\nProvides a way to inform TypeScript that when compiled, non-relative imports can be resolved relative to this path.\nIt is similar to the (discouraged) `NODE_PATH` option for Node.js.\n\n### `moduleSuffixes`\n\n[Release announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#resolution-customization-with-modulesuffixes)\n\n_Examples TBD_\n\nAllows customizing the “sub” extensions TS will examine, which can be particularly useful when targeting React Native\nas a runtime. For example, `\"moduleSuffixes\": [\".ios\", \".native\", \"\"]` will look for files ending with `.ios.ts`, `.native.ts`, then `.ts`.\n\n### `resolution-mode`\n\n[Release announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-4-7/#resolution-mode)\n\n_Examples TBD_\n\nThis is an experimental feature, parts of which are available only in nightly versions, which can change the\n\"resolution mode\" of globals or imported types, allowing CJS types to be used in ESM files, and vice-versa.\n\n## Miscellaneous\n\n### Ambient modules\n\nAmbient modules make it possible to import a JavaScript project without types, and use\n[community-supplied](https://github.com/DefinitelyTyped/DefinitelyTyped) types or custom-written types to\ndescribe that project. The examples in `misc/ambient-modules` explore different ways that ambient modules can be\nconfigured and used.\n\n## TS V5\n\n### TS V5.0\n\n#### Resolution Customization Flags\n\n- [Youtube - Resolution Customization Flags](https://youtu.be/uKcfxI84xPc?si=4C8Fa1kGB-roejUP)\n\n#### ModuleResolution Bundler\n\n- [Youtube - --moduleResolution bundler](https://youtu.be/wfCRQF-HxwY?si=E28B1MipgyElA8QS)\n\n### TS V5.1\n\n#### TypeRoots Are Consulted In Module Resolution\n\n- [Youtube - typeRoots Are Consulted In Module Resolution](https://youtu.be/Z5Qk6z9RK4s?si=-mPoX2bmxp0ey5oK)\n\n#### Explicit TypeRoots Disables Upward Walks for node_modules/@types\n\n- [Youtube - Explicit typeRoots Disables Upward Walks for node_modules/@types](https://youtu.be/avVimJ1gdNA?si=zm-lwIQHCNo3JA-j)\n\n### TS V5.2\n\n#### Module and moduleResolution Must Match Node.js Settings\n\n- [Youtube - module and moduleResolution Must Match Node.js Settings](https://youtu.be/j3OUn0iw4k8?si=Km4-xA1FkmpW6gaj)\n\n#### Type-Only Import Paths + TypeScript Implementation File Extensions\n\n- [Youtube - Type-Only Import Paths + TypeScript Implementation File Extensions](https://youtu.be/ZwNIsSmk-Ks?si=XGQl-BmzXYOGUhYF)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianvs%2Fts-module-resolution-examples","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fianvs%2Fts-module-resolution-examples","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fianvs%2Fts-module-resolution-examples/lists"}