@@ -252,8 +252,13 @@ Vite's `server.fs.allow` is extended to cover each installed module's
 package root, so pages shipped inside a wheel work for the dev server and
 production build alike.
 
-For production builds, ship a pre-bundled `my_module/static/dist/` inside
-the wheel and expose it via `ModuleBase.static_mounts()`:
+**Inertia pages never need pre-bundling.** The consuming host's Vite build
+compiles `pages/*.tsx` straight out of the installed wheel (via the
+`#module/<pkg>` aliases + `server.fs.allow`). `static/dist/` +
+`static_mounts()` exist only for assets *outside* that pipeline — vendor JS,
+standalone widgets, images. Build them with `smpy module build` (see
+[Developing out-of-tree](#developing-out-of-tree)) and expose them via
+`ModuleBase.static_mounts()`:
 
 ```python
 from importlib.resources import files
@@ -339,9 +344,62 @@ final word from its own `@theme` block below the generated import.
 **No packaging change is required.** The module wheel template already
 declares `[tool.hatch.build.targets.wheel] packages = ["my_module"]`, and
 Hatch includes every file under the package directory — `.css` along with
-`.tsx`. The `force-include` block is only needed for artifacts that live
-*outside* the package dir (`package.json`) or that are gitignored
-(`static/dist`).
+`.tsx`. Only two extras need declaring: `package.json` lives *outside* the
+package dir (a `force-include` maps it in), and `static/dist` is gitignored
+(an `artifacts` entry ships it when present without failing the build when
+it isn't).
+
+## Developing out-of-tree
+
+A module in its own repo has no host around it — these are the three
+commands that close the gap. All of them run from the module repo root.
+
+### Type-checking
+
+`smpy create-module` scaffolds a `package.json` whose devDependencies pin
+`@simple-module-py/ui`, `@simple-module-py/tsconfig` and
+`@simple-module-py/i18n` to the framework version that created the module
+(all three are published to npm in lockstep with the PyPI packages), and a
+`tsconfig.json` that resolves `@simple-module-py/ui/*` from your own
+`node_modules`. So:
+
+```bash
+npm install          # once; commit package-lock.json and use `npm ci` in CI
+npm run typecheck    # tsc --noEmit over your pages
+```
+
+### `smpy module verify` — does my frontend actually build?
+
+`tsc` alone cannot tell you whether your pages and `theme.css`/`styles.css`
+survive a real host build (Vite import resolution, Tailwind scanning, the
+`#module/<pkg>` alias plumbing). `verify` answers that by scaffolding a
+throwaway host into `.smpy/verify-host/` (cached, gitignored), installing
+your module into it as an editable path dependency, and running the host's
+real `gen-pages` + `npm run build`:
+
+```bash
+uv run smpy module verify          # warm re-runs reuse the cached host
+uv run smpy module verify --fresh  # nuke and rebuild the cached host
+```
+
+The scaffolded CI workflow runs it on every push. The verify host pins the
+framework version you develop against, so a green verify ≈ your module
+building inside a freshly scaffolded host of that version. It needs `uv`,
+`npm`, and network access to PyPI + npm on first run.
+
+### `smpy module build` — static_mounts() assets
+
+If (and only if) your module ships assets outside the Inertia page pipeline,
+put an entry file at `<pkg>/assets_src/index.ts` and run:
+
+```bash
+uv run smpy module build
+```
+
+It bundles `assets_src/` into `<pkg>/static/dist/` (IIFE, via the verify
+host's Vite toolchain — your repo needs no bundler devDependency). The
+scaffolded `pyproject.toml` already ships `static/dist` in the wheel via a
+hatch `artifacts` entry; the command warns if that entry has been removed.
 
 ## Templates
 
 
@@ -0,0 +1,133 @@
+# Out-of-tree module JS/CSS DX — Design
+
+**Goal:** Make the frontend half of a standalone module repo (a module living
+outside this monorepo) work out of the box: correct editor/typecheck setup,
+a CI-runnable proof that the module's TSX + CSS compile against the real host
+toolchain, and a build path for `static_mounts()` assets.
+
+**Date:** 2026-08-06
+**Approach chosen:** Extend `smpy` with a `module` command group + fix the
+`create-module` scaffold templates (Approach A). Rejected: template-only
+`dev-host/` committed into each module repo (drifts from the framework);
+separate `simple_module_devkit` package (release overhead with no benefit over
+the existing CLI).
+
+---
+
+## Problem
+
+The `create-module` scaffold and docs assume the monorepo:
+
+1. `tsconfig.json.tpl` maps `@simple-module-py/ui/*` to `../../packages/ui/src/*`
+   — a path that only exists inside this repo. Standalone repos get broken
+   type-checking and editor IntelliSense out of the box.
+2. There is no way to compile the module's frontend standalone. Pages import
+   `@simple-module-py/ui/components/...` subpaths and ship `theme.css` /
+   `styles.css` that only mean anything inside a host's Vite + Tailwind build —
+   so the first signal that something is wrong arrives after publishing, inside
+   a consuming host.
+3. `docs/module-authoring.md` says "for production builds, ship a pre-bundled
+   `static/dist`" — misleading: wheel modules' TSX pages are compiled by the
+   *host's* Vite build (via `#module/<pkg>` aliases + `fs.allow`).
+   `static/dist` + `static_mounts()` is only for assets *outside* that pipeline
+   (vendor JS, widgets, images), and there is no tooling to produce one.
+4. The module scaffold has no JS typecheck/lint scripts and its CI runs Python
+   only.
+
+Both `@simple-module-py/ui` and `@simple-module-py/tsconfig` are already
+published to npm, versioned in lockstep with the framework — the raw materials
+exist; the scaffold and CLI just don't use them.
+
+## Deliverables
+
+### 1. Scaffold fixes (editor/typecheck correctness)
+
+`create-module` already distinguishes standalone vs in-repo (`include_ci`
+logic, GH #210). The JS templates become variant-aware on the same switch:
+
+- **`tsconfig.json` (standalone variant):** paths resolve via the installed
+  npm package:
+  `"@simple-module-py/ui/*": ["./node_modules/@simple-module-py/ui/src/*"]`
+  (and the same for `@simple-module-py/i18n`). The in-repo variant keeps the
+  current `../../packages/*` mapping.
+- **`package.json` (standalone variant):** peerDependencies stay as the
+  host-contract; add pinned devDependencies so `npm install` + `tsc` work in
+  the repo: `@simple-module-py/ui`, `@simple-module-py/tsconfig`,
+  `typescript`, `@types/react`, `@types/react-dom` — pinned with the existing
+  `{{FRAMEWORK_VERSION}}` mechanism where applicable. Add
+  `"scripts": {"typecheck": "tsc --noEmit"}`.
+- **`ci.yml` (standalone):** add a JS job — setup-node, `npm ci`,
+  `npm run typecheck`, then `uv run smpy module verify`.
+  `simple_module_cli` joins the scaffold's `dev` extra.
+- **`.gitignore`:** add `.smpy/`.
+
+Rejected alternative: adding an `exports` map to the published
+`@simple-module-py/ui` package would remove the need for `paths` everywhere,
+but it touches the host's Vite alias machinery and every existing consumer —
+out of scope; possible later refactor.
+
+### 2. `smpy module verify`
+
+New `smpy module` Typer group in `framework/cli`. `verify` proves the module's
+TSX + `theme.css`/`styles.css` compile against the real host toolchain:
+
+1. Scaffold (or reuse) an ephemeral host at `.smpy/verify-host/` using the
+   existing `create-host` templates, with the module wired in as an editable
+   path dependency via `[tool.uv.sources]`.
+2. Run, in the host: `uv sync` → `npm install` (in `client_app/`) →
+   `smpy host gen-pages` → `npm run build` (`tsc && vite build`).
+3. Propagate the exit code — CI-friendly. Print the failing step's output.
+
+Details:
+
+- **Caching:** `.smpy/verify-host/` persists between runs (gitignored), so
+  warm re-runs skip scaffolding and get fast idempotent `npm install`.
+  `--fresh` deletes and rebuilds it.
+- **Version:** the ephemeral host is pinned to the CLI's installed framework
+  version via the existing `resolve_framework_version()` — verify passing ≈
+  the module working in a freshly scaffolded host of that version.
+- **No DB / no boot:** `gen-pages` only does discovery + file emission, so
+  verify needs no database, no `.env`, no running server, and no auth module.
+- **Preconditions:** run from the module repo root; error clearly if no
+  `[project.entry-points.simple_module]` is found in `pyproject.toml`.
+
+### 3. `smpy module build`
+
+For `static_mounts()` assets only (vendor JS, widgets — outside the Inertia
+page pipeline):
+
+- **Convention:** sources in `<pkg>/assets_src/`, output to
+  `<pkg>/static/dist/`.
+- Reuses the verify-host's node toolchain (same bootstrap path as `verify`),
+  generating a Vite **lib-mode** config on the fly — no Vite devDependency in
+  the module repo.
+- Warns if the module's `pyproject.toml` lacks the hatch `force-include` for
+  `static/dist` (it is gitignored, so wheels would silently omit it).
+- Errors clearly if `assets_src/` does not exist (the command is opt-in; most
+  modules never need it).
+
+## Testing
+
+- Unit tests for the orchestration in `framework/cli/tests`, with subprocess
+  boundaries (uv/npm invocations) mocked: scaffold reuse vs `--fresh`,
+  editable-source wiring, precondition errors, exit-code propagation,
+  force-include warning.
+- One real end-to-end test (scaffold a module → `verify` green) behind the
+  existing `e2e` marker, since it needs npm and network access.
+- Template-variant tests: standalone vs in-repo emit the right
+  `tsconfig.json` / `package.json` / `ci.yml`.
+
+## Docs
+
+- New "Developing out-of-tree" section in `docs/module-authoring.md`: the
+  tsconfig/npm story, `verify` in CI, `build` for static assets.
+- Fix the misleading "ship a pre-bundled `static/dist`" wording in the
+  Frontend assets section: pages are built by the consuming host;
+  `static/dist` is only for extra-pipeline assets.
+
+## Out of scope (this round)
+
+- A live preview/dev-server loop for out-of-tree modules (`smpy module dev`) —
+  the largest remaining gap, deliberately deferred.
+- `exports` map on the published npm packages.
+- Any change to how in-repo (`modules/*`) development works.
@@ -0,0 +1,92 @@
+"""``smpy module build`` — bundle ``<pkg>/assets_src/`` into ``<pkg>/static/dist/``.
+
+Only for assets served via :meth:`ModuleBase.static_mounts` (vendor JS,
+widgets, images). Inertia pages do NOT need this — the consuming host's Vite
+build compiles ``pages/*.tsx`` straight from the wheel.
+
+The module repo carries no bundler of its own: we borrow the verify host's
+node toolchain (``.smpy/verify-host/client_app``) and point Vite at a
+generated lib-mode config.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+import typer
+
+from simple_module_cli._module_host import ModuleInfo, ensure_verify_host, require_binary
+from simple_module_cli.case import to_pascal_case
+
+_ENTRY_CANDIDATES = ("index.ts", "index.tsx", "index.js")
+
+
+def run_build(info: ModuleInfo, *, fresh: bool = False, runner=subprocess.run) -> None:
+    assets_src = info.root / info.package_name / "assets_src"
+    entry = next((assets_src / n for n in _ENTRY_CANDIDATES if (assets_src / n).is_file()), None)
+    if entry is None:
+        typer.echo(
+            f"error: no {info.package_name}/assets_src/index.(ts|tsx|js) found. "
+            "`smpy module build` bundles static_mounts() assets only — Inertia pages "
+            "are built by the consuming host and need no bundling.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    host = ensure_verify_host(info, fresh=fresh)
+    client_app = host / "client_app"
+    npm = require_binary("npm")
+    if not (client_app / "node_modules").is_dir():
+        typer.echo("[build] npm install (first run)")
+        if runner([npm, "install"], cwd=client_app).returncode != 0:
+            typer.echo("[build] FAILED at: npm install", err=True)
+            raise typer.Exit(code=1)
+
+    out_dir = info.root / info.package_name / "static" / "dist"
+    config_path = info.root / ".smpy" / "module-build.config.mjs"
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    config_path.write_text(
+        _vite_lib_config(entry, out_dir, global_name=to_pascal_case(info.package_name)),
+        encoding="utf-8",
+    )
+    typer.echo(f"[build] vite build -> {info.package_name}/static/dist")
+    npx = require_binary("npx")
+    if runner([npx, "vite", "build", "--config", str(config_path)], cwd=client_app).returncode != 0:
+        typer.echo("[build] FAILED at: vite build", err=True)
+        raise typer.Exit(code=1)
+
+    _warn_missing_force_include(info)
+    typer.echo("[build] OK")
+
+
+def _vite_lib_config(entry: Path, out_dir: Path, *, global_name: str) -> str:
+    return f"""\
+import {{ defineConfig }} from 'vite'
+
+export default defineConfig({{
+  build: {{
+    lib: {{
+      entry: {entry.as_posix()!r},
+      formats: ['iife'],
+      name: {global_name!r},
+      fileName: () => 'index.js',
+    }},
+    outDir: {out_dir.as_posix()!r},
+    emptyOutDir: true,
+  }},
+}})
+"""
+
+
+def _warn_missing_force_include(info: ModuleInfo) -> None:
+    """static/dist is gitignored — without an artifacts entry the wheel silently omits it."""
+    pyproject = (info.root / "pyproject.toml").read_text(encoding="utf-8")
+    if f"{info.package_name}/static/dist" not in pyproject:
+        typer.echo(
+            "warning: pyproject.toml does not ship "
+            f'"{info.package_name}/static/dist" — the built bundle will NOT be in the wheel. '
+            "Add under [tool.hatch.build.targets.wheel]:\n"
+            f'  artifacts = ["{info.package_name}/static/dist/"]',
+            err=True,
+        )
@@ -0,0 +1,85 @@
+"""Shared plumbing for ``smpy module`` commands.
+
+Out-of-tree module repos have no frontend toolchain of their own — the
+commands borrow one by scaffolding a throwaway host (via the same templates
+as ``smpy create-host``) into ``.smpy/verify-host/`` and caching it there.
+"""
+
+from __future__ import annotations
+
+import shutil
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+import typer
+
+from simple_module_cli.scaffolding import create_host, resolve_framework_version
+
+VERIFY_HOST_RELPATH = Path(".smpy") / "verify-host"
+
+
+@dataclass(frozen=True)
+class ModuleInfo:
+    """Identity of the module under the cwd, read from its pyproject."""
+
+    root: Path
+    pypi_name: str  # [project].name, e.g. simple_module_my_feature
+    package_name: str  # the simple_module entry-point key, e.g. my_feature
+
+
+def read_module_info(root: Path) -> ModuleInfo:
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        typer.echo(f"error: no pyproject.toml in {root} — run from the module repo root.", err=True)
+        raise typer.Exit(code=1)
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    entry_points = data.get("project", {}).get("entry-points", {}).get("simple_module", {})
+    if not entry_points:
+        typer.echo(
+            "error: pyproject.toml declares no [project.entry-points.simple_module] — "
+            "this does not look like a SimpleModule module.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+    return ModuleInfo(
+        root=root,
+        pypi_name=data["project"]["name"],
+        package_name=next(iter(entry_points)),
+    )
+
+
+def require_binary(name: str) -> str:
+    """Resolve ``name`` on PATH or exit with a clear message (npm on Windows is npm.cmd)."""
+    path = shutil.which(name)
+    if path is None:
+        typer.echo(f"error: '{name}' not found on PATH — install it and retry.", err=True)
+        raise typer.Exit(code=1)
+    return path
+
+
+def ensure_verify_host(info: ModuleInfo, *, fresh: bool = False) -> Path:
+    """Scaffold (or reuse) the cached verify host; return its directory."""
+    host_dir = info.root / VERIFY_HOST_RELPATH
+    if fresh and host_dir.exists():
+        shutil.rmtree(host_dir)
+    if not (host_dir / "pyproject.toml").is_file():
+        create_host(
+            host_dir,
+            name="verify_host",
+            modules=[],
+            framework_version=resolve_framework_version(),
+        )
+        _wire_module_dep(host_dir / "pyproject.toml", info.pypi_name)
+    return host_dir
+
+
+def _wire_module_dep(pyproject_path: Path, pypi_name: str) -> None:
+    """Add the module as an editable path dependency of the verify host."""
+    text = pyproject_path.read_text(encoding="utf-8")
+    # Unpinned on purpose: [tool.uv.sources] overrides it with the local path.
+    # Note: pin_framework_deps may have rewritten the array onto one line, so
+    # match the opening bracket only — TOML tolerates the injected newline.
+    text = text.replace("dependencies = [", f'dependencies = [\n    "{pypi_name}",', 1)
+    text += f'\n[tool.uv.sources]\n{pypi_name} = {{ path = "../..", editable = true }}\n'
+    pyproject_path.write_text(text, encoding="utf-8")