{"id":15503842,"url":"https://github.com/kentcdodds/workshop-setup","last_synced_at":"2025-04-22T23:51:41.825Z","repository":{"id":57399318,"uuid":"84877792","full_name":"kentcdodds/workshop-setup","owner":"kentcdodds","description":"Verify and setup a repository for workshop attendees","archived":false,"fork":false,"pushed_at":"2021-01-25T23:19:55.000Z","size":230,"stargazers_count":41,"open_issues_count":2,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-15T05:03:08.528Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://unpkg.com/workshop-setup/dist/bundled/index.js","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kentcdodds.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-13T21:47:50.000Z","updated_at":"2023-10-12T05:43:36.000Z","dependencies_parsed_at":"2022-09-19T00:11:23.164Z","dependency_job_id":null,"html_url":"https://github.com/kentcdodds/workshop-setup","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentcdodds%2Fworkshop-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentcdodds%2Fworkshop-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentcdodds%2Fworkshop-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentcdodds%2Fworkshop-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kentcdodds","download_url":"https://codeload.github.com/kentcdodds/workshop-setup/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250343909,"owners_count":21415037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-02T09:14:52.960Z","updated_at":"2025-04-22T23:51:41.808Z","avatar_url":"https://github.com/kentcdodds.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# workshop-setup\n\nVerify and setup a repository for workshop attendees\n\n[![Build Status][build-badge]][build]\n[![Code Coverage][coverage-badge]][coverage]\n[![Dependencies][dependencyci-badge]][dependencyci]\n[![version][version-badge]][package] [![downloads][downloads-badge]][npm-stat]\n[![MIT License][license-badge]][license]\n\n[![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors)\n[![PRs Welcome][prs-badge]][prs] [![Donate][donate-badge]][donate]\n[![Code of Conduct][coc-badge]][coc] [![Roadmap][roadmap-badge]][roadmap]\n[![Examples][examples-badge]][examples]\n\n[![Watch on GitHub][github-watch-badge]][github-watch]\n[![Star on GitHub][github-star-badge]][github-star]\n[![Tweet][twitter-badge]][twitter]\n\n## The problem\n\nI make quite a few [workshops][workshops] and one of the biggest challenges I\nhave is making sure that people have set things up correctly so the workshop has\nas few surprises as possible. So I want to have a script validate things on\nattendees machines before they start on the workshop and give them helpful info\nto fix problems early and on their own.\n\nThe problem is further complicated by the fact that I can't use any modules to\ndo this because I can pretty much only guarantee that attendees have some\nversion of node and npm, but not which version. So I need something that exists\nwhen they clone the repository right from the start.\n\n## This solution\n\nThis exposes a simple function that takes an array of validators which return\nstrings of helpful text (or a promise that resolves to a string of helpful text)\nif the system is not valid (or `null` if it is valid). To overcome the issue of\nnot being able to install things, there is a bundled version of this module that\nyou can download from the registry and commit directly to your project.\n\n## Table of Contents\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Installation](#installation)\n- [Usage](#usage)\n  - [Alternative usage](#alternative-usage)\n  - [verifySystem](#verifysystem)\n  - [installDeps](#installdeps)\n- [Inspiration](#inspiration)\n- [Other Solutions](#other-solutions)\n- [Contributors](#contributors)\n- [LICENSE](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\nThe way I expect people to use this module is by downloading the UMD build and\ncommitting it directly into their project. You can download the UMD build via\nnpm if you like (then just copy/paste the file from `node_modules`) or download\nit from `unpkg.com` here: https://unpkg.com/workshop-setup/dist/index.js\n\n```\ncurl -o scripts/workshop-setup.js -L https://unpkg.com/workshop-setup/dist/index.js\n```\n\nThis module is distributed via [npm][npm] which is bundled with [node][node] and\ncan be installed as one of your project's `devDependencies`:\n\n```\nnpm install --save-dev workshop-setup\n```\n\n## Usage\n\nHere's what I recommend:\n\n1. Download the workshop-setup script into `scripts/workshop-setup.js`\n2. Add `engines` config to your `packge.json` with `node`, `npm`, and `yarn`\n   listed\n3. Add a `script` to your `package.json` called `setup` with:\n   `node ./scripts/setup`\n4. Create the `scripts/setup.js` file\n5. And put this in it:\n\n```javascript\nvar path = require('path')\nvar pkg = require(path.join(process.cwd(), 'package.json'))\n\n// if you install it then this should be require('workshop-setup')\n// but that... doesn't really make sense.\nrequire('./workshop-setup')\n  .setup(pkg.engines)\n  .then(\n    () =\u003e {\n      console.log(`💯  You're all set up! 👏`)\n    },\n    error =\u003e {\n      console.error(`🚨  There was a problem:`)\n      console.error(error)\n      console.error(\n        `\\nIf you would like to just ignore this error, then feel free to do so and install dependencies as you normally would in \"${process.cwd()}\". Just know that things may not work properly if you do...`,\n      )\n    },\n  )\n```\n\n### Alternative usage\n\nWhether you install it or download it, usage is basically the same. The\ndifference is how you require it.\n\n```javascript\n// if you install it, you'd do\nvar workshopSetup = require('workshop-setup')\n// if you download it, you'd do something like:\nvar workshopSetup = require('./workshop-setup')\n```\n\n### verifySystem\n\nThis allows you to verify the user's system is correct:\n\n```javascript\nvar verifySystem = require('./workshop-setup').verifySystem\n\nvar verifyPromise = verifySystem([\n  verifySystem.validators.node('^8.4.0'),\n  verifySystem.validators.npm('^5.4.1'),\n])\n\nverifyPromise.then(\n  function() {\n    // resolves if there are no errors\n    console.log('🎉  Congrats! Your system is setup properly')\n    console.log('You should be good to install and run things.')\n  },\n  function(error) {\n    // rejects if there are errors\n    console.error(error)\n    console.info(\n      \"\\nIf you don't care about these warnings, go \" +\n        'ahead and install dependencies with `node ./scripts/install`',\n    )\n    process.exitCode = 1\n  },\n)\n```\n\nYou can also specify custom validators. There are several utilities exposed by\n`workshop-setup` as well which can be quite helpful.\n\n```javascript\nverifySystem([\n  function promiseVerify() {\n    return new Promise(resolve =\u003e {\n      // note the exclusion of reject here. We expect all validator promises to\n      // resolve with `null` or the error message.\n      resolve(null) // there were no errors\n    })\n  },\n  function syncVerify() {\n    if ('cats' \u003e 'dogs') {\n      return 'dogs are way better than cats'\n    }\n    return null\n  },\n  // here's a practical example that uses some utilities\n  function validateYeoman() {\n    return verifySystem.utils.execValidator('^1.8.5', 'yo --version', function(\n      actual,\n      desired,\n    ) {\n      return verifySystem.utils.commonTags.oneLine`\n        You have version ${actual} of yeoman, but\n        should have a version in the range: ${desired}\n      `\n    })\n  },\n]).then(/* handle success/failure */)\n```\n\n#### validators\n\nThe built-in validators available on `workshopSetup.verifySystem.validators`\nare:\n\n- `node(desiredVersionRange)`\n- `yarn(desiredVersionRange)`\n- `npm(desiredNpmVersionRange)`\n\n#### utils\n\nMost of the utils are simply exposing other modules which are bundled with\n`workshop-setup`. These are available on `workshopSetup.verifySystem.utils`:\n\n- `execValidator(desiredVersionRange, commandToGetVersion, messageFn)` -\n  `messageFn` is given `actual, desired`\n- `oneLine`: a tag that allows you to have multiple lines for a message and\n  it'll put it all on one line\n- [`semver`][semver] (really useful `satisfies` method on this one)\n\n### installDeps\n\nThis will install dependencies in the given directory/directories (defaults to\n`process.cwd()`) using `npm`.\n\n```javascript\nvar path = require('path')\nvar installDeps = require('./workshop-setup').installDeps\n\nvar main = path.resolve(__dirname, '..')\nvar api = path.resolve(__dirname, '../api')\nvar client = path.resolve(__dirname, '../client')\ninstallDeps([main, api, client]).then(\n  () =\u003e {\n    console.log('👍  all dependencies installed')\n  },\n  () =\u003e {\n    // ignore, workshop-setup will log for us...\n  },\n)\n\n// you can also do:\ninstallDeps()\n// which is effectively\ninstallDeps(process.cwd())\n\n// or, to be more specific:\ninstallDeps(path.resolve('..'))\n```\n\n## Inspiration\n\nThis project was inspired by all of the people who have ever struggled to set up\none of my workshops before. Hopefully it's easier now!\n\n## Other Solutions\n\nI'm unaware of any other solutions for this problem. Feel free to link them here\nif you find any.\n\n## Contributors\n\nThanks goes to these people ([emoji key][emojis]):\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\n| [\u003cimg src=\"https://avatars.githubusercontent.com/u/1500684?v=3\" width=\"100px;\"/\u003e\u003cbr /\u003e\u003csub\u003eKent C. Dodds\u003c/sub\u003e](https://kentcdodds.com)\u003cbr /\u003e[💻](https://github.com/kentcdodds/workshop-setup/commits?author=kentcdodds) [📖](https://github.com/kentcdodds/workshop-setup/commits?author=kentcdodds) 🚇 [⚠️](https://github.com/kentcdodds/workshop-setup/commits?author=kentcdodds) |\n| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |\n\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\nThis project follows the [all-contributors][all-contributors] specification.\nContributions of any kind welcome!\n\n## LICENSE\n\nMIT\n\n[npm]: https://www.npmjs.com/\n[node]: https://nodejs.org\n[build-badge]:\n  https://img.shields.io/travis/kentcdodds/workshop-setup.svg?style=flat-square\n[build]: https://travis-ci.org/kentcdodds/workshop-setup\n[coverage-badge]:\n  https://img.shields.io/codecov/c/github/kentcdodds/workshop-setup.svg?style=flat-square\n[coverage]: https://codecov.io/github/kentcdodds/workshop-setup\n[dependencyci-badge]:\n  https://dependencyci.com/github/kentcdodds/workshop-setup/badge?style=flat-square\n[dependencyci]: https://dependencyci.com/github/kentcdodds/workshop-setup\n[version-badge]:\n  https://img.shields.io/npm/v/workshop-setup.svg?style=flat-square\n[package]: https://www.npmjs.com/package/workshop-setup\n[downloads-badge]:\n  https://img.shields.io/npm/dm/workshop-setup.svg?style=flat-square\n[npm-stat]:\n  http://npm-stat.com/charts.html?package=workshop-setup\u0026from=2016-04-01\n[license-badge]:\n  https://img.shields.io/npm/l/workshop-setup.svg?style=flat-square\n[license]:\n  https://github.com/kentcdodds/workshop-setup/blob/master/other/LICENSE\n[prs-badge]:\n  https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square\n[prs]: http://makeapullrequest.com\n[donate-badge]:\n  https://img.shields.io/badge/$-support-green.svg?style=flat-square\n[donate]: http://kcd.im/donate\n[coc-badge]:\n  https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square\n[coc]:\n  https://github.com/kentcdodds/workshop-setup/blob/master/other/CODE_OF_CONDUCT.md\n[roadmap-badge]:\n  https://img.shields.io/badge/%F0%9F%93%94-roadmap-CD9523.svg?style=flat-square\n[roadmap]:\n  https://github.com/kentcdodds/workshop-setup/blob/master/other/ROADMAP.md\n[examples-badge]:\n  https://img.shields.io/badge/%F0%9F%92%A1-examples-8C8E93.svg?style=flat-square\n[examples]:\n  https://github.com/kentcdodds/workshop-setup/blob/master/other/EXAMPLES.md\n[github-watch-badge]:\n  https://img.shields.io/github/watchers/kentcdodds/workshop-setup.svg?style=social\n[github-watch]: https://github.com/kentcdodds/workshop-setup/watchers\n[github-star-badge]:\n  https://img.shields.io/github/stars/kentcdodds/workshop-setup.svg?style=social\n[github-star]: https://github.com/kentcdodds/workshop-setup/stargazers\n[twitter]:\n  https://twitter.com/intent/tweet?text=Check%20out%20workshop-setup!%20https://github.com/kentcdodds/workshop-setup%20%F0%9F%91%8D\n[twitter-badge]:\n  https://img.shields.io/twitter/url/https/github.com/kentcdodds/workshop-setup.svg?style=social\n[emojis]: https://github.com/kentcdodds/all-contributors#emoji-key\n[all-contributors]: https://github.com/kentcdodds/all-contributors\n[workshops]: https://kentcdodds.com/workshops\n[semver]: https://www.npmjs.com/package/semver\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentcdodds%2Fworkshop-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentcdodds%2Fworkshop-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentcdodds%2Fworkshop-setup/lists"}