Introduction

The Bandolier (aka bando) 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. It includes implementations of:

• JSON API backends.
• Multi-page and Single-page web UIs.
• Queues for offloading processing.
• Video support with HLS, HTML, and WebTorrent Video.
• Built-in Database administration and a simple ORM.
• Authentication with passport.
• Websockets with socket.io.
• Pre-made CSS components and a simple CSS design method for non-designers.
• Unit testing and UI test automation.
• Automation commands to automate the boring tasks.
• Helpful video processing in JavaScript.
• Template generators to get started with code.
• Full but simple database administrator in the browser.
• Basic Discord integration.
• Custom documentation generation for APIs using acorn.
• Includes common things you need like lucide icons, Email DNS testing, web log analysis, in an easy to extend administrator tool.
• All implemented in reasonably sized pieces of code you can study on your own.

You can think of bando as a belt full of simple useful web development code and practices that help you learn how to get things done. The idea is that everything in here is "similar" to features in other full stack web frameworks, but simplified so you can study them. Once you learn what's here you should be able to learn most other features in other frameworks.

Educational and Capable

Even though The bando is designed to be studied it doesn't mean it's useless. It's taken from real code I use for all of my websites now, and contains nearly everything you'll find in most any other framework. It's designed to be as performant, secure, and simple as possible. While it might not have every feature conceivable, it does have the ones you need to make most websites.

It also features a lot of custom components that you don't find in other web frameworks. You'll find examples of handling HLS Video Streaming, Fast Blurred Image Loading, ffmpeg video compression, Passport.js authentication, and much more. So while each feature doesn't cover every conceivable edge case, the framework does include a huge number of things everyone should learn for modern web development.

80% Done For You

A lot of the important things are also done for you while still letting you change them if you need to. For example, you shouldn't have to figure out password based authentication and encrypted password storage in 2023. So many other frameworks make people reinvent authentication when it's a completely solved problem and also a delicate thing to get right. In the bando authentication is already implemented and uses standard Passport.js with bcrypt passport storage, since that's the most recommended setup in 2023. If you want to use something else--say scrypt--then you can base your changes on my simple implementation and use the tests I have, rather than make everything from scratch.

Another example is payments. The bando contains working production code for Paypal, Stripe, and BTCPayServer. If you want to support something else then it should be easy to study my implementations and then write your own.

In general, the norm with bando is it contains most of the mundane things you might need to get started, and then replace later when you have a need for more features.

You Can Change or Remove Almost Everything

The bando is designed for you to learn new technologies without having to create an entire web application from scratch. If you want to try Actix as a backend JSON server then just make it return the same JSON on the same URLs in api/ and it should work. Don't like the ORM? You could probably replace it fairly easily. Want to learn how to use React? Just start your own React app in a new directory, and slowly bring over what you need from client/ but in React form. Don't like my CSS? All of the HTML is very simple and semantic, so you can craft almost any classless CSS you want. Converting to something like bootstrap would be some work, but you can use the client/components as a list of things to replicate in your version. Probably the most difficult thing to replace is the is the client/ directory, since admin/ and rendered/ use code from client/components, but if you really want to learn a front-end framework then replicating all of the components in client/components would be an incredible way to learn.

The reason this works is because the code in api/ doesn't really depend on anything in client/ or admin/. If it uses something in queue/ it's through a library so you can replace it easily, or possibly even use the Bull queue from your favorite backend language. Bull uses redis, and you could probably replicate it. There's also a large test suite in tests/ that you can keep running to make sure your changes are working.

Finally, all of the code is reasonably sized. Most files are about 100 - 500 lines of code with not too much convolution or deep references. You could probably pick a random file and spend a few hours to study it. Many of the source files also teach a different technique. For example, the client/fsm.js file implements a simple Finite State Machine, which is used to make HLS video work in client/components/HLSVideo.svelte. Then in client/components/WTVideo.svelte there's more traditional callback style for handling WebTorrent videos so you can learn both techniques.

Since all of this code is right there, and there's lots of tests, you can feel free to experiment while you study it. When you want to use it for something real, you can use what's there, and improve what you need for your application.

Current Status

This is a first rough ALPHA release to get the project published and get some victi^H^H^H^H^H...users testing it and telling me how it works so far. You aren't expected to be able to figure it out since I haven't completely documented it, but you should feel free to explore the code, study what's there, and see what you can do. The next release will have reference documentation and more code cleaning, then after that videos demonstrating the important features and showing how to use the tools included.

After that, further development will be focused on supporting the Learn JavaScript the Hard Way course where students will use bando to create their own projects, and also learn how to implement the important elements on this stack. Once the course is done I'll start writing more public documentation for the framework as well as more demonstrations of using it to implement common websites.

About bandolier-template

The bandolier-template is the template project that's checked out and configured when you run the npx bando-up command from ljsthw-bandolier. This is where the code really lives. The Quick Start will show you how to install everything and get a few first tasks done to test it out.

About bandolier-website

Th bandolier-website repository is the code for the bando.learnjsthehardway.com website. This demonstration site allows access to some /admin/ features such as documentation, routes browsing, and components browsing, but doesn't allow access to more sensitive things like the database. This is to demonstrate the split between /client/ and /admin/ for people curious about how they work.