Workshop App Guide

Workshop Structure

Each workshop is a standalone project with a consistent structure:

• exercises/ – Contains the "problem" and "solution" versions of each step. Treat this as a reference for after the workshop.
• playground/ – This is where your work takes place. We recommend opening this directory as its own editor instance for efficient file searching.

The Lesson Page

When you click into a lesson, the app displays the video along with written content, code snippets, and other useful information. To the right is a pane with tabs:

• Playground – Where you'll spend most of your time. You can interact with the app here or open it in a dedicated tab.
• Problem – The starting point of the exercise.
• Solution – The completed exercise state.
• Diff – Compare your current version against the finished state. Use this if you get stuck, but try to avoid it if possible.
• Tests – If the exercise includes tests, they'll appear here to verify your work.

File Links

At the bottom of a lesson page, the "Files" button opens a list of relevant files for the current exercise. Clicking a file opens it directly in your editor at the right location.

Key things to know:

• Files are tied to your current Playground – make sure it's set to the lesson you're working on.
• A "+" icon next to a filename means you need to create that file. Clicking it will create and open the file.
• If you see a red "Set to Playground" link, click it to sync the playground for the current exercise.

Troubleshooting

If you're unable to open file links from the workshop app, create a .env file in the root of the workshop project and add:

Examples:

• VS Code: EPICSHOP_EDITOR=code
• VS Code on Windows: EPICSHOP_EDITOR='"C:\Program Files\Microsoft VS Code\bin\code.cmd"'
• Cursor: EPICSHOP_EDITOR=cursor

Note: If the path includes spaces, wrap it in quotes as shown in the Windows example.

For Cursor/VS Code users, you can also install the 'code' command in your PATH by opening the Command Palette (⌘⇧P on Mac, Ctrl+Shift+P on Windows) and searching for "Install 'code' command in PATH".

Setting the Playground

If you navigate to a different exercise than what's currently loaded, a red "Set to Playground" link will appear. Clicking this syncs the playground for the appropriate exercise.

Important: Always have your Playground set to the lesson you're working on! This is not automated because you might want to refer back to previous exercises without losing your current work.

The Diff Tab

The diff tab helps you get unstuck when you're totally stuck. It shows the difference between your playground and the solution. This is especially useful for catching typos or small mistakes.

• + lines (green) show code that needs to be added
• - lines (red) show code that needs to be removed
• Unchanged lines provide context around the changes

Tip: Try to avoid using the diff tab until you've made a solid attempt at the exercise. The learning happens in the struggle!

Tests

Some exercises include tests to verify your work. If available, they appear in the Tests tab. Tests can run in two ways:

• Script-based: A button runs the test script and streams the output
• Browser-based: Test files are compiled and run directly in the browser

Look for 🚨 Alfred the Alert in test failures for helpful explanations about what went wrong.

Keyboard Shortcuts

When the workshop server is running in your terminal, you can use these keyboard shortcuts:

• u – Check for and apply updates to the workshop
• d – Dismiss update notifications

The server automatically restarts after updates are applied.

CLI Commands

The epicshop CLI provides useful commands for managing your workshop:

Run epicshop --help to see all available commands.

AI Assistant (MCP)

If you use an AI assistant that supports MCP (Model Context Protocol), you can install the Epic Workshop MCP server to enhance your learning experience.

What it provides

• Exercise context: Your AI can understand what you're working on and provide relevant help
• Progress tracking: Mark lessons complete directly through your AI
• Diff viewing: Ask your AI to show you what changes are needed
• File opening: Have your AI open the relevant files in your editor
• Quiz mode: Ask your AI to quiz you on workshop topics

Installation

Add the following to your AI assistant's MCP configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "epicshop": {
      "command": "npx",
      "args": ["-y", "@epic-web/workshop-mcp"]
    }
  }
}

Make sure to run your AI assistant from within the workshop directory so the MCP server can find the right files.

Emoji Key

Each exercise has comments with helpful emoji characters:

• 👨‍💼 Peter the Product Manager – Helps you know what users want
• 🧝‍♀️ Kellie the Co-worker – Your co-worker who sometimes does work ahead of your exercises
• 🐨 Kody the Koala – Tells you when there's something specific to do
• 🦺 Lily the Life Jacket – Helps with TypeScript-specific parts
• 💰 Marty the Money Bag – Gives specific tips and sometimes code
• 📝 Nancy the Notepad – Encourages you to take notes
• 🦉 Olivia the Owl – Gives useful tidbits and best practices
• 📜 Dominic the Document – Links to useful documentation
• 💣 Barry the Bomb – Indicates code to delete
• 💪 Matthew the Muscle – Indicates you're working with an exercise
• 🏁 Chuck the Checkered Flag – Indicates a final step
• 🚨 Alfred the Alert – Shows up in test failures with explanations

Need More Help?

Visit our Support page for additional help options, including Discord access and how to report issues.