9.8 KiB
LJSTHW Bandolier
The Bandolier is an educational web framework featured in the Learn JavaScript the Hard Way 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:
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 student it only select projects from git.learnjsthehardway.com using their names. You use the --using option to specify a different project:
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 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. 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.