TWD streamlines testing setup with zero app code changes

The latest updates to TWD have transformed how developers set up test automation in JavaScript projects. Gone are the days of sprinkling dev-only boilerplate across application entry files. With the release of twd-js@1.8 and twd-relay@1.2, the testing framework now ships with two native Vite plugins, allowing setup to occur exclusively in vite.config.ts—without touching main.tsx.

A cleaner setup with Vite plugins

Previously, integrating TWD required adding dynamic imports, test glob patterns, and service-worker configurations directly into the app’s entry file. This approach worked but cluttered the file with dev-specific code that didn’t belong in production. The new method shifts all configuration into the Vite build pipeline. Here’s what the updated vite.config.ts looks like:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { twd } from "twd-js/vite-plugin";
import { twdRemote } from "twd-relay/vite";

export default defineConfig({
  plugins: [
    react(),
    twd({
      testFilePattern: "/**/*.twd.test.ts",
      open: false,
      position: "right",
      search: true,
    }),
    twdRemote(),
  ],
});

Meanwhile, the main.tsx file remains unaltered:

import React from "react";
import ReactDOM from "react-dom/client";
import { RouterProvider } from "react-router";
import { router } from "./routes/router";
import "./styles/index.css";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <RouterProvider router={router} />
);

The twd() plugin now manages the sidebar, test discovery, and service-worker registration, while twdRemote() auto-injects the browser client into index.html during development. Both plugins operate only in the serve mode, ensuring production builds remain unaffected.

What developers no longer need to write

To illustrate the improvement, compare the old manual setup to the new plugin-based approach. Previously, the main.tsx file required this block of dev-only code:

if (import.meta.env.DEV) {
  const { initTWD } = await import("twd-js/bundled");
  const tests = import.meta.glob("./**/*.twd.test.ts");
  initTWD(tests, {
    open: false,
    position: "right",
    serviceWorker: true,
    serviceWorkerUrl: "/mock-sw.js",
    search: true,
  });
  const { createBrowserClient } = await import("twd-relay/browser");
  const client = createBrowserClient({
    url: `${window.location.origin}/__twd/ws`,
  });
  client.connect();
}

This approach involved multiple top-level await statements, manual synchronization of service-worker URLs, and WebSocket paths—all of which had to align perfectly. The new system removes this complexity entirely, eliminating the need for conditional checks and dynamic imports.

Why this change improves developer experience

The refactor introduces three key benefits. First, it consolidates configuration into a single source of truth. Previously, parameters like serviceWorkerUrl and WebSocket paths were scattered across files and had to be manually synchronized. The plugins now manage these details internally.

Second, it eliminates top-level await for tooling. Loading the TWD runner before React mounted created unnecessary delays. With the plugins handling setup, the application entry point remains clean and straightforward.

Third, it aligns with Vite’s ecosystem conventions. Tools like @vitejs/plugin-react, Tailwind CSS, and Tanstack Router devtools already use plugin-based configurations. TWD now follows the same pattern, making it familiar to developers already working with Vite.

Support for non-Vite projects

While the new plugins simplify setup for Vite users, developers using other build tools aren’t left behind. The manual API remains available for projects based on Webpack, Angular CLI, Rollup, esbuild, or Rspack. The initTWD and createBrowserClient functions stay publicly supported, ensuring backward compatibility. For Vite projects that prefer manual control, the twdRemote({ autoConnect: false }) option provides an escape hatch to wire the browser client manually.

Next steps for developers

Adopting the new TWD setup is straightforward. Upgrade to twd-js@1.8 and twd-relay@1.2, then remove any dev-only code from your entry file. Next, add the two plugins to your vite.config.ts. Once configured, the testing framework integrates seamlessly into your development workflow without additional app code.

The official TWD runner is available at twd.dev, where developers can explore further and test the new setup in their projects.