ts-ink-template

• What is this?
• npm scripts
  • Development using tsm (skip compilation)
  • Traditional approach (compile TS and run JS)
  • start script
• npm link
  • How do I change the name of the CLI app?
• IDEA Run Configurations
• How to update the template
• ESM, r3bl-ts-utils, and React
• CommonJS, ESM, r3bl-ts-utils, and React

What is this?

This is a Github template repo project that makes it easy to work w/ Ink v3 to build CLI (command line interface) apps using Node.js w/ TypeScript and Jest for testing. Make sure to run npm install after cloning this template repo on your machine. Both IntelliJ IDEA & VSCode project files are provided, so you can easily open this repo up in both IDEs.

npm scripts

There are two types of scripts provided - one using tsm to quickly run TypeScript code w/out having to compile it first, and the other using the traditional build, test, and run approach.

To run any of the following scripts you can execute npm run <SCRIPT_NAME>.

Development using tsm (skip compilation)

Task	Script	Notes
Run	start-dev	Run the dist/cli.tsx file
Run & watch	start-dev-watch	Watch for changes and re-run the dist/cli.tsx file
Run tests	test	Run all the Jest tests (no need for compiling)
Run tests & watch	test-watch	Run all the Jest tests in watch mode (no need for compiling)
Run linter	lint	Run ESLint.

Traditional approach (compile TS and run JS)

Task	Script	Notes
Run (w/out compile)	start	Run the dist/cli.js file (make sure its executable)
Compile	build	Runtsc to generate JS files in the dist folder
Compile & watch	build-watch-js	run tsc and watch for changes in TS files
Run & watch	start-watch-js	Watch for changes in JS files, and re-run
Compile, run, watch	dev-js	Run both scripts above in parallel using npm-run-all

Here are some notes on how all the watching tasks work.

1. Instead of combining the steps to compile with tsc, and run the resulting JS in node, these two are separated and run concurrently. Each one of these separate tasks watches for its own changes.
2. nodemon and ignoring unhandled exit code. This prevents nodemon from exiting when there is an error in running the JS code. Here's more background info on these exit codes.
3. npm-run-all then takes care of running these tasks in parallel and dumping their output in a terminal.

start script

1. Make sure to mark dist/cli.js file as executable so that this self executing module can run.
2. To pass command line arguments you can use npm run start -- <STUFF>
3. You can also run npm exec -c 'ink-cli-app <STUFF>'.
4. Where <STUFF> can be:

• --help
• -n Grogu
• --name Grogu

npm link

If you want to create a symlink for the executable node module in this template project, you can simply run the following command in the folder containing package.json. It will create a symlink ink-cli-app (that should be in your $PATH depending on how you installed Node.js).

$ npm link

How do I change the name of the CLI app?

The name property in package.json is ink-cli-app by default. If you want to rename it to something else, just change this property. If you want to update your symlink, then you have to run the following commands.

$ npm uninstall -g ink-cli-app
$ npm link

IDEA Run Configurations

You can also use IDEA Run Configurations that are included.

1. Run all tests - This runs all the tests in the src folder using the the jest.config.cjs file.
2. cli.js - This uses Node.js to run run the dist/cli.js file after building it.

How to update the template

You can get more info on this topic here. Here are the steps to create a remote called template that we will pull the changes from and then merge those changes into main.

git remote add template https://github.com/nazmulidris/ts-ink-template
git pull template main

CommonJS, ESM, r3bl-ts-utils, and React

This node module is compiled to CommonJS (as specified in tsconfig.json) and not ESM. Here's more information on CommonJS, ESM, and hybrid modules.

• How to create dual modules.
• Example of a dual module.
• Here's a commit from r3bl-ts-utils that applied a fix related to modules.