@nativele/ts-dom 0.5.0 → 0.5.2

package/skills/nativele-testing/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: nativele-testing
+description: "Test Nativele components in an app: component tests with Vitest and happy-dom (or jsdom), real-browser tests with Vitest browser mode in headless Chrome, and page tests with Playwright. Covers generating the templates before tests, creating elements, props, events, lists, data-if, stores, slots, test isolation, and what a DOM shim cannot show. Use when a project depends on @nativele/ts-dom and on vitest, @playwright/test or playwright."
+metadata:
+  tier: official
+  nativele: ">=0.5.2 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vitest@5.1.0 happy-dom@21.0.4 jsdom@30.1.3 @vitest/browser-playwright@5.1.0 playwright@1.64.1 @playwright/test@1.64.1 vite@8.3.6 typescript@7.0.2"
+  author: "Nativele maintainers"
+  detects: "vitest @playwright/test playwright"
+---
+
+# Testing Nativele components
+
+## When to use
+
+- An app that already uses Nativele (`@nativele/ts-dom`) and needs tests for its components: rendering, props, events, lists, `data-if`, stores and slots.
+- Signals: `@nativele/ts-dom` together with `vitest`, `@playwright/test` or `playwright` in `package.json`, or a request to add tests to a project with `.html` templates and `define()` calls.
+- The starting point is a Vite app with Nativele set up as in the `nativele-vite` Skill (`npm create vite@latest -- --template vanilla-ts`, the `tsDom()` plugin in `vite.config.ts`, components in `src/nv/`). This Skill adds only what testing Nativele needs; it does not teach Vitest or Playwright.
+- Not for writing the components (`npx ts-dom skills add nativele-core`), and not for testing the library itself.
+
+The recommended path is Vitest: component tests in happy-dom, and the few behaviors a DOM shim gets wrong in Vitest browser mode on headless Chrome. The alternative is Playwright Test for tests of whole built pages.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.2 |
+| vitest | 5.1.0 |
+| happy-dom | 21.0.4 |
+| jsdom | 30.1.3 (the same component tests pass; not the recommended environment) |
+| @vitest/browser-playwright | 5.1.0 |
+| playwright | 1.64.1 (used only to drive the installed Chrome; no browser is downloaded) |
+| @playwright/test | 1.64.1 |
+| vite | 8.3.6 |
+| typescript | 7.0.2 |
+
+Verified on 2026-11-05 with Node 24 and Google Chrome 148, starting from `create-vite` 9.3.4 with the `vanilla-ts` template, with the example project in the Nativele repository (`skills/nativele-testing/example`), which CI runs again when the example or the library changes and once a month. Vitest 5 changed its configuration (`test.api`, `test.projects`, providers as separate packages); with Vitest 4 or older, or another major version of any tool above, treat every step as unverified.
+
+## Set-up
+
+1. Install the test tools:
+
+   ```sh
+   npm i -D vitest@5.1.0 happy-dom@21.0.4
+   ```
+
+2. Put the test configuration in the same `vite.config.ts` that has `tsDom()`, so Vitest loads the plugin. The plugin writes the generated `x.html.ts` files and `ts-dom-tags.ts` when Vitest starts, so `vitest run` works on a clean checkout with nothing generated yet. A separate `vitest.config.ts` replaces `vite.config.ts` for Vitest; if the project has one, add `tsDom({ dirs: ["src/nv"] })` to its `plugins` too (see Troubleshooting).
+
+   ```ts
+   // vite.config.ts
+   import { defineConfig } from "vitest/config";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({
+     plugins: [tsDom({ dirs: ["src/nv"] })],
+     test: {
+       projects: [
+         { extends: true, test: { name: "unit", include: ["test/**/*.test.ts"], exclude: ["test/**/*.browser.test.ts"], environment: "happy-dom" } },
+       ],
+     },
+   });
+   ```
+
+3. Keep the tests in `test/` and add it to `include` in `tsconfig.json` (`"include": ["src", "test"]`). Vitest does not type-check; `ts-dom check src/nv` runs the project's `tsc`, which then checks the tests too, and `ts-dom-tags.ts` types `document.createElement("counter-card")` as the component class, with its props.
+4. Add the scripts:
+
+   ```sh
+   npm pkg set scripts.test="vitest run --project unit"
+   ```
+
+   Keep `ts-dom check src/nv` in the build script (as `nativele-vite` sets it up) or run it before or after the tests: it is what reports type errors in the tests and the templates.
+
+5. For the real-browser tests, install the Vitest provider and Playwright, and add a second project. It drives the Chrome already installed on the machine (`CHROME_BIN`, or `/usr/bin/google-chrome`, which GitHub's `ubuntu-latest` runners have), so nothing is downloaded and `npx playwright install` is not needed:
+
+   ```sh
+   npm i -D @vitest/browser-playwright@5.1.0 playwright@1.64.1
+   npm pkg set scripts.test:browser="vitest run --project browser"
+   ```
+
+   ```ts
+   // vite.config.ts: the browser project, next to "unit" in test.projects
+   import { playwright } from "@vitest/browser-playwright";
+
+   const chrome = process.env.CHROME_BIN ?? "/usr/bin/google-chrome";
+
+   {
+     extends: true,
+     test: {
+       name: "browser",
+       include: ["test/**/*.browser.test.ts"],
+       api: { port: 63432, strictPort: true },
+       browser: {
+         enabled: true,
+         headless: true,
+         provider: playwright({ launchOptions: { executablePath: chrome, args: ["--no-sandbox", "--no-zygote", "--disable-gpu", "--disable-dev-shm-usage"] } }),
+         instances: [{ browser: "chromium" }],
+       },
+     },
+   },
+   ```
+
+   `headless: true` keeps the run the same locally and in CI. The launch arguments suit containers, WSL and CI runners. Name only the tests that need a real browser `*.browser.test.ts` (limitation 1); everything else stays in happy-dom, which starts in a fraction of the time.
+
+6. Alternative, for tests of whole pages (the built app, every component on it, navigation): Playwright Test against `vite preview`, with the same Chrome:
+
+   ```sh
+   npm i -D @playwright/test@1.64.1
+   npm pkg set scripts.test:e2e="playwright test"
+   ```
+
+   ```ts
+   // playwright.config.ts
+   import { defineConfig } from "@playwright/test";
+
+   const chrome = process.env.CHROME_BIN ?? "/usr/bin/google-chrome";
+
+   export default defineConfig({
+     testDir: "e2e",
+     use: {
+       baseURL: "http://localhost:4432",
+       launchOptions: { executablePath: chrome, args: ["--no-sandbox", "--no-zygote", "--disable-gpu", "--disable-dev-shm-usage"] },
+     },
+     webServer: { command: "npm run build && npx vite preview --port 4432 --strictPort", url: "http://localhost:4432" },
+   });
+   ```
+
+   Add `e2e` to `include` in `tsconfig.json` so `ts-dom check` type-checks the specs, and `test-results` and `playwright-report` to `.gitignore`.
+
+## Example
+
+The component under test (from the example project, `src/nv/counter-card.*`):
+
+```html
+<!-- src/nv/counter-card.html -->
+<style scoped>
+  b { color: rgb(200, 0, 0); }
+</style>
+<p>{{ label }}: <b>{{ count }}</b></p>
+<button type="button" data-on-click="increment">+1</button>
+<p data-if="many">That is a lot.</p>
+```
+
+```ts
+// src/nv/counter-card.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./counter-card.html.js";
+
+export class CounterCard extends Component(tpl, {
+  props: { label: "Count" },
+  state: { count: 0 },
+  derive: { many: (s) => s.count >= 3 },
+  emits: { "count-change": event<{ count: number }>() },
+}) {
+  increment(): void {
+    this.set({ count: this.state.count + 1 });
+    this.emit("count-change", { count: this.state.count });
+  }
+}
+define("counter-card", CounterCard);
+```
+
+Its tests, in happy-dom:
+
+```ts
+// test/counter-card.test.ts
+import { afterEach, expect, test } from "vitest";
+import type { EmitEvent } from "@nativele/ts-dom";
+import "../src/nv/counter-card.ts";
+import type { CounterCard } from "../src/nv/counter-card.ts";
+
+afterEach(() => document.body.replaceChildren());
+
+function mount(label?: string): CounterCard {
+  const el = document.createElement("counter-card");
+  if (label !== undefined) el.label = label;
+  document.body.append(el);
+  return el;
+}
+
+test("renders when it is appended, with props set as properties before", () => {
+  const el = document.createElement("counter-card");
+  el.label = "Clicks";
+  expect(el.childNodes.length).toBe(0);
+  document.body.append(el);
+  expect(el.querySelector("p")?.textContent).toBe("Clicks: 0");
+});
+
+test("a prop changed later, as a property or an attribute, renders at once", () => {
+  const el = mount();
+  el.label = "Taps";
+  expect(el.querySelector("p")?.textContent).toBe("Taps: 0");
+  el.setAttribute("label", "Hits");
+  expect(el.querySelector("p")?.textContent).toBe("Hits: 0");
+});
+
+test("emit: listen on the element, read detail; the event does not bubble", () => {
+  const el = mount();
+  const details: { count: number }[] = [];
+  let heardByDocument = 0;
+  el.addEventListener("count-change", (e) => details.push((e as EmitEvent<CounterCard, "count-change">).detail));
+  document.addEventListener("count-change", () => heardByDocument++);
+  el.querySelector("button")!.click();
+  el.querySelector("button")!.click();
+  expect(details).toEqual([{ count: 1 }, { count: 2 }]);
+  expect(heardByDocument).toBe(0);
+});
+
+test("data-if: the block is absent until its value is truthy", () => {
+  const el = mount();
+  const lots = () => [...el.querySelectorAll("p")].some((p) => p.textContent === "That is a lot.");
+  for (let i = 0; i < 2; i++) el.querySelector("button")!.click();
+  expect(lots()).toBe(false);
+  el.querySelector("button")!.click();
+  expect(lots()).toBe(true);
+});
+```
+
+The steps every test follows:
+
+1. Import the component module for its side effect (`import "../src/nv/counter-card.ts"`): that runs `define()`. A type-only import registers nothing (limitation 2).
+2. Create the element with `document.createElement(tag)`; set object, array and other props as properties (`el.todos = [...]`), before or after appending. String, number and boolean props can also be attributes.
+3. Append it to `document.body`. A Light DOM component has no children until it is connected; a component renders when it is appended.
+4. Assert at once. Rendering is synchronous: after `append`, a prop assignment, `setAttribute`, `el.click()` or `store.set()`, the DOM is already updated, and `emit` listeners have already run. For a form, set the input's `value`, then call `click()` on its submit button or `form.requestSubmit()`: both run the template's `data-on-submit` handler, in happy-dom too. The only waits are for slot changes made after connection (one microtask, below).
+5. Empty the document in `afterEach` (`document.body.replaceChildren()`): removing the elements runs `disconnected()` and ends their `bind`, `on` and `onCleanup` registrations.
+
+Other parts of the API, as in the example project's tests:
+
+```ts
+// lists (test/todo-list.test.ts): items as components; an item's event reaches the parent with hit.key
+const el = document.createElement("todo-list");
+el.todos = todos;
+document.body.append(el);
+expect([...el.querySelectorAll("todo-row")].map((r) => r.textContent?.trim())).toEqual(["Write tests", "Run them"]);
+expect(el.lists.todos.items).toEqual(todos);
+el.querySelectorAll("todo-row")[1]!.querySelector("input")!.click();
+expect(el.state.done).toEqual([2]);
+
+// stores and bind (test/user-badge.test.ts): reset the shared store before each test
+beforeEach(() => session.set({ user: "guest" }));
+session.set({ user: "Ada" });
+expect(el.textContent?.trim()).toBe("Signed in as Ada");
+
+// Light DOM slots (test/panels.test.ts): children present at connection are placed at once;
+// a child added later is placed by a MutationObserver, after one microtask
+el.append(title);
+await Promise.resolve();
+expect(el.assignedNodes("title")).toEqual([title]);
+
+// Shadow DOM slots: the template is in el.shadowRoot; the native slotchange event also fires after one microtask
+el.shadowRoot!.querySelector("slot[name=title]")!.addEventListener("slotchange", onChange);
+```
+
+A real-browser test, for what happy-dom cannot show (limitation 1):
+
+```ts
+// test/move.browser.test.ts
+import { afterEach, expect, test, vi } from "vitest";
+import "../src/nv/todo-list.ts";
+import { TodoRow, type Todo } from "../src/nv/todo-row.ts";
+
+afterEach(() => {
+  document.body.replaceChildren();
+  vi.restoreAllMocks();
+});
+
+const todos: Todo[] = [
+  { id: 1, title: "Write tests", done: false },
+  { id: 2, title: "Run them", done: true },
+];
+
+test("Chrome moves a list item with moveBefore: it stays connected and keeps focus", () => {
+  expect("moveBefore" in Element.prototype).toBe(true);
+  const el = document.createElement("todo-list");
+  el.todos = todos;
+  document.body.append(el);
+  const disconnected = vi.spyOn(TodoRow.prototype, "disconnected");
+  const connected = vi.spyOn(TodoRow.prototype, "connected");
+  const input = el.querySelector("todo-row input") as HTMLInputElement;
+  input.focus();
+  el.todos = [todos[1]!, todos[0]!];
+  expect(el.querySelectorAll("todo-row input")[1]).toBe(input);
+  expect(disconnected).not.toHaveBeenCalled();
+  expect(connected).not.toHaveBeenCalled();
+  expect(document.activeElement).toBe(input);
+});
+```
+
+Under happy-dom this test fails: there is no `moveBefore`, both callbacks run and the input loses focus. The example's `test/todo-list.test.ts` asserts the happy-dom behavior, so a later happy-dom release that adds `moveBefore` shows up as a failing test. The Vitest API in browser mode is the same: the example's other happy-dom tests also pass unchanged when run in the browser project, so moving a test there is a matter of renaming it.
+
+A page test with Playwright (the alternative):
+
+```ts
+// e2e/app.spec.ts
+import { expect, test } from "@playwright/test";
+
+test("the built page renders the components and they respond", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("pageerror", (e) => errors.push(e.message));
+  await page.goto("/");
+  const counter = page.locator("counter-card");
+  await expect(counter.locator("p").first()).toHaveText("Clicks: 0");
+  await counter.getByRole("button", { name: "+1" }).click();
+  await expect(counter.locator("b")).toHaveText("1");
+  await expect(page.locator("todo-list todo-row")).toHaveText(["Write tests", "Run them in Chrome"]);
+  await expect(page.locator("light-panel h2")).toHaveText("Light");
+  await expect(page.locator("shadow-panel h2")).toHaveText("Untitled");
+  await expect(page.getByRole("heading", { name: "Shadow" })).toBeVisible();
+  expect(errors).toEqual([]);
+});
+```
+
+Playwright locators reach into open shadow roots, so `page.locator("shadow-panel h2")` finds the heading inside a `shadow: true` component; its text is the slot fallback, not what is shown (limitation 6).
+
+## Known limitations
+
+1. **What happy-dom does not have.** happy-dom 21 (and jsdom 30) have no `Element.prototype.moveBefore`, so a list item that moves on reorder is taken out and put back: `disconnected()` and `connected()` run, `bind` subscriptions end and start again, and a focused input in it loses focus. Chrome 148 has `moveBefore`, and the same move runs neither callback and keeps focus. Test moves and focus in a `*.browser.test.ts`. Everything else the example covers behaves the same in happy-dom, jsdom and Chrome: custom elements and attribute changes, `MutationObserver` (Light DOM slots), Shadow DOM, native slots and `slotchange`, events, lists, `data-if` and stores. Computed styles are not reliable in a DOM shim (jsdom ignores the `@scope` rule that `<style scoped>` produces; happy-dom applies it); assert styles, layout and real input in the browser.
+2. **Import the module, not only the type.** `import type { CounterCard }` (or `import { type CounterCard }`) is erased, so `define()` never runs: `document.createElement("counter-card")` returns a plain element that never renders, and `tsc` still types it as `CounterCard` through `ts-dom-tags.ts`. The symptom is `expected undefined to be ...` or `Cannot read properties of null (reading 'click')`. Add `import "../src/nv/counter-card.ts"`. Child components used in a template are imported by its generated module, so importing the parent is enough.
+3. **One registry per test file.** Vitest runs each test file in a new environment by default (`isolate: true`), in happy-dom and in browser mode: each file starts with an empty document and an empty `customElements`. Inside a file, the document and the registry are shared by all its tests, so empty the document in `afterEach`. With `isolate: false` and the files run one after another in the same worker (`--no-isolate --no-file-parallelism`), they share both: the document keeps the previous file's elements, and a direct `customElements.define()` of a name already defined throws.
+4. **A tag cannot be redefined.** `define()` with a name that is already defined does nothing and keeps the first class; `customElements.define()` throws an error whose message says the name is already used or registered (in happy-dom, jsdom and Chrome). `vi.resetModules()` followed by a new `import()` creates a new class and new module-level stores, but the tag keeps running the first class, bound to the first store. Reset shared stores with `store.set(...)` in `beforeEach` instead, and give a component defined only for one test file a name no other module uses.
+5. **Do not add a `data-ref` only for a test.** `ts-dom check` reports a ref that the component class never reads as `unused-ref`, and access from a test does not count. Query the rendered DOM in the test (`el.querySelector("button")`, `el.shadowRoot.querySelector(...)`, `el.assignedNodes(name)`). The same applies to the oxlint rule: turn `ts-dom/unused-markup` off for test folders, as the setup guide says.
+6. **Text of a slotted heading in a Shadow DOM component.** `textContent` (and Playwright's `toHaveText` on the element inside the shadow root) reads the slot's fallback content, not the slotted nodes: in the example, `shadow-panel h2` has the text `Untitled` while it shows `Shadow`. Read the slot with `el.assignedNodes(name)`, or in Playwright use `getByRole("heading", { name: "Shadow" })`, which follows what is shown. A Light DOM component has the slotted nodes in place, so its text is what is shown.
+7. **Slot changes after connection are asynchronous.** Children added to a Light DOM component after it is connected are placed by a `MutationObserver`, and `slotchange(name)` runs then; for a Shadow DOM component, the native `slotchange` event fires at the same point. `await Promise.resolve()` once before asserting is enough in happy-dom, jsdom and Chrome. Children present when the element is appended are placed synchronously.
+8. **Typing custom events.** `addEventListener` types an unknown event name as `Event`, so `e.detail` is a `tsc` error (`TS2339`); cast with `EmitEvent<CounterCard, "count-change">`.
+9. Not verified: Vitest watch mode after a template change, Vitest 4 or older, browsers other than Chrome, Playwright's downloaded browsers (`npx playwright install`) instead of the installed Chrome, `@vitest/browser-webdriverio`, and testing components inside a UI framework (see that framework's Skill).
+
+## Verify
+
+Run in the project:
+
+```sh
+npx vitest run --project unit      # expect: every test file passes, on a clean checkout too
+npx ts-dom check src/nv            # expect: ts-dom check: no issues (this type-checks the tests)
+npx ts-dom doctor src/nv           # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npx vitest run --project browser   # expect: the *.browser.test.ts files pass in headless Chrome
+npx playwright test                # if you use the alternative: builds, serves on port 4432, passes
+```
+
+The example project's `verify` script runs exactly these, plus the same unit tests under jsdom as a third Vitest project (`"environment": "jsdom"`), which shows that jsdom works for the same tests. Its tests prove each limitation above: the module import, per-file isolation, `define()` twice, `vi.resetModules()`, slot timing in both modes, and the move that happy-dom and Chrome handle differently.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Error: Failed to resolve import "./counter-card.html.js" from "src/nv/counter-card.ts". Does the file exist?` | Vitest runs without the `tsDom()` plugin (a `vitest.config.ts` without it replaces `vite.config.ts`), and nothing generated the files | add `tsDom({ dirs: ["src/nv"] })` to the config Vitest loads, or run `ts-dom gen src/nv` before the tests |
+| `expected undefined to be '...'`, `Cannot read properties of null (reading 'click')` on a freshly appended element | the component module was imported only as a type, so the tag is not defined | `import "../src/nv/x.ts"` (limitation 2) |
+| `TS2339: Property 'detail' does not exist on type 'Event'` from `ts-dom check` | the listener's event is a plain `Event` | cast with `EmitEvent<Component, "event-name">` |
+| `TS2339: Property 'label' does not exist on type 'HTMLElement'` on `document.createElement("counter-card")` | `tsc` ran without `ts-dom-tags.ts` (nothing generated it), or the component class is not exported | run `ts-dom check src/nv` instead of plain `tsc`; export the class |
+| `src/nv/x.html:1:1 error [unused-ref] data-ref="..." is never used by the component class` | a ref added for a test | query the DOM in the test and remove the ref (limitation 5) |
+| A test passes alone and fails with others in the same file, or sees elements from another test | the document is shared within a file | `afterEach(() => document.body.replaceChildren())`; reset module-level stores in `beforeEach` |
+| `Error: browserType.launch: Failed to launch chromium because executable doesn't exist at /usr/bin/google-chrome` | no Chrome at that path | set `CHROME_BIN` to the Chrome or Chromium binary |
+| `Error: browserType.launch: Executable doesn't exist at ~/.cache/ms-playwright/...` and `Looks like Playwright was just installed or updated` | `executablePath` is missing from `launchOptions`, so Playwright looks for its own downloaded browser | set `executablePath` as in step 5 |
+| DEPRECATED: `test.browser.api` was deprecated in Vitest 5. Use `test.api` instead. | the port is set where Vitest 4 had it | move `api` from `test.browser` to `test` of the browser project |
+| A test that moves list items passes in happy-dom and fails in Chrome (or the reverse) | happy-dom has no `moveBefore` | assert moves in a `*.browser.test.ts` (limitation 1) |
+
+## See also
+
+- Rendering is synchronous, `set` and `batch`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-and-view-state-optional
+- Props as properties and attributes, `emit`, events that do not bubble: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-flow-props-down-events-up
+- Light DOM and Shadow DOM slots, `assignedNodes`, `slotchange`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#light-default-and-shadow
+- Stores and `bind`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#state-store-when-not-using-state
+- Lists, and what moving an item does with and without `moveBefore`: https://github.com/Pixmi/nativele/blob/main/docs/lists.md#moving-items-connecting-and-subscriptions
+- The Vite plugin, `ts-dom check`, and lint in test folders: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md
+- Setting up the Vite app first: `npx ts-dom skills nativele-vite`

package/skills/nativele-vite/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: nativele-vite
+description: "Add Nativele to an existing Vite app without a UI framework, and set up the tsDom() Vite plugin correctly: dirs and Vite's root, multi-page apps, the build script, and what vite dev does when a template or component changes. Use when a project depends on vite (or vite-plus) and @nativele/ts-dom."
+metadata:
+  tier: official
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vite@8.3.6 typescript@7.0.2 create-vite@9.3.4 vite-plus@1.5.0"
+  author: "Nativele maintainers"
+  detects: "vite vite-plus"
+---
+
+# Nativele + Vite
+
+## When to use
+
+- A Vite app with no UI framework (for example one started with `npm create vite@latest -- --template vanilla-ts`) that adds components written with Nativele (`@nativele/ts-dom`).
+- Any Vite project with Nativele whose set-up goes beyond the defaults: `root` in a sub-folder, several HTML pages, Vite+, or questions about what `vite dev` does when a template changes.
+- Signals: `vite` or `vite-plus` and `@nativele/ts-dom` in `package.json`, a `vite.config.ts`.
+- With React, follow `nativele-react`; with another framework, `nativele-integration`. The parts about `dirs`, `root` and the build script apply there too, but the hot-update behavior below was verified without a framework.
+- Not for writing the components themselves (`npx ts-dom skills add nativele-core`), and not for setting Vite up.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| vite | 8.3.6 |
+| typescript | 7.0.2 |
+| create-vite (`vanilla-ts` template, the starting point) | 9.3.4 |
+| vite-plus | 1.5.0 (checked by hand with `vp dev`, `vp build` and `vp lint`; the example project does not run it) |
+
+Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-vite/example`), which CI runs again when the example or the library changes and once a month. With a different major version of Vite, treat every step as unverified.
+
+## Set-up
+
+Starting from the `vanilla-ts` template, which already has `"type": "module"`, a `tsconfig.json` with `"include": ["src"]` and no `strict`, no `vite.config.ts`, and `"build": "tsc && vite build"`:
+
+1. `npm i @nativele/ts-dom`.
+2. Keep the components in their own folder, for example `src/nv/`, each as `x.html` plus `x.ts` (write them with `nativele-core`).
+3. Add `"strict": true` to `compilerOptions` in `tsconfig.json`. The template's other options (`verbatimModuleSyntax`, `erasableSyntaxOnly`, `noUnusedLocals`, `allowImportingTsExtensions`) work with the generated files as they are, and `"include": ["src"]` already covers `src/nv`.
+4. Create `vite.config.ts` (the template has none, so `ts-dom doctor` cannot report the plugin as missing yet):
+
+   ```ts
+   import { defineConfig } from "vite";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] })] });
+   ```
+
+   `dirs` is resolved against Vite's `root`, not against the folder you run commands in (see step 8). The other options are in the setup guide.
+
+5. Replace `tsc` in the build script with `ts-dom check`, given the same folder:
+
+   ```sh
+   npm pkg set scripts.build="ts-dom check src/nv && vite build"
+   ```
+
+   The generated files are not committed, so on a clean checkout `tsc` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'` and follow-on errors. `ts-dom check` writes them, then runs `tsc` and the lint rules. `vite build` writes them too, but it never type-checks.
+
+6. Add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`.
+7. Import each page's components from that page's entry module, and write the tags straight into the page's HTML (`<hello-card name="home"></hello-card>`; attributes reach string props). Import the component modules the way the project imports its own (`./nv/hello-card.ts` in this template), and templates always as `./x.html.js`.
+8. When `root` is a sub-folder (a multi-page app or a monorepo app kept in `web/`), each path is relative to a different folder:
+
+   | Setting | Relative to | With `root: "web"` |
+   |---|---|---|
+   | `tsDom({ dirs })` | Vite's `root` | `["src/nv"]` |
+   | `ts-dom check`, `doctor`, `gen`, `lint` arguments | the folder they run in (the one with `package.json` and `tsconfig.json`) | `web/src/nv` |
+   | `include` in `tsconfig.json` | the tsconfig's folder | `["web/src"]` |
+   | `build.rolldownOptions.input` | write absolute paths (see Troubleshooting) | `resolve(import.meta.dirname, "web/about.html")` |
+
+   Nativele needs nothing per page: each page's entry imports the components that page uses.
+
+9. With Vite+ instead of Vite, import `defineConfig` from `"vite-plus"`; the plugin, `dirs` and the build script are the same, and the lint settings in the setup guide work with `vp lint`. If `vp build` then stops with `Cannot find package 'vite'`, see Troubleshooting.
+
+## Example
+
+A two-page app with `root: "web"`, as in the example project:
+
+```
+package.json  tsconfig.json  vite.config.ts
+web/index.html  web/about.html
+web/src/main.ts  web/src/about.ts
+web/src/nv/hello-card.html  web/src/nv/hello-card.ts  web/src/nv/about-card.html  web/src/nv/about-card.ts
+```
+
+```jsonc
+// package.json (scripts)
+"dev": "vite",
+"build": "ts-dom check web/src/nv && vite build"
+```
+
+```jsonc
+// tsconfig.json: the template's, with "strict": true and
+"include": ["web/src"]
+```
+
+```ts
+// vite.config.ts
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+import { tsDom } from "@nativele/ts-dom/vite";
+
+const page = (file: string) => resolve(import.meta.dirname, "web", file);
+
+export default defineConfig({
+  root: "web",
+  plugins: [tsDom({ dirs: ["src/nv"] })],
+  build: {
+    outDir: "../dist",
+    emptyOutDir: true,
+    rolldownOptions: { input: { main: page("index.html"), about: page("about.html") } },
+  },
+});
+```
+
+```html
+<!-- web/index.html (body); web/about.html has <about-card></about-card> and /src/about.ts -->
+<hello-card name="home"></hello-card>
+<script type="module" src="/src/main.ts"></script>
+```
+
+```ts
+// web/src/main.ts
+import "./nv/hello-card.ts";
+```
+
+```html
+<!-- web/src/nv/hello-card.html -->
+<p>Hello, {{ name }}</p>
+<button type="button" data-on-click="bump">clicked {{ count }}</button>
+```
+
+```ts
+// web/src/nv/hello-card.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./hello-card.html.js";
+
+export class HelloCard extends Component(tpl, { props: { name: "" }, state: { count: 0 } }) {
+  bump(): void {
+    this.set({ count: this.state.count + 1 });
+  }
+}
+define("hello-card", HelloCard);
+```
+
+## Known limitations
+
+1. **Every change reloads the page; component state is lost.** A custom element tag can be defined only once, so there is no hot swap of a component. During `vite dev`:
+
+   | Change | What happens |
+   |---|---|
+   | A template is edited | its `x.html.ts` is regenerated and the browser reloads; the terminal prints `[vite] (client) page reload src/nv/x.html` |
+   | A template is saved with no change | no reload (the terminal still prints the `page reload` line) |
+   | A template no page has loaded since the dev server started is edited | no reload |
+   | A template some page has loaded is edited | every open page reloads, also pages that do not use it |
+   | A template that `ts-dom gen` rejects is saved | no reload: the page keeps the last good version, and the error (`file:line:col error [rule-id] ... Fix: ...`) is printed only in the terminal, with no overlay in the browser |
+   | A template uses a name the component does not have (`{{ nope }}`) | it is regenerated and reloads, the hole stays empty, and nothing reports it: only `ts-dom check` does |
+   | A component `.ts` is edited | Vite reloads the page, and the new class runs |
+
+2. **Do not call `import.meta.hot.accept()` in a module that imports components.** Vite then re-runs the modules instead of reloading, `define()` finds the tag already defined and keeps the old class, and the edit silently has no effect until a manual reload.
+3. **Neither `vite dev` nor `vite build` type-checks.** Run `ts-dom check` (the build script in step 5 does), and run it after a template change that `vite dev` accepted without complaint.
+4. **A wrong `dirs` fails without a warning from the plugin.** If `dirs` does not point at the templates from Vite's `root` (for example `["web/src/nv"]` with `root: "web"`), nothing is generated, and the first sign is an unresolved `./x.html.js` (see Troubleshooting).
+5. **Pass one folder to every `ts-dom` command.** `ts-dom-tags.ts` is written into the folder a command is given, so `ts-dom check web` next to `ts-dom check web/src/nv` leaves a second `ts-dom-tags.ts` in `web/`; delete it and use the same folder everywhere.
+6. Not verified: hot updates under a framework plugin (React Fast Refresh, Vue), server-side rendering, Vite library mode, an npm workspaces monorepo where the app has its own `package.json` (only `root` in a sub-folder of one package was verified), and Vite versions other than 8.3.
+
+## Verify
+
+Run in the project (with `root: "web"`, the folder is `web/src/nv`):
+
+```sh
+npm run build                 # expect: ts-dom check: no issues, then ✓ built, and one HTML file per page in the output
+npx ts-dom doctor src/nv      # expect: ts-dom doctor: the set-up looks right
+```
+
+Then run `npm run dev`, open every page and check that its components render and respond. Edit a template and check that the page reloads once and shows the change. The example project's [`verify.mjs`](https://github.com/Pixmi/nativele/blob/main/skills/nativele-vite/example/verify.mjs) checks with Playwright that `vite build` alone writes the generated files, that both built pages work under `vite preview`, and every row of the table in Known limitations, restoring the files it edits.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `TS2307: Cannot find module './x.html.js'` from `npm run build` on a clean checkout | the build script starts with `tsc`, before anything generated the files | `"build": "ts-dom check <folder> && vite build"` |
+| `vite build`: `[UNRESOLVED_IMPORT] Could not resolve './x.html.js'`; `vite dev`: `Failed to resolve import "./x.html.js"` and a 500 for the module | `dirs` is not relative to Vite's `root`, or leaves out the folder | give `dirs` relative to `root` (`["src/nv"]` with `root: "web"`) |
+| `ts-dom check`: `[dir-not-found] The folder src does not exist` | the commands default to `src` in the folder they run in | pass the folder from there: `ts-dom check web/src/nv` |
+| `ts-dom doctor`: `[tsconfig-misses-templates]`; `ts-dom check`: `TS18003: No inputs were found` | `include` is relative to the tsconfig, not to Vite's `root` | `"include": ["web/src"]` |
+| An edit to a component has no effect until the page is reloaded by hand | a module calls `import.meta.hot.accept()` | remove it |
+| A template edit never reaches the page, and the terminal shows `error [rule-id]` | the template breaks a template rule | fix it by the `Fix:` hint; once the template generates again, the page shows it |
+| `vite dev`: `(!) Failed to run dependency scan ... failed to resolve rolldownOptions.input value: "web/index.html"` | `vite dev` resolves a relative `input` against `root` | write absolute paths, as in the example |
+| Vite warns `ESM syntax in a file loaded as CommonJS (vite.config.ts:1:1)` | `package.json` has no `"type": "module"` | `npm pkg set type=module` |
+| `vp build`: `Cannot find package 'vite' imported from .../vitest/dist/config.js` | npm left `vite` nested under `vite-plus` on the first install (seen with npm 11.19, also without Nativele) | run `npm i` once more |
+
+## See also
+
+- The Vite plugin, its options and the dev server: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#with-vite-optional
+- Lint settings for `vite.config.ts` (Vite+): https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#lint-optional
+- What `ts-dom check`, `doctor` and `gen` check and write: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#checks
+- Writing the components: `npx ts-dom skills nativele-core`