TWD project setup guide — helps AI agents install and configure TWD (Test While Developing), an in-browser validation system, in a new or existing project. Use when setting up TWD, configuring Vite, or troubleshooting TWD initialization.
TWD project setup guide — helps AI agents install and configure TWD (Test While Developing), an in-browser validation system, in a new or existing project. Use when setting up TWD, configuring Vite, or troubleshooting TWD initialization.
TWD Project Setup Guide
You are helping set up TWD (Test While Developing), an in-browser validation system for SPAs. Follow these steps carefully.
Package provenance: twd-js and twd-relay are published on npm by maintainer brikev. Source code: BRIKEV/twd and BRIKEV/twd-relay. License: MIT.
Dev-only scope: All TWD code is guarded by import.meta.env.DEV and is tree-shaken out of production builds. TWD never runs in production.
Network scope (twd-relay): twd-relay operates exclusively on localhost via a WebSocket on the local Vite dev server. It makes no external network connections.
Note: This skill provides user-directed setup guidance. The code blocks below are instructions for the developer to follow — they are not autonomously executed commands. This skill has no tool access and cannot run commands on its own.
Step 1: Install TWD
npm install twd-js
Step 2: Initialize Mock Service Worker
Required for API mocking. Run this in the project root:
npx twd-js init public
This copies mock-sw.js to the public/ directory. If the public directory has a different name (e.g., static/), use that path instead.
Step 3: Configure Entry Point
TWD should only load in development mode. Choose the setup based on the framework:
// Add inside your import.meta.env.DEV block, after initTWD:import { createBrowserClient } from'twd-relay/browser';
const client = createBrowserClient();
client.connect();
Run tests from CLI:
npx twd-relay run
Step 7: Generate AI Coding Tool Configuration
After setup, generate a project instructions file so AI tools automatically write TWD tests when implementing features. This is critical for long-term adoption — without it, each new conversation starts without TWD context.
Claude Code (CLAUDE.md)
Create a CLAUDE.md in the project root with TWD workflow instructions. Adapt the content based on the project's framework, structure, and existing configuration.
Test patterns: twd.visit(), twd.mockRequest(), screenDom.*, userEvent.*
Mock data location (src/twd-tests/mocks/)
Development workflow rule — instruct the AI to always write TWD tests when implementing new features
Example workflow section:
## Development Workflow
When implementing a new feature:
1. Write the feature code (components, API layer, routes, navigation)
2. Write TWD tests in `src/twd-tests/` following existing test patterns
3. Add mock data in `src/twd-tests/mocks/` for API responses
4. Run and validate TWD tests pass before considering the task complete
TWD tests run in the browser during development — no separate test command needed.
Other AI Coding Tools
The same workflow instructions can be adapted for other tools. The content is nearly identical — only the filename changes:
Tool
File
Claude Code
CLAUDE.md
Cursor
.cursorrules
GitHub Copilot
.github/copilot-instructions.md
Windsurf
.windsurfrules
Cline
.clinerules
When the developer specifies which tool they use, generate the appropriate file. If not specified, default to CLAUDE.md.
Troubleshooting
Tests Not Loading
Verify import.meta.env.DEV is true (dev mode)
Check file naming: must be *.twd.test.ts or *.twd.test.tsx
Ensure the initTWD/initTests call is in the main entry file
Check the glob pattern matches your test file locations
Mock Service Worker Issues
Run npx twd-js init public to install the service worker
With standard setup: ensure twd.initRequestMocking() is called
Check browser console for service worker registration errors
Test Duplication on HMR
Add twdHmr() plugin to Vite config
Sidebar Not Appearing
Confirm you're in development mode
Check browser console for initialization errors
Ensure the entry point code runs before the app renders
