Node CLI - Starter pack and beginner friendly-introduction

The only requirement is that you have some basic knowledge of programming fundamentals and javascript, es6 might help, but not necessary.

Contents

1. What does this provide?
2. Configuration and setup
3. Examples
   1. Introduction
   2. Templates
   3. Typesafety
   4. Tested cli interactions
   5. Automation tricks
      1. "Faster" typecheck and logging the result
      2. Check structure
4. Tech stack and requirements

What does this provide?

Back to the contents

A starter point into the CLI world for node, without some complex frameworks or local/private installations/distributions. Just some scripting, a couple of .mjs files, and even some type safety into it.

This is meant to show the possibilities and provide some pieces of the bigger picture, it is up to you how you put them together

Configuration and setup

Back to the contents

I'm using pnpm, npm or yarn will also do the job.

You don't have to, but typescript is installed, and for the complete run, you'll have to install it, you can do so by:

pnpm install # or npm or yarn

Scripts and entrypoints are executed via pnpm, you can replace them, and most can be executed like:

pnpm run [script] [...args] # or npm or yarn

Examples

Back to the contents

Introduction

Back to the examples

My recommended script order:

1. JS Hello world
2. With imports
3. Hello name
4. CLI Args parser
5. EZ Write to file
6. Write to file
7. Faster TSC
8. Type safe
9. Hello name with TypeScript

Templates

Back to the examples

Creating almost similar structures by copying and pasting folders is prone to error, mistakes, or simply, oversights. Automating that process can be crucial in bigger apps with more complex structure, even more so if the architecture is complex and you want to assure quality.

You can do so by defining templates, and how you'd like them to interact with, what should be done before creating them, and after.

Different frameworks use different files, extensions, structures, and projects and teams define the overarching architecture of it's elements, thus, it's up to you how the structure should actually be implemented.

You can even add different set of (initially failing) tests, services, queries and many more...

pnpm run make:from --template=components --name=always-use-kebab-case

It would be highly recommended to make the default case be kebab-case, serpent_case could be the only other candidate that could also assure consistency.

Typesafety

Back to the examples

It's easy to fall under the pit of writing scripts in pure javascript, or commonjs, and variants. It's not a bad thing per se but it could be improved, and it should on bigger CLIs.

Typesafety could be achieved by simplify transpiling the content. I'd recommend using .mts that would transpile to .mjs, as to maximize the JS ecosystem in newer versions and be able to import/export utilities.

In case the utilities you're using are in Javascript, and migrating them might be too much, you could declare it's content with a module declaration file (.js -> .d.ts, .cjs -> .d.cts, .mjs -> .d.mts).

Tested cli interactions

Back to the examples

At times we write code, that we don't test, and we should. CLIs are no exception and actually are a great use case and example.

Not everything in a CLI should be tested, i.e. saving a file, you'd be testing the actual system, but you could check the contents of that file looking for some specific change, even though it would be "slower", it could be necessary.

Automation tricks

Back to the examples

Manually saving the output to a log, checking some details about the system (referent to the project), a custom update script

"Faster" typecheck and logging the result

Back to the automation tricks

It's not really faster, literally, but it will seem like it, instead of visually logging the output, just save it into a file, it's almost always much faster. Plus, the advantage of having a log file you can always check as a point of reference

pnpm run faster-tsc

It will generate a log with the typescript errors, if any

Check structure

Back to the automation tricks

We can also automate the validity of our structure, it can actually make PRs/MRs easier to check, since it's one less thing to worry about.

pnpm run check-structure

This will throw an exception if something's not valid.
If you don't want to wait for every file to be checked and just want to see if at least one is wrong, earlyStopping comes to the rescue!

pnpm run check-structure --earlyStopping

You may also want to check for a flat structure validity, or that's the standard in your app, you can do so by utilizing the flat flag.

pnpm run check-structure --flat

That you can stack...

pnpm run check-structure --earlyStopping --flat

Tech stack and requirements

Back to the contents

Tech stack:

• Node
• Typescript
• Vitest (testing) and coverage packs

Requirements:

• Node v18.5.0
• NPM 8.12.1 (not used directly)
• PNPM 7.18.1 (Node Agent, should also work with NPM and YARN)