Zed A. Shaw
||2 months ago|
|commands||6 months ago|
|lib||6 months ago|
|tests/commands||6 months ago|
|.gitignore||6 months ago|
|LICENSE||6 months ago|
|README.md||2 months ago|
|bando.js||6 months ago|
|bando.ps1||6 months ago|
|package-lock.json||6 months ago|
|package.json||6 months ago|
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.
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:
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
-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
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:
The list should contain something like this:
HEXNUMBER will be different from mine, but the url
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
--using option to specify a different project:
npx bando-up create --using js-level-1-code my-js-level-1
This will check out the full URL
git and then do the usual setup. You an view a list of all available code for the course.
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:
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
Some answers to questions I'm sure I'll receive.
Why Not use npm init?
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:
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.
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.
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.