Workshop App

Code to generate React workshops. Inspired by Kent C Dodd's workshop app.

Examples

Here are some examples of available workshops:

• Live Workshop Lesson Recording
• Prerecorded Workshop Playlist
• useEffect Workshop Code
• styled-components Workshop Code
• Custom Hooks Workshop Code

Generating New Workshops

To create a new workshop from a template, run:

npx create-react-app workshop-name --use-npm --template @ihollander/cra-template-flatiron-workshop

This will create a new workshop repo with some starter code and all the necessary dependencies. It also provides a README with student-facing instructions for getting the workshop set up locally.

NOTE: The script above uses npm instead of yarn as the default package installer. There are some dependency issues with yarn that need some further investigation; in the meantime, npm works just fine.

Workshop Features

In the generated workshop repo, the folder structure looks like this:

.
├── public
└── src
    ├── __tests__
    │   └── 01.test.js
    ├── exercise
    │   ├── 01.js
    │   ├── 01.md
    │   ├── 02.html
    │   └── 02.md
    ├── solution
    │   ├── 01.extra-1.js
    │   ├── 01.js
    │   └── 02.html
    ├── index.js
    └── setupTests.js

Under the hood, the workshop repo generates routes for each exercise based on the filenames in the src/exercise and src/solution folder. You'll see the @ihollander/workshop-app code referenced in src/index.js.

Student Setup

The main README.md file in the workshop repo generated by the template has the setup instructions for students to follow. You can also send students this video, which has the setup instructions as well as a walkthrough of the features of the workshop:

• YouTube video

Adding Exercises

To add new exercises, create the following file using the following naming convention/folder structure:

• src/exercises/03.md: a readme for the exercise.
• src/exercises/03.js: starter code for a React exercise. You must have one default export in this file!.
• src/exercises/03.html: starter code for a Javascript exercise. You should include any HTML, CSS and JavaScript code as inline scripts.
• src/solutions/03.js (optional, but encouraged): solution code for the exercise.
• src/solutions/03.extra-1.js (optional): extra credit solution code. You can add multiple extra credit solutions, if you like, by following the naming convention {exercise}.extra-{number}.js.
• src/__tests__/03.test.js (optional): test code for the exercise.

The workshop app makes certain assumptions about your code based on the file type:

• md files will be used for READMEs
• js files will be used for React exercises (and must export default a component)
• html files will be used for JavaScript exercises (and must include all necessary HTML, CSS and JS within the file)

You'll need to restart the app any time you add a new file (otherwise, changes to the files will hot reload as normal).

Writing Exercise Readmes

Exercise readmes should follow this structure:

# Exercise Name

## Overview

- Add any code examples, explanatory text, etc here

## Exercise

- Explain the exercise here

### Extra Credit

- Add extra credit instructions, if any

Rendering Code Blocks

You can define a code block in the markdown, as normal:

```jsx
function App() {
  return <h1>Hello!</h1>;
}
```

You can also define a live, editable code block that will render with a preview of a component, like this:

```jsx live=true render=true
function App() {
  return <h1>Hello!</h1>;
}

render(<App />);
```

This is achieved using react-live. The code for transforming markdown code blocks to live components is done here for reference.

Note that due to limitations in react-live, you can't use import statements. However, the following variables are available in scope:

• React, useState, and useEffect
• styled and ThemeProvider from `styled-components

All code blocks with render=true must call render(<Component />).