workshop-setup
Verify and setup a repository for workshop attendees
The problem
I make quite a few workshops and one of the biggest challenges I have is making sure that people have set things up correctly so the workshop has as few surprises as possible. So I want to have a script validate things on attendees machines before they start on the workshop and give them helpful info to fix problems early and on their own.
The problem is further complicated by the fact that I can't use any modules to do this because I can pretty much only guarantee that attendees have some version of node and npm, but not which version. So I need something that exists when they clone the repository right from the start.
This solution
This exposes a simple function that takes an array of validators which return
strings of helpful text (or a promise that resolves to a string of helpful text)
if the system is not valid (or null
if it is valid). To overcome the issue of
not being able to install things, there is a bundled version of this module that
you can download from the registry and commit directly to your project.
Table of Contents
Installation
The way I expect people to use this module is by downloading the UMD build and
committing it directly into their project. You can download the UMD build via
npm if you like (then just copy/paste the file from node_modules
) or download
it from unpkg.com
here: https://unpkg.com/workshop-setup/dist/index.js
curl -o scripts/workshop-setup.js -L https://unpkg.com/workshop-setup/dist/index.js
This module is distributed via npm which is bundled with node and
can be installed as one of your project's devDependencies
:
npm install --save-dev workshop-setup
Usage
Here's what I recommend:
- Download the workshop-setup script into
scripts/workshop-setup.js
- Add
engines
config to yourpackge.json
withnode
,npm
, andyarn
listed - Add a
script
to yourpackage.json
calledsetup
with:node ./scripts/setup
- Create the
scripts/setup.js
file - And put this in it:
var path = var pkg = // if you install it then this should be require('workshop-setup')// but that... doesn't really make sense.
Alternative usage
Whether you install it or download it, usage is basically the same. The difference is how you require it.
// if you install it, you'd dovar workshopSetup = // if you download it, you'd do something like:var workshopSetup =
verifySystem
This allows you to verify the user's system is correct:
var verifySystem = verifySystem var verifyPromise = verifyPromise
You can also specify custom validators. There are several utilities exposed by
workshop-setup
as well which can be quite helpful.
validators
The built-in validators available on workshopSetup.verifySystem.validators
are:
node(desiredVersionRange)
yarn(desiredVersionRange)
npm(desiredNpmVersionRange)
utils
Most of the utils are simply exposing other modules which are bundled with
workshop-setup
. These are available on workshopSetup.verifySystem.utils
:
execValidator(desiredVersionRange, commandToGetVersion, messageFn)
-messageFn
is givenactual, desired
oneLine
: a tag that allows you to have multiple lines for a message and it'll put it all on one linesemver
(really usefulsatisfies
method on this one)
installDeps
This will install dependencies in the given directory/directories (defaults to
process.cwd()
) using npm
.
var path = var installDeps = installDeps var main = pathvar api = pathvar client = path // you can also do:// which is effectively // or, to be more specific:
Inspiration
This project was inspired by all of the people who have ever struggled to set up one of my workshops before. Hopefully it's easier now!
Other Solutions
I'm unaware of any other solutions for this problem. Feel free to link them here if you find any.
Contributors
Thanks goes to these people (emoji key):
Kent C. Dodds 💻 📖 🚇 ⚠️ |
---|
This project follows the all-contributors specification. Contributions of any kind welcome!
LICENSE
MIT