yehyecoa-vue

yeh-yeh-CO-ah in Nahuatl means to try something; to try or experiment with something; to rehearse;

This is our own spin on the Vue Playground. Originally intended to be used within a TutorialKit (tk in this readme to save some keystrokes) preview window.

Most notably, it doesn't allow for switching Vue versions nor it displays the compiled code. Since this will be focused (at least at first) on the basic concepts, we don't want all of that.

Usage

As part of amoxtli-vue

This is the playground that will load into a preview pane in the amoxtli-vue project. It reads the different code files in the lessons provided from that repo and loads them into the monaco editor to interact with them.

Installing it in amoxtli-vue

An npm task is available for when you want to see your changes embedded into the tk project:

# build and install on tk project
npm bi

This will first build the project and then copy the required contents from the /dist folder into the amoxtli-vue/src/templates/yehyecoa/ folder.

Standalone

Note

Take a look at amoxtli-vue/src/templates/yehyecoa/server.js as it contains logic to notify yehyecoa-vue when the contents of the file have been updated. This is if you want to dynamically update the contents of the editor (and thus perfect for embedding into a tk webcontainer).

Development Environment Setup

Prerequisites

• Node.js: Version 24.5.0 (exact version specified in .node-version file and engines field)

  Recommended: Use fnm to manage Node.js versions:

  # Install fnm (if not already installed)
  curl -fsSL https://fnm.vercel.app/install | bash
  
  # Use the project's Node.js version (reads .node-version automatically)
  fnm use
  
  # Or install and use the specific version
  fnm install 24.5.0
  fnm use 24.5.0

• pnpm: Version 10.17.0 (specified as packageManager)

  npm install -g [email protected]

Recommended IDE Setup

VSCode + Volar (and disable Vetur) + ESLint + UnoCSS

Recommended VSCode Extensions

• Vue.volar - Vue language support
• dbaeumer.vscode-eslint - ESLint integration
• antfu.unocss - UnoCSS IntelliSense
• bradlc.vscode-tailwindcss - TailwindCSS IntelliSense (for CSS utilities)
• Vue.vscode-typescript-vue-plugin - Vue TypeScript support

Project Architecture

This is a pnpm workspace with multiple packages:

• Root: Main Vue application with real-time collaboration
• packages/party-kit/: PartyKit server for WebSocket communication
• packages/vue-repl/: Enhanced Vue REPL component (forked from @vue/repl)
• packages/shared-types/: Shared TypeScript types

Installation

1. Clone and install dependencies:

   git clone <repository-url>
   cd yehyecoa-vue
   pnpm install

2. Install dependencies for all workspace packages:

   # This installs dependencies for all packages in the workspace
   pnpm install --recursive

Development Workflow

Option 1: Full Development Setup (Recommended)

For complete real-time collaboration features, you need both the main app and PartyKit server:

1. Start the PartyKit server (in a separate terminal):

   cd packages/party-kit
   pnpm dev

   This starts the WebSocket server at http://localhost:1999

2. Start the main application (in another terminal):

   # From project root
   pnpm dev

   This starts the Vue app at http://localhost:5173

Option 2: Frontend Only Development

If you're only working on UI components and don't need real-time features:

pnpm dev

Note

Without the PartyKit server, collaboration features will be disabled but the REPL will still function as a standalone editor.

Option 3: Working on vue-repl Package

If you're modifying the core REPL functionality:

cd packages/vue-repl
pnpm dev

Available Scripts

Root Package Scripts

• pnpm dev - Start development server with hot reload
• pnpm build - Build for production (includes all optimizations)
• pnpm preview - Preview production build
• pnpm type-check - Run TypeScript type checking
• pnpm lint - Lint the main package
• pnpm lint:all - Lint all packages in workspace
• pnpm lint:fix - Auto-fix linting issues

Specialized Scripts

• pnpm bi - Build and Install: Build project and copy to amoxtli-vue
• pnpm sync:vue-repl - Sync with upstream vue-repl fork
• pnpm sync:party-kit - Sync with upstream party-kit fork

Environment Configuration

The project uses:

• UnoCSS for utility-first CSS with multiple presets
• Monaco Editor for code editing with TypeScript support
• Pinia for state management
• PartyKit for real-time WebSocket communication
• Vite for build tooling and development server

Type Support for .vue Imports in TS

TypeScript cannot handle type information for .vue imports by default, so we replace the tsc CLI with vue-tsc for type checking. In editors, we need Volar to make the TypeScript language service aware of .vue types.

Testing

# Run tests for party-kit package
cd packages/party-kit
pnpm test

# Run tests with coverage
pnpm test:coverage

Troubleshooting

Common Issues

1. Node version mismatch: Ensure you're using Node.js 24.5.0+
2. pnpm version issues: Use the exact version specified (10.17.0)
3. WebSocket connection fails: Make sure PartyKit server is running on port 1999
4. Monaco Editor not loading: Check that workers are properly bundled (handled by build scripts)

Workspace Dependencies

If you encounter issues with workspace packages:

# Clean and reinstall all dependencies
pnpm clean
rm -rf node_modules packages/*/node_modules
pnpm install

# Rebuild all packages
pnpm -r run build

Build and Deployment

Production Build

pnpm build

This will:

1. Type-check all files
2. Build the main application
3. Minify workers and assets
4. Build the server component
5. Compress assets for optimal loading

TutorialKit Integration Build

pnpm bi

This builds the project and copies the distribution files to the amoxtli-vue template directory.

Customize Configuration

See Vite Configuration Reference and UnoCSS Configuration.