Launch your Workshop App Experience

#It's better in the Workshop App

For each of our Epic Web workshops, there's a corresponding Workshop App repository available for you to clone and run on your own computer. For the best experience we highly recommend you use the Epic Web workshop application on your local machine. It allows you to authenticate and work through the material as intended at your own pace.

Also, while you can work through these workshops in any order, they build upon each other linearly and you'll have the best experience by going through them in order.

#Available Workshop Apps

#How to Use the Workshop App

Each includes a README with a list of prerequisites and other resources to help you prepare for the workshop. Be sure to review those before you start the workshop!

#Workshop App Setup

After cloning a workshop repo, run the npm run setup command to install dependencies and verify your system is ready to go.

This setup script will verify that your system has the right versions of necessary tools (Node, npm, etc). If not, it will let you know what versions you need to upgrade to, and request your approval to automatically install dependencies as needed.

If something goes wrong with the setup script, you'll likely see it in a clear error message. If you need help, please open an issue in the workshop's respective repository.

#Workshop App Structure

Each workshop app is a standalone project. The directory structure will vary a bit from workshop to workshop, but there are some commonalities.

The exercises directory contains the "problem" and "solution" versions of each of the steps of the workshop, but is not meant for you to work from. Treat the exercises directory as a reference for after the workshop!

The playground directory is where your work will take place. It is suggested to open the playground directory as its own VS Code instance so you can more efficiently search for specific files by name. To do this, navigate to a workshop's directory and run code playground.

In some workshops, you’ll be required to run commands. In some cases you’ll need to run these in the root workshop directory and in others you’ll need to run them in the playground directory. So we’ll always specify where commands should be run. During the exercises, you’ll mostly be running commands in the playground directory.

#Running a Workshop App

Inside a terminal, navigate to a workshop app's directory and run: npm start

This will start the KCDShop app at localhost:5639, and provide a quick link to open it in your browser.

If an exercise requires you to view the server logs, they will be displayed in this terminal where you ran the npm start command. Each workshop app will have a similar structure.

The homepage of the app contains a list of each of the workshop modules on the home page, as well as a writeup of the workshop's goals and objectives.

The navigation sidebar also contains a list of the workshop modules which expand to show the exercises for each. Inside of the navigation sidebar, the playground slide emoji 🛝 corresponds to the current exercise the playground is set to.

#The Lesson Page

When you click into a lesson, the app will display the video along with written content, code snippets, and other useful information for completing an exercise. Filename links in the lesson text will open in your local editor.

To the right of the lesson video & text is a pane with tabs for Playground, Problem, Solution, and Diff. If the exercise step includes tests to verify your work, there will also be a Test tab. Some of these tabs includes a "Run App" button that allows you to interact with the app at the current state of the exercise.

The Playground tab is where you will spend most of your time during the workshop. You can either interact with the app from here, or click the button to open it in a dedicated tab. This is recommended if you want to use DevTools during your work.

The Problem tab will load the application at the starting point of the exercise, and the Solution tab will load the completed exercise state. This can be useful if you want to review how the app is supposed to behave before you’ve made any changes or how it’s supposed to behave when you’re finished.

The Diff tab allows you to compare your current version of a Playground file against the "finished" state. This feature is here in case you get totally stuck, but it's recommended to avoid using it if possible.

#The Files List

At the bottom of a lesson page the "Files" button will open a list of the relevant files you'll be working with for the current exercise. Clicking on a file will open it in your editor. This is a nice way to quickly navigate to a file you need to work on, but note that it is tied to your current Playground.

If necessary, the Files list will include a "+" icon next to filenames that an exercise requires you to create. Clicking this icon will create the file for opening in your editor.

#Setting the Playground

If you navigate to a different exercise than the one that is currently loaded, a red "Set to Playground" link will appear in the navigation breadcrumbs and files list. Clicking this will sync the playground for the appropriate exercise so you can work on it.

It is important to have your Playground set to the lesson you are working on!

Note that this is not automated, because there are times when you might want to refer back to a previous exercise without losing your current work.

#Troubleshooting Workshop File Links

If you are unable to open file links from the workshop app, create a .env file in the root of this project and add an environment variable called KCDSHOP_EDITOR with the value being set to the path to your editor's executable. For example, if you're using VS Code on Windows, you'd add this to your .env file:

Make certain that if the path includes spaces that you wrap the path in quotes as above (note the use of single quotes wrapping the double quotes!).

The value of KCDSHOP_EDITOR should be the command that you would run in your terminal to open your editor from the command line. This means, the first thing should be the path to the executable for your editor (or the command if you have one in your PATH). So you may be able to get away with doing something as simple as this: KCDSHOP_EDITOR=code

If you're working with VSCode, you have another option. You can accomplish this by accessing the Command Palette (using the shortcut ⌘⇧P) and entering "shell command". You may want to consider uninstalling it first and then proceed to "Install 'code' command in PATH."

#Emoji Key

Each exercise has comments in it to help you get through the exercise. These fun emoji characters are here to help you.

• Peter the Product Manager 👨‍💼 helps us know what our users want

• Kellie the Co-worker 🧝‍♀️ your co-worker who sometimes does work ahead of your exercises

• Kody the Koala 🐨 will tell you when there's something specific you should do

• Lily the Life Jacket 🦺 will help you with any TypeScript-specific parts of the exercises

• Marty the Money Bag 💰 will give you specific tips (and sometimes code) along the way

• Nancy the Notepad 📝 will encourage you to take notes on what you're learning

• Olivia the Owl 🦉 will give you useful tidbits/best practice notes

• Dominic the Document 📜 will give you links to useful documentation

• Barry the Bomb 💣 will be hanging around anywhere you need to blow stuff up (delete code)

• Matthew the Muscle 💪 will indicate that you're working with an exercise

• Chuck the Checkered Flag 🏁 will indicate that you're working with a final

• Alfred the Alert 🚨 will occasionally show up in the test failures with potential explanations for why the tests are failing