如何导入尚未正式发布到npm或yarn的TypeScript模块

针对开发阶段未上架npm的模块，有3种稳定可用的接入方式，按新手友好度从高到低排列：

方案2：本地目录直接引用（零配置门槛，最推荐新手用） #

不用折腾Git拉取、软链配置，手动放代码就能用，出错概率最低：

• 第一步：先把目标模块的完整代码（也就是仓库里packages/xchain-midgard下的所有文件）下载到本地，在你自己的项目根目录新建local-packages文件夹，把xchain-midgard文件夹整个放进去，最终路径为项目根目录/local-packages/xchain-midgard
• 第二步：进入xchain-midgard文件夹，先安装模块自身的依赖、执行编译生成可用的JS产物：

cd local-packages/xchain-midgard
yarn install
yarn build

绝大多数TS写的npm包都不会把编译后的dist产物提交到代码仓库，这步不能跳过，直接引源码大概率报路径、语法错误

• 第三步：回到你自己的项目的根目录，执行命令把本地模块注册到项目依赖里：

yarn add file:./local-packages/xchain-midgard

完成后就可以和普通npm包一样正常导入使用，示例：

import { MidgardClient } from '@xchainjs/xchain-midgard'

后续如果模块代码有更新，直接替换xchain-midgard文件夹里的内容，重新在模块目录执行yarn build即可，不用重复修改依赖配置。

方案1：直接拉取Git分支作为依赖（不用手动下载代码） #

如果你的yarn版本为2.x及以上，支持直接拉取对应开发分支的仓库代码作为依赖：

• 直接打开项目根目录的package.json，在dependencies字段里手动添加对应依赖项，指定仓库和目标开发分支，保存后执行yarn install即可
• 如果安装后提示找不到包入口，是因为该模块属于monorepo结构的子包，yarn 1.x无法自动识别子包入口，换回上面的本地方案即可

方案3：yarn软链（适合需要同步修改模块源码的场景） #

如果你后续需要边调试模块代码、边开发自己的项目，用软链方式效率最高：

• 第一步：把包含目标模块的整个仓库克隆到本地任意位置，切换到对应开发分支，进入packages/xchain-midgard目录
• 第二步：在模块目录依次执行命令完成全局注册：

yarn install
yarn build
yarn link

• 第三步：回到你自己的项目根目录，执行命令把全局注册的模块链到当前项目：

yarn link "@xchainjs/xchain-midgard"

之后你修改模块源码、重新执行build，自己项目里会实时同步改动，不用反复重装依赖。

新手常见踩坑提示 #

• 不要把模块的TS源码直接拖到自己项目的src业务目录里混用，容易打乱TS编译配置、路径别名规则，触发各种找不到类型、编译报错的问题
• 如果TS提示找不到模块类型声明，先检查项目根目录tsconfig.json里的compilerOptions.moduleResolution配置，要设置为node/node16/bundler，不要用默认的classic解析模式
• 接入前先看模块自己的package.json里的main/module/types字段，确认build命令执行后确实生成了字段指向的入口文件，避免空引报错

内容的提问来源于stack exchange，提问作者unchained