ljsthw-bandolier/README.md

## LJSTHW Bandolier

The Bandolier is an educational web framework featured in the [Learn JavaScript the Hard Way](https://learnjsthehardway.com) course.  The Bandolier contains all of the features a full stack developer would need to learn, but with smaller easier to understand implementations that are fully visible in the project.

This repository contains an installer tool that creates Bandolier projects for you.  It downloads the code for a basic Bandolier web application using a template repository and configures it for you.  It will also provide additional management features in the future to help you while you take the course.

## Installation

> ___BIG WARNING__: If you are using an ARM Mac (M1, M2) then you are going to have problems.  You should switch to an older computer until open source project catch up because many of the projects you'll install here are going to not be available for the M1/M2 macs.

You simply use `npm` to install directly from the git repository:

```shell
npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
```

### Windows Expired Certificate Error

_WARNING_: If you get an error on Windows of "SSL certificate has expired" it's because the root
certificate for Let's Encrypt expired and your `git` is too old.  This happens on other platforms
but other OS keep their certificates and `git` commands updated.  To fix it type this:

```
git update-git-for-windows -g
```

The `-g` option says to use the graphical installer, so you'll see this:

```
Git for Windows 2.19.0.windows.1 (64bit)
Update 2.38.1.windows.1 is available
Download and install Git for Windows 2.38.1 [N/y]? y
```

Then git will open a GUI installer window to do the installation.

_IMPORTANT_:  When you get to the section that asks to use git's OpenSSL or Windows Secure Channel, pick Secure Channel. This uses the Windows encryption system which maintains accurate certificates without updating your git every time.

Once you've installed it you need to close your PowerShell/Cmdr window to register the new `git` in
the `PATH`.  After that you should be able to to type `git --version` and see the new version.

## Find the Installed Package

Once it's installed you can list your packages to confirm you installed the correct one:

```
npm list
```

The list should contain something like this:

```
ljsthw-bandolier@0.1.2 (git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git#HEXNUMBER
```

Your `HEXNUMBER` will be different from mine, but the url `git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git` should be the same.  If not then you installed the wrong thing, remove it immediately.

## Usage

You now have an `npx` command named `bando-up` which lets you create start your projects:

```
npx bando-up version
npx bando-up --help
```

This will print the version and list all of the available commands, with the most important being create:

```
npx bando-up create my-first-project
```

This will create an initial web application using the course's web framework named `Bandolier`.  It checks out the project from the `git.learnjsthehardway.com` site and then configures it so you get started.

### Installing Other Projects

Since this tool is intended to make it easier for [Learn JavaScript the Hard Way](https://learnjsthehardway.com) student it only select projects from git.learnjsthehardway.com using their names.  You use the `--using` option to specify a different project:

```shell
npx bando-up --using js-level-1-code my-js-level-1
```

This will check out the full URL `https://git.learnjsthehardway.com/learn-javascript-the-hard-way/bandolier-template.git` using `git` and then do the usual setup.  You an [view a list of all available code](https://learnjsthehardway.com) for the course.

## Updating

When there's new releases you can update with:

```
npm update ljsthw-bandolier
```

That should download any new versions, but if it doesn't then it's safe to remove the project and reinstall it:

```
npm remove ljsthw-bandolier
npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
```

## Removing

As mentioned before, you can remove the project with:

```
npm remove ljsthw-bandolier
```

## Getting the Code

If you want to see how this code works (please do), then you can check it out with `git`:

```
git clone https://git.learnjsthehardway.com/learn-javascript-the-hard-way/ljsthw-bandolier.git
```

# FAQ

Some answers to questions I'm sure I'll receive.

## Why Not use npm init?

Because `npm` (as of version 9.1.2) requires any module that implements the create mechanism be registered at npmjs.com.  Even though the documentation says that it won't when the module is installed "globally" it still checks in npmjs.com despite the module being installed locally.  Additionally, even if it did work it doesn't buy you much and adds a ton of convolution to basically run a command.

For example, here's how `npm init` should work with this project:

```
npm install git+https://git.learnjsthehardway.com/learn-javascript-the-hard-way/create-ljsthw-bandolier.git
npm init ljsthw-bandolier
```

Why all the `create` words everywhere? Because npm's init system uses a strange naming convention to determine that a project is meant to generate other projects.  When you run that final `npm init ljsthw-bandolier` command it just...runs `npm exec create-ljsthw-bandolier`, which is, you guessed it, just `npx create-ljsthw-bandolier`.  It's quite literally doing nothing adding convoluted steps to run a simple command.

However, this doesn't even work.  If you run the first `npm install` command, it works.  If you then run the `npm init ljsthw-bandolier` command it fails because `npm` _tries to confirm that npmjs.com has a module named `create-ljsthw-bandolier`_.  It's not supposed to do this because the project is actually installed, but it does anyway.  Why? Because Microsoft probably told some manager over at npm to make the User Stonks go "up and to the right!"

After trying for weeks to figure out why this didn't work I just figured out that it was completely unnecessary.  If a user installs a module, and that module has scripts in the `bin` portion of the `package.json` file, then they can just run the command with `npx`.  It's even easier and cleaner than the stupid `create-` that talks to a `create-` that talks to npmjs.com to a `create-` script that...you get the idea.

`TLDR:` Because it's actually simpler to just install a module from a git repo that has a command the user can run.

## Why Not an npm Module?

The Bandolier is designed for _you_ to change it.  You are expected to study the code, change it how you want, and learn how everything is made.  Every component in The Bandolier is small, and not feature complete _on purpose_, as that gives you room to experiment.  Placing the code directly in your own project gives you easy access, and _permission_ to make changes and see how it works.

There's a psychological and technical deterrent to changing code in `node_modules`.  There's nothing preventing you from going into `node_modules` to change the code. I do it all the time when I'm debugging, but something about it makes you feel "dirty" because it seems like it's owned by someone else.  Moving the code out of `node_modules` makes it clear _you_ can view it and change it.

The technical deterrent to changing code in `node_modules` comes from the complex ecosystem behind `npm`.  If you make changes then how can you maintain them?  You'd need to create forks of the original, submit pull requests, submit bug reports, wait for the original author to finalize the change, or create your own npmjs.com registration of your fork.  All of that is valuable to learn, but it's far too much work for someone who just wants to experiment while they're learning.

The `ljsthw-bandolier` project simplifies exploration by placing the code right there in your project.  Enjoy.

## Isn't That Unsafe?

If you think modules on npmjs.com are magically "safe" because it's a big website owned by Microsoft then you'd be very wrong.  NPM has almost no restrictions on what can be registered and has famously allowed typo-squatters to hijack projects to distribute malware. In fact, this is so common I had to register placeholders for this project in npmjs.com just in case someone tried to typo-squat it.

With `ljsthw-bandolier`, you see all of the code, and all of the changes, so you are fully informed of what will happen when you update. It's also managed on my private website at git.learnjsthehardway.com, so nobody can typo-squat it.

If you think it's dangerous to let people change the code they download, then how do you expect them to learn how that code works? Letting people make mistakes and break things isn't dangerous in an educational setting.  It's how they learn to not break things in the real world.

## Doesn't That Make Updates Difficult?

_Yes._  This is the major problem with this style of project creation.  If you installed a module using `npm` then you could easily download updates with a few commands.  Assuming the update doesn't require changes in your code you'd be done.

When the code is exported into your project it becomes much more difficult to update.  If there's updates to code you don't change then simple patches will work, but if you've modified files then you'll have to study the changes and apply them yourself.  Manually doing updates _can_ be educational, but it's definitely not optimal in a real world situation.

In the future this tool will have commands to help with updating your code, but the first release doesn't support that.

## Why Not github?

I don't want to give any more of my [property to Microsoft](https://www.saverilawfirm.com/our-cases/github-copilot-intellectual-property-litigation). They've proven they're not friends of Open Source, and any code placed on their websites will end up in their automated copyright infringement tools.