Repository files navigation

Run small JS exos in your terminal with instant feedback

Useful documents:CHANGELOG.md -How to create and maintain exos - exos.md -Brainstorming - todos.md -Development documentation - dev.md

During the WEB course at HEIG-VD, we trained with various online games or tutorials. The very visualFlexbox froggy,Elevator Saga andTypeScript exercises are just 3 examples of great online websites that let you train a specific part of web development. For HTML and CSS, this is probably a pretty good experience level, but for JavaScript and TypeScript, the online editors clearly lacks the power of local IDEs such as VSCode. When there is no "fast running" test suites backing the exercises, it becomes harder to develop it. Some of those websites focus on learning almost all possible attributes but only half of them are used very most of times.Let's take another example, thew3resource.com JavaScript array exercises, the idea of "Write a function that does X, here is some input and output examples" is good in itself, it allows to train a small concept, a few methods. But manually creating a new function, running it, printing and checking the output by hand is slow and brings a tons of friction.

We had the opportunity to work on our own idea for the latest WEB lab on condition of working with React and 2 other web technologies. We picked Ink (that uses React components) and TypeScript. Instead of doing "just another lab" without any long term utility, this was a great occasion to contribute to the course and contribute to redefine the training experience - in a more deliberate way.

The experience consists of having a way to focus on one exo after the other, show the only the related errors and a rich diff on the result, everything in watch mode reloading on file save, without leaving the comfort of our prefered IDE.

PRJS would allow to create a set of exos focused on practicing one or more concepts/functions/methods each time. It would make it easy to train on combination of various concepts to increase the level of complexity gradually.

Exos are written and ran byVitest under the hood. Vitest itself is very powerful for software test suite but not very adapted to exo test suite like we want here. The main problems are that the full test list is displayed all time, all errors are displayed in a big list, when one exo pass, it continues to fail (the next test actually) because there is no transition of "okay it's correct, let's switch to the next exo". There is no way to show more than a title for the exo, making it impossible to directly support hints, instruction, level, ...

All these problems make it very hard to focus on a single exo with all this noise around. But the watch mode of Vitest and the nice diff report is very good, this is why PRJS uses Vitest in the background and read its state when there are changes.

This project is inspired byRustlings that let you learn Rust and get used to compiler errors with small exos to implement or fix.

Note: This repository do not contains exos, it only contains the runner. The repositorysamuelroland/WEB-training is where we tried to create some exos on array and string manipulations.

You can runprjs -h you can get the list CLI flags and TUI shortcuts. You can also access the shortcuts by typing? when PRJS is started.

PRJS - Practice Runner for JavaScriptRun small JS exos in your terminal with instant feedbackUsage$ prjsOptions-v, --version: Show version-h, --help: Show this help-d, --debug: Enable debug modeCommon shortcuts? View help pageq, Ctrl+c Quit the TUIHelp shortcutsescape Escape help pagej, down Scroll downk, up Scroll upHome shortcutsl View list pageList shortcutsescape Escape search barreturn Enter a selected exoreturn Validate searchj, down Next itemk, up Previous itemh, left Switch to files listl, right Switch to exos listf Find exo by titleTrain shortcutsescape Escape exo detailsn Next exop Previous exo

If you want to have a try via the WEB-training repository

git clone https://github.com/samuelroland/WEB-trainingcd WEB-trainingnpm inpx prjs

1. The watch mode is not perfect, sometimes you need to hit Ctrl+S twice before seeing the current result/exo error.
2. If you have the messageNo test found in this folder..., because the start process is not very stable (and we don't understand why yet), here what you can try
   1. Make sure you are in the WEB-training repository, not the repository of PRJS
   2. Try to save one of the exos files (arrays/arrays.js for ex.), so the watch mode will rerun tests wake up
   3. Try typingj andk a few times, it sometimes helps
3. If you already started to implement the functions, make sure you don't have an infinite loop or a syntax error, because we don't support displaying them yet.

Debug mode

If PRJS is not working as expected, you can run in debug mode with-d or--debug and look at logs generated in the same folder asdebug.log,out.log anderr.log... You can see the progress of logs withtail liketail -f debug.log. The first file is logged generated by PRJS debug code and the 2 following are stdout and stderr of the Vitest instance programmatically started by PRJS.

If you are a student, things should already be setup in the exos repository and you should just be able to typenpx prjs to run it ! (afternpm install obviously)

If you are a teacher, you might want to defineprjs as a dependency in your repository by runningnpm install @delibay/prjs and runnpm update from time to time.

Seedev.md

See dedicated fileexos.md on how to write exos technically and strategies for easy maintenance and efficient training.

• 2024-05-22 ->2024-06-12: a group of 3 students:@samuelroland,@CamilleKoestli and@GuilhermePintodac developed the original version for a WEB course lab. They released and presented the project on the last day. Seepresentation folder for more details.See the project at the time of the lab's release 364366f905b61449da6a1bc5f8744a02037337e4
• 2024-06-18: reupload of the private repository publicly on GitHub undersamuelroland/prjs, to develop further changes in preparation of the WEB exam on the 2024-06-21.The project is in waiting of school approval to release it under a Free license. We might move the repository on Codeberg at the same time if it makes sense. The project might be used the next semester (S2 2024) by our teacher.
• 2024-09-12:@samuelroland released the first version onnpmjs.com under@delibay/prjs (becauseprjs name conflicts with a squatting packagepr.js). PRJS is going to be migrate to Delibay's Git organisation on codeberg.org later, so releasing it under this name makes sense. Before the release, he continued to fix a few bugs, implemented a partial list system, added a build system, tried to write some automated tests, and wrote a CHANGELOG.md.

You can see our slides for the lab release inpresentation made withSlidev

This project is not opened to contributions until we can apply a free software license. But you can contribute to the exos repositorysamuelroland/WEB-training !

All rights reserved for now. All contributors are okay to release it as a free software but we need to wait until we can get the approval of the school as it was developed at school... Coming in September-October 2024 I hope!