Debugging Local Packages with Pnpm and Vite: Common Issues and Solutions
When developing with Pnpm + Vite, during local package debugging, Vite may still load the old version of the package. This article analyzes and resolves this issue.
Local Package Debugging Steps
Since the package manager is pnpm, the corresponding debugging package mounting steps are as follows:
- Execute
pnpm link --globalin the local package - Execute
pnpm link pkgname --globalin the target project
After performing these steps, accessing the web browser will reproduce the issue of incorrect package versions.
Let’s first analyze the situation in vite/pnpm
.vite
When Vite builds a project, it creates a .vite folder under node_modules
The .vite cache requires changes in any of the following conditions:
- Package manager lockfile content, e.g.
package-lock.json,yarn.lock,pnpm-lock.yamlorbun.lockb. - Patches folder modification time.
- Relevant fields in your
vite.config.js, if present. NODE_ENVvalue.
To force a refresh in Vite, you need to use --force or delete the .vite directory. For more details, see the official documentation
When executing pnpm link, you’ll notice that the lock file doesn’t change, so the .vite cache won’t be updated.
.pnpm Directory
Packages in node_modules are soft-linked to the .pnpm folder. When executing pnpm link:
- The lock file won’t change
- The corresponding package in node_modules will be soft-linked to the globally linked package
Problem Analysis
In summary, the issue is that after pnpm link, the lock file doesn’t get updated. Although the package dependency links change (meaning the content changes), Vite is unaware of this. Therefore, the Vite cache needs to be manually refreshed. Manually deleting the .vite directory and restarting Vite will show that the correct content is loaded.
Related Issues
SourceMap
SourceMap is designed to facilitate debugging with source code, such as being able to search for source files in Chrome Network. The reason it can be retrieved is that when the browser has Network open, it attempts to load the corresponding map file based on the sourcemap address noted in the code file. The map file records the location of the source files, and then the source code files are loaded. If you can’t retrieve source code files in Chrome, you can check whether the map files and source files are being loaded successfully with the correct paths.
SourceMap Not Working When Debugging Webpack Packages in Vite
The reason is that the sourcemap generated by Webpack uses the webpack protocol for source files, which Vite doesn’t support. One solution is to switch to Vite for building.
{"version":3,"file":"index.js","mappings":"AAAA","sources":["webpack://laputarenderer/webpack/universalModuleDefinition"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory(require(\"react\"));\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([\"react\"], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"laputarenderer\"] = factory(require(\"react\"));\n\telse\n\t\troot[\"laputarenderer\"] = factory(root[\"React\"]);\n})(self, (__WEBPACK_EXTERNAL_MODULE__12__) => {\nreturn "],"names":[],"sourceRoot":""}
Related Documentation
Final Thoughts
Debugging local packages with Pnpm and Vite can be challenging due to caching mechanisms. The key insight is understanding that Vite’s dependency pre-bundling relies on lockfile changes to invalidate its cache. When using pnpm link, the lockfile remains unchanged, causing Vite to continue using cached versions of packages. The solution is to manually clear the Vite cache by deleting the .vite directory or using the --force flag when restarting the development server. This approach ensures that your local package changes are properly reflected during development.
