TanStack · chughgaurav · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/.changeset/lemon-memes-divide.md b/.changeset/lemon-memes-divide.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/lit-query': minor
+---
+
+Add initial @tanstack/lit-query package
diff --git a/.gitignore b/.gitignore
@@ -10,6 +10,7 @@ yarn.lock
 build
 coverage
 dist
+dist-cjs
 dist-ts
 
 # misc

diff --git a/examples/lit/basic/README.md b/examples/lit/basic/README.md
@@ -0,0 +1,5 @@
+# Example
+
+To run this example from the repo root:
+
+- `pnpm --dir examples/lit/basic run dev`
diff --git a/examples/lit/basic/basic-query.html b/examples/lit/basic/basic-query.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Lit Query Basic Example</title>
+  </head>
+  <body>
+    <basic-query-root></basic-query-root>
+    <script type="module" src="/src/basic-query.ts"></script>
+  </body>
+</html>
diff --git a/examples/lit/basic/config/port.d.ts b/examples/lit/basic/config/port.d.ts
@@ -0,0 +1 @@
+export const DEMO_PORT: number
diff --git a/examples/lit/basic/config/port.js b/examples/lit/basic/config/port.js
@@ -0,0 +1,22 @@
+const DEFAULT_DEMO_PORT = 4173
+const envPort = process.env.DEMO_PORT
+
+function resolvePort() {
+  if (!envPort) {
+    return DEFAULT_DEMO_PORT
+  }
+
+  const parsedPort = Number.parseInt(envPort, 10)
+  const isValidPort =
+    Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
+
-  const parsedPort = Number.parseInt(envPort, 10)
-  const isValidPort =
-    Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
+  const isDigitsOnly = /^\d+$/.test(envPort)
+  const parsedPort = Number(envPort)
+  const isValidPort =
+    isDigitsOnly && Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
-  const parsedPort = Number.parseInt(envPort, 10)
-  const isValidPort =
-    Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
+  const isDigitsOnly = /^\d+$/.test(envPort)
+  const parsedPort = Number(envPort)
+  const isValidPort =
+    isDigitsOnly && Number.isInteger(parsedPort) && parsedPort > 0 && parsedPort <= 65535
+  if (!isValidPort) {
+    throw new Error(
+      `Invalid DEMO_PORT "${envPort}". Expected an integer between 1 and 65535.`,
+    )
+  }
+
+  return parsedPort
+}
+
+export const DEMO_PORT = resolvePort()
diff --git a/examples/lit/basic/index.html b/examples/lit/basic/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>TanStack Lit Query E2E Demo</title>
+  </head>
+  <body>
+    <demo-root></demo-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
diff --git a/examples/lit/basic/lifecycle-contract.html b/examples/lit/basic/lifecycle-contract.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>TanStack Lit Query Lifecycle Contract Fixture</title>
+  </head>
+  <body>
+    <lifecycle-contract-root></lifecycle-contract-root>
+    <script type="module" src="/src/lifecycle-contract.ts"></script>
+  </body>
+</html>
diff --git a/examples/lit/basic/mutation.html b/examples/lit/basic/mutation.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Lit Query Mutation Example</title>
+  </head>
+  <body>
+    <mutation-example-root></mutation-example-root>
+    <script type="module" src="/src/mutation.ts"></script>
+  </body>
+</html>
diff --git a/examples/lit/basic/package.json b/examples/lit/basic/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "@tanstack/query-example-lit-basic",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@tanstack/lit-query": "^0.1.0",
+    "@tanstack/query-core": "^5.99.0",
+    "lit": "^3.3.1"
+  },
+  "devDependencies": {
+    "typescript": "5.8.3",
+    "vite": "^6.4.1"
+  }
+}
diff --git a/examples/lit/basic/src/basic-query.ts b/examples/lit/basic/src/basic-query.ts
@@ -0,0 +1,90 @@
+import { html, LitElement } from 'lit'
+import { QueryClient } from '@tanstack/query-core'
+import { QueryClientProvider, createQueryController } from '@tanstack/lit-query'
+import {
+  fetchTodosFromServer,
+  resetTodoApi,
+  type TodosResponse,
+} from './todoApi'
+
+resetTodoApi()
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: { retry: false },
+  },
+})
+
+class BasicQueryProvider extends QueryClientProvider {
+  constructor() {
+    super()
+    this.client = queryClient
+  }
+
+  protected override createRenderRoot(): HTMLElement | DocumentFragment {
+    return this
+  }
+}
+
+customElements.define('basic-query-provider', BasicQueryProvider)
+
+class BasicQueryExample extends LitElement {
+  private readonly todos = createQueryController<TodosResponse, Error>(this, {
+    queryKey: ['todos'],
+    queryFn: fetchTodosFromServer,
+  })
+
+  protected override createRenderRoot(): HTMLElement | DocumentFragment {
+    return this
+  }
+
+  render() {
+    const query = this.todos()
+    return html`
+      <main>
+        <h1>Basic Query Example</h1>
+        <p data-testid="basic-query-status">
+          Status: <strong>${query.status}</strong>
+        </p>
+        <button
+          data-testid="basic-refetch"
+          @click=${() => this.todos.refetch()}
+        >
+          Refetch
+        </button>
+
+        ${query.isPending
+          ? html`<p data-testid="basic-loading">Loading...</p>`
+          : null}
+        ${query.isError
+          ? html`<p data-testid="basic-error">Error: ${String(query.error)}</p>`
+          : null}
+
+        <ul data-testid="basic-todo-list">
+          ${(query.data?.items ?? []).map(
+            (todo) =>
+              html`<li data-testid="basic-todo-item">${todo.title}</li>`,
+          )}
+        </ul>
+      </main>
+    `
+  }
+}
+
+customElements.define('basic-query-example', BasicQueryExample)
+
+class BasicQueryRoot extends LitElement {
+  protected override createRenderRoot(): HTMLElement | DocumentFragment {
+    return this
+  }
+
+  render() {
+    return html`
+      <basic-query-provider>
+        <basic-query-example></basic-query-example>
+      </basic-query-provider>
+    `
+  }
+}
+
+customElements.define('basic-query-root', BasicQueryRoot)
-Original file line number
+Diff line change
@@ Expand Up / @@ -10,6 +10,7 @@ yarn.lock @@
     build
     coverage
     dist
+    dist-cjs
     dist-ts
     # misc
@@ Expand Down @@