Creating and using a Node library with TypeScript

node-ts-hello-adventures.md

node-ts-hello adventures

This is what I was really doing while creating an example from this answer on Stack Overflow:

• deno vs ts-node : what's the difference

It turned out that I made several stupid mistakes and wasted a lot more time than it might look like from reading the answer. I eventually removed from the answer not so much out of embarrassment but because I didn't want to be accused that I am complicating the process on purpose to make Deno look better in comparison. The truth is that below ius exactly what I did while trying to create and publish a new module on npm written in TypeScript and use it with ts-node later:

https://github.com/rsp/node-ts-hello

Creating library:

1. find a name that is free on npm (no longer enough, see below)
2. create repo on GitHub
3. create package.json with npm init
4. install TypeScript compiler with npm install typescript
5. decide if you're keeping package-lock.json in the repo (there are pros and cons)
6. create a src dir where you will keep TypeScript files
7. add hello.ts to src
8. add tsconfig.json file and make sure to: a. add "src/**/*" to "include" a. add dependencies and your own types to "paths" a. add "outDir": "dist" to put the JS files in a known place a. add the dist directory to .gitignore so that compiled files are not in git a. add "declaration": true so you have *.d.ts files generated
9. add "main": "dist/hello.js" in package.json (note the "js" suffix)
10. add "types": "dist/hello.d.ts" in package.json (note the "ts" suffix)
11. add "build": "tsc" to package.json
    • make sure to remove the entire dist or its contents before the compilation because otherwise if you remove or rename files in src you will have redundant files in dist which are not only not needed but they can cause errors and tsc --build --clean doesn't remove them for me (it caused me problems more than once so that's why I'm mentioning it here but the solution is out of the scope of this answer)
12. compile the project with npm run build
13. publish the package with npm publish
    • when you get npm ERR! publish Failed PUT 401 you need to login with npm login
    • I keep logged out because of the history of malware stealing npm credentials in the past - see: Now Pushing Malware: NPM package dev logins slurped by hacked tool popular with coders
14. run npm publish
    • after logging in I now got npm ERR! publish Failed PUT 403 with "Package name too similar to existing packages; try renaming your package to '@rsp/ts-hello' and publishing with 'npm publish --access=public' instead" which is interesting because I checked if ts-hello was free on npm and I got "package 'ts-hello' not found" but now apparently this is not enough so I need to rename it! both the package and the repo, after I already created it. I'm adding this info here because I seriously got this problem right now which I didn't expect at all so to keep it real I'm adding the steps here
15. rename your package name
    • if you're lazy like me just change the "name" in package.json but if you're more serious that also rename the GitHub repo for consistency and update the remotes in your local git directory, plus upate all of the links in package.json to readme, issues etc.
16. publish the package with npm publish this time with success
17. logout from npm with npm logout
18. see your ~/.npmrc and make sure you have nothing like this left:
    • //registry.npmjs.org/:_authToken=...

Using the library in other project using ts-node

1. create a new directory
2. create a package.json file with npm init
3. install our library with npm install node-ts-hello
4. optionally install ts-node with npm install typescript ts-node (unless it's installed globally)
5. add hi.ts file that imports our library with:
   • import { hello } from 'node-ts-hello';
6. run it with npx ts-node hi.ts (if ts-node was installed locally) or ts-node hi.ts (if ts-node was installed globally)
7. get error TS2307: Cannot find module 'node-ts-hello'.
   • seriously I got this error because I forgot that npm publish ignores files that are present in .gitignore (the most important dist directory in this case!)
8. go back to your library repo and add a file .npmignore (but watch out for gotchas, see: For the love of god, don’t use .npmignore) that contains node_modules like .gitignore but not the dist directory!
9. login to npm again with npm login
10. publish new version to npm: npm publish
    • remember to update the version first
11. logout from npm with npm logout
12. upgrade the node-ts-hello version in the directory with hi.ts
13. get the same error again, this time because I forgot to change the "main": "index.js" in package.json of node-ts-hello
14. change "main": "index.js" to "main": "dist/hello.js" in package.json of node-ts-hello
15. update version
16. npm login
17. npm publish
18. npm logout
19. go back to hi.ts and update the node-ts-hello dependency again
20. remove the node-ts-hello with npm remove node-ts-hello
21. install node-ts-hello again with npm install node-ts-hello (because it was cached and didn't really update before)
22. now, it works!