zdev Skill

Use

zdev

Prerequisites

• zdev

  CLI installed (

  bunx zdev

  or

  bun add -g zdev

  )
• Vite-based frontend project (Convex backend is optional, auto-detected)

Creating a New Project

# Basic TanStack Start project
zdev create my-app

# With Convex backend
zdev create my-app --convex

# Flat structure (no monorepo)
zdev create my-app --flat

Creates:

• TanStack Start app with clean routes

• .zdev/setup.sh

  for worktree setup
• Agentation for UI feedback (dev only)

Initializing an Existing Project

zdev init /path/to/project

Creates

.zdev/project.json

Configuration

First-time setup (or to change settings):

zdev config --set devDomain=dev.example.com
zdev config --set traefikConfigDir=/etc/traefik/dynamic
zdev config --list

Before Starting Any Feature

# Check what's already running
zdev list

If your feature already exists, just

cd

Starting a New Feature

# Start feature with public URL
zdev start <feature-name> -p /path/to/project

# Start without public URL (local only)
zdev start <feature-name> -p /path/to/project --local

# Start with seed data (Convex projects)
zdev start <feature-name> -p /path/to/project --seed

# Use different base branch
zdev start <feature-name> -p /path/to/project --base-branch main

After starting:

1. .zdev/setup.sh

   runs automatically (installs deps, etc.)
2. Note the worktree path (e.g.,

   ~/.zdev/worktrees/project-feature

   )
3. Note the local URL (e.g.,

   http://localhost:5173

   )
4. Note the public URL if available (e.g.,

   https://project-feature.dev.example.com

   )

5. cd

   to the worktree path to begin work

While Working

You're in an isolated git worktree with its own:

• Branch (

  feature/<name>

  )
• Node modules
• Convex dev instance (if applicable)
• Port allocation

Work normally. Commit often. Push when ready for review.

git add .
git commit -m "description"
git push -u origin feature/<name>

Stopping Work (End of Session)

# Stop servers but keep worktree (resume later)
zdev stop <feature-name> -p /path/to/project --keep

# Or just leave it running if you'll be back soon

Resuming Work

# Check status
zdev list

# If stopped, restart
zdev start <feature-name> -p /path/to/project

# If already running, just cd to the worktree
cd ~/.zdev/worktrees/project-feature

Presenting Output

When showing zdev output to users:

• Never put URLs inside markdown tables or code blocks — they won't be clickable
• Place URLs on their own line as plain text
• Use bold labels before URLs, not inline formatting

Example:

**Local:** http://localhost:5185
**Public:** https://project-feature.dev.example.com

NOT like this:

| Local | `http://localhost:5185` |  ← URLs not clickable!

Creating a Pull Request

# Create PR with auto-generated title and preview URL
zdev pr -p /path/to/project

# Create PR with custom title
zdev pr -p /path/to/project --title "Add user authentication"

# Create draft PR
zdev pr -p /path/to/project --draft

# Open PR in browser instead of CLI
zdev pr -p /path/to/project --web

The PR body automatically includes the preview URL.

After PR is Merged

# Clean up completely
zdev clean <feature-name> -p /path/to/project

This removes the worktree, Traefik route, and port allocation.

Quick Reference

zdev create NAME

zdev init PATH

zdev config --list

zdev list

zdev start NAME -p PATH

zdev pr -p PATH

zdev stop NAME -p PATH --keep

zdev stop NAME -p PATH

zdev clean NAME -p PATH

Troubleshooting

"Feature already exists" → It's already running. Use

zdev list

"Failed to create worktree: invalid reference" → Use

--base-branch master

Port conflict → Specify a port:

zdev start NAME --port 5200

No public URL → Run

zdev config --set devDomain=dev.example.com

Convex not working → Run

bunx convex dev

Vite "host not allowed" / 403 on preview URL →

zdev start

vite.config.ts

server.allowedHosts

devDomain

zdev config --list

devDomain

defineConfig({})

export default {}