From c136d829c4c996637e6b517c01d1487ac735b596 Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Mon, 5 Oct 2026 16:33:35 +0400
Subject: [PATCH 1/5] Leave non-JavaScript Vue script blocks out of script
 modules

Volt.Plugin.Vue returned every <script> block as a script module and
named any lang it did not know .js. A block in another language, such as
PhoenixVapor's <script lang="elixir">, became a virtual .js module, so
mix volt.js.check linted and type-checked Elixir as JavaScript.

Only blocks without a lang, or with js, jsx, ts or tsx, are script
modules now, and jsx blocks are named .jsx.

Fixes #57
---
 CHANGELOG.md                  |  6 ++++++
 lib/volt/plugin/vue.ex        | 13 ++++++++----
 test/volt/plugin/vue_test.exs | 40 +++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c849de3..1700635 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Fixed
+
+- Leave Vue `<script>` blocks in other languages, such as `<script lang="elixir">`, out of the script modules that `mix volt.js.check` lints and type-checks. Every block was treated as JavaScript, so such a block was reported as TypeScript syntax errors. `lang="jsx"` blocks are now checked as JSX ([#57](https://github.com/elixir-volt/volt/issues/57)).
+
 ## 0.20.0 - 2026-10-03
 
 ### Breaking changes
diff --git a/lib/volt/plugin/vue.ex b/lib/volt/plugin/vue.ex
index 999bc10..5a55f20 100644
--- a/lib/volt/plugin/vue.ex
+++ b/lib/volt/plugin/vue.ex
@@ -165,9 +165,12 @@ defmodule Volt.Plugin.Vue do
   defp scripts(source) do
     case Vize.parse_sfc(source) do
       {:ok, descriptor} ->
-        [descriptor.script, descriptor.script_setup]
-        |> Enum.reject(&is_nil/1)
-        |> Enum.map(fn block -> {script_extension(block[:lang]), block.content} end)
+        # A block in another language, such as `<script lang="elixir">`, belongs
+        # to other tooling and is not a JavaScript module.
+        for block <- [descriptor.script, descriptor.script_setup],
+            block != nil,
+            extension = script_extension(block[:lang]),
+            do: {extension, block.content}
 
       {:error, _} ->
         []
@@ -198,9 +201,11 @@ defmodule Volt.Plugin.Vue do
     end
   end
 
+  defp script_extension(lang) when lang in [nil, "js"], do: ".js"
+  defp script_extension("jsx"), do: ".jsx"
   defp script_extension("ts"), do: ".ts"
   defp script_extension("tsx"), do: ".tsx"
-  defp script_extension(_lang), do: ".js"
+  defp script_extension(_lang), do: nil
 
   defp style_extension(lang) when lang in [nil, "css"], do: ".css"
   defp style_extension(lang), do: ".#{lang}"
diff --git a/test/volt/plugin/vue_test.exs b/test/volt/plugin/vue_test.exs
index 1577d9c..a1d5328 100644
--- a/test/volt/plugin/vue_test.exs
+++ b/test/volt/plugin/vue_test.exs
@@ -12,6 +12,46 @@ defmodule Volt.Plugin.VueTest do
     assert result.code =~ "export default { render }"
   end
 
+  describe "embedded_modules/3" do
+    defp script_modules(source) do
+      "Example.vue"
+      |> Volt.Plugin.Vue.embedded_modules(source, [])
+      |> Volt.Plugin.EmbeddedModule.normalize_all()
+      |> Enum.filter(&(&1.type == :script))
+      |> Enum.map(&{&1.extension, String.trim(&1.source)})
+    end
+
+    test "leaves out script blocks that are not JavaScript" do
+      source = """
+      <script setup lang="ts">
+      const n: number = 1
+      </script>
+
+      <script lang="elixir">
+      def total(%{items: items}), do: length(items)
+      </script>
+
+      <template><p>{{ n }}</p></template>
+      """
+
+      assert script_modules(source) == [{".ts", "const n: number = 1"}]
+    end
+
+    test "names script blocks by their JavaScript dialect" do
+      for {lang, extension} <- [
+            {"", ".js"},
+            {~s( lang="js"), ".js"},
+            {~s( lang="jsx"), ".jsx"},
+            {~s( lang="ts"), ".ts"},
+            {~s( lang="tsx"), ".tsx"}
+          ] do
+        source = "<script#{lang}>export default {}</script><template><p /></template>"
+
+        assert script_modules(source) == [{extension, "export default {}"}]
+      end
+    end
+  end
+
   test "script-bearing scoped components receive their CSS scope on the default export" do
     for script <- [
           "<script setup>defineProps(['label'])</script>",

From 28cbed24324734f33a913923eb3c88c7fd1d0156 Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Mon, 5 Oct 2026 16:33:35 +0400
Subject: [PATCH 2/5] Serve OXC runtime helpers from the dev server

With a :target below ES2022, OXC lowers a class field into an import of
a helper from @oxc-project/runtime. The dev server rewrote that import
to /@vendor/, which resolved the package from node_modules and answered
404 when it was not installed. The importing module then failed to load,
and every module importing it, with nothing in the page or the log.

The production build already leaves these imports to OXC.bundle/2,
which provides the helpers itself. Vendor bundling now does the same
through an entry that only names the helper. The check for such
specifiers moves to Volt.JS.Specifier, shared by both.

Fixes #58
---
 CHANGELOG.md                                  |  1 +
 lib/volt/builder/resolver.ex                  |  7 +----
 lib/volt/js/specifier.ex                      | 13 ++++++++
 lib/volt/js/vendor.ex                         | 13 +++++++-
 .../volt/dev_server/import_rewriting_test.exs | 30 +++++++++++++++++++
 5 files changed, 57 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1700635..0781eb2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
 ### Fixed
 
 - Leave Vue `<script>` blocks in other languages, such as `<script lang="elixir">`, out of the script modules that `mix volt.js.check` lints and type-checks. Every block was treated as JavaScript, so such a block was reported as TypeScript syntax errors. `lang="jsx"` blocks are now checked as JSX ([#57](https://github.com/elixir-volt/volt/issues/57)).
+- Serve the `@oxc-project/runtime` helpers that the dev server's own output imports. With a `:target` below ES2022, a class with fields compiles to an import of such a helper, which `/@vendor/` answered with 404 unless the npm package was installed, so the importing module and everything importing it failed to load with no error shown. The helpers now come from the bundler, as in production builds ([#58](https://github.com/elixir-volt/volt/issues/58)).
 
 ## 0.20.0 - 2026-10-03
 
diff --git a/lib/volt/builder/resolver.ex b/lib/volt/builder/resolver.ex
index 52325c6..2afe1c2 100644
--- a/lib/volt/builder/resolver.ex
+++ b/lib/volt/builder/resolver.ex
@@ -51,7 +51,7 @@ defmodule Volt.Builder.Resolver do
 
       # OXC's transform imports helpers from `@oxc-project/runtime`, and `OXC.bundle/2`
       # provides them itself, so they never come from `node_modules`.
-      oxc_runtime_helper?(specifier) ->
+      Volt.JS.Specifier.oxc_runtime_helper?(specifier) ->
         :skip
 
       absolute?(specifier) ->
@@ -68,11 +68,6 @@ defmodule Volt.Builder.Resolver do
     end
   end
 
-  defp oxc_runtime_helper?(specifier),
-    do:
-      specifier == "@oxc-project/runtime" or
-        String.starts_with?(specifier, "@oxc-project/runtime/")
-
   defp resolve_absolute(specifier) do
     if File.exists?(specifier) do
       {:ok, specifier}
diff --git a/lib/volt/js/specifier.ex b/lib/volt/js/specifier.ex
index 032d2b4..f418d80 100644
--- a/lib/volt/js/specifier.ex
+++ b/lib/volt/js/specifier.ex
@@ -16,6 +16,19 @@ defmodule Volt.JS.Specifier do
 
   def split_query(specifier), do: Volt.URL.split_query(specifier)
 
+  @oxc_runtime "@oxc-project/runtime"
+
+  @doc """
+  Return whether a specifier names a helper from `@oxc-project/runtime`.
+
+  OXC's transform imports these when it lowers syntax for a target, such as
+  class fields below ES2022. `OXC.bundle/2` provides them itself, so they are
+  never resolved from `node_modules`.
+  """
+  @spec oxc_runtime_helper?(String.t()) :: boolean()
+  def oxc_runtime_helper?(specifier),
+    do: specifier == @oxc_runtime or String.starts_with?(specifier, @oxc_runtime <> "/")
+
   defp split_on_query(specifier) do
     case String.split(specifier, "?", parts: 2) do
       [path, query] -> {path, query}
diff --git a/lib/volt/js/vendor.ex b/lib/volt/js/vendor.ex
index 388af78..d2f5327 100644
--- a/lib/volt/js/vendor.ex
+++ b/lib/volt/js/vendor.ex
@@ -381,7 +381,18 @@ defmodule Volt.JS.Vendor do
         )
 
       nil ->
-        package_prebundle_entry(specifier, module_dirs)
+        if Volt.JS.Specifier.oxc_runtime_helper?(specifier) do
+          # The bundler supplies these helpers, so the entry only has to name
+          # one; the package does not need to be installed.
+          synthetic_prebundle_entry(
+            specifier,
+            "helper.js",
+            ~s(export { default } from #{Jason.encode!(specifier)};\n),
+            context_dir(module_dirs, plugins, module_types)
+          )
+        else
+          package_prebundle_entry(specifier, module_dirs)
+        end
     end
   end
 
diff --git a/test/volt/dev_server/import_rewriting_test.exs b/test/volt/dev_server/import_rewriting_test.exs
index 7f9452e..42df997 100644
--- a/test/volt/dev_server/import_rewriting_test.exs
+++ b/test/volt/dev_server/import_rewriting_test.exs
@@ -81,6 +81,36 @@ defmodule Volt.DevServer.ImportRewritingTest do
     end
   end
 
+  describe "syntax lowered for a target" do
+    @tag :tmp_dir
+    test "serves the runtime helper a lowered class field imports", %{tmp_dir: project} do
+      # A project of its own, so the helper is not already in the vendor cache.
+      root = Path.join(project, "src")
+      File.mkdir_p!(root)
+      File.mkdir_p!(Path.join(project, "node_modules"))
+
+      File.write!(Path.join(root, "search.ts"), """
+      export class Search {
+        private readonly style = 'field'
+      }
+      """)
+
+      # Class fields are lowered below ES2022, into an import of a helper from
+      # `@oxc-project/runtime`, which is not installed in `node_modules`.
+      opts = [root: root, target: :es2020]
+      conn = call_dev_server("/assets/search.ts", opts)
+      assert conn.status == 200
+
+      assert [helper_url] =
+               Regex.run(~r{/@vendor/[^"]*defineProperty\.js\?v=[a-f0-9]+}, conn.resp_body)
+
+      helper = call_dev_server(helper_url, opts)
+      assert helper.status == 200
+      assert helper.resp_body =~ "function _defineProperty"
+      assert helper.resp_body =~ ~r/export \{[^}]*default/
+    end
+  end
+
   describe "import rewriting" do
     test "rewrites relative imports to absolute paths" do
       File.write!(Path.join(@fixture_dir, "src/utils.ts"), "export const y = 1")

From d66369e2f8fd13a147d04ae28dcbc9921b20a335 Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Mon, 5 Oct 2026 16:33:35 +0400
Subject: [PATCH 3/5] Resolve dev server paths from the directory Volt started
 in

The working directory belongs to the whole VM, and Mix changes it while
it compiles a dependency. Phoenix.CodeReloader does that for a
reloadable path dependency during a request, so a vendor request served
at the same time resolved the relative cache directory under the
dependency: the bundle was written into the dependency's _build, or the
write failed with enoent and the page's module graph did not load.

Volt now remembers the working directory when it starts, and the dev
server resolves from it: the vendor cache, the asset root, watched and
reload directories, the public directory and the Tailwind input. Build
tasks, which run with the project as the working directory, are
unchanged.

Fixes #56
---
 CHANGELOG.md                 |  1 +
 lib/volt/application.ex      |  1 +
 lib/volt/config/tailwind.ex  |  2 +-
 lib/volt/dev.ex              |  9 +++++----
 lib/volt/dev_server.ex       | 20 ++++++++++++++------
 lib/volt/js/vendor.ex        |  8 ++++----
 lib/volt/paths.ex            | 22 ++++++++++++++++++++++
 lib/volt/public_dir.ex       |  2 +-
 lib/volt/watcher.ex          | 15 ++++++++-------
 lib/volt/watcher/ignore.ex   |  2 +-
 test/volt/js/vendor_test.exs | 27 +++++++++++++++++++++++++++
 11 files changed, 85 insertions(+), 24 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0781eb2..d73840f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Leave Vue `<script>` blocks in other languages, such as `<script lang="elixir">`, out of the script modules that `mix volt.js.check` lints and type-checks. Every block was treated as JavaScript, so such a block was reported as TypeScript syntax errors. `lang="jsx"` blocks are now checked as JSX ([#57](https://github.com/elixir-volt/volt/issues/57)).
 - Serve the `@oxc-project/runtime` helpers that the dev server's own output imports. With a `:target` below ES2022, a class with fields compiles to an import of such a helper, which `/@vendor/` answered with 404 unless the npm package was installed, so the importing module and everything importing it failed to load with no error shown. The helpers now come from the bundler, as in production builds ([#58](https://github.com/elixir-volt/volt/issues/58)).
+- Resolve the dev server's paths from the directory Volt started in, not the current working directory. `Phoenix.CodeReloader` changes the VM's working directory while it compiles a reloadable path dependency, so a vendor request served at the same time wrote its cache into the dependency's `_build`, or failed with `could not write to file`. The vendor cache, asset root, watched directories and Tailwind input are affected ([#56](https://github.com/elixir-volt/volt/issues/56)).
 
 ## 0.20.0 - 2026-10-03
 
diff --git a/lib/volt/application.ex b/lib/volt/application.ex
index b1c20d9..5eae0f6 100644
--- a/lib/volt/application.ex
+++ b/lib/volt/application.ex
@@ -4,6 +4,7 @@ defmodule Volt.Application do
 
   @impl true
   def start(_type, _args) do
+    Volt.Paths.capture_root()
     Volt.Cache.create_table()
     Volt.Dev.Assets.create_table()
     Volt.HMR.ImportGraph.create_table()
diff --git a/lib/volt/config/tailwind.ex b/lib/volt/config/tailwind.ex
index d1f2ea3..2fe3d7a 100644
--- a/lib/volt/config/tailwind.ex
+++ b/lib/volt/config/tailwind.ex
@@ -29,7 +29,7 @@ defmodule Volt.Config.Tailwind do
     name = overrides[:name] || config[:name] || entry_name(css)
 
     %__MODULE__{
-      css: if(css, do: Path.expand(css)),
+      css: if(css, do: Volt.Paths.expand(css)),
       name: name,
       sources: overrides[:sources] || config[:sources] || [],
       dev_url: overrides[:dev_url] || config[:dev_url] || default_dev_url(name)
diff --git a/lib/volt/dev.ex b/lib/volt/dev.ex
index d858639..d85e177 100644
--- a/lib/volt/dev.ex
+++ b/lib/volt/dev.ex
@@ -35,7 +35,7 @@ defmodule Volt.Dev do
   @doc "Start or reuse a managed watcher, rejecting conflicting configuration."
   def start(opts) do
     session = session_identity(opts)
-    root = opts |> Keyword.fetch!(:root) |> Path.expand()
+    root = opts |> Keyword.fetch!(:root) |> Volt.Paths.expand()
     key = {:session, session}
     opts = normalize_options(Keyword.put(opts, :session, session), root)
 
@@ -78,7 +78,8 @@ defmodule Volt.Dev do
   def session_identity(opts) do
     case Keyword.get(opts, :session, :default) do
       :default ->
-        {:managed, Keyword.get(opts, :id, :default), Path.expand(Keyword.fetch!(opts, :root))}
+        {:managed, Keyword.get(opts, :id, :default),
+         Volt.Paths.expand(Keyword.fetch!(opts, :root))}
 
       session ->
         session
@@ -139,8 +140,8 @@ defmodule Volt.Dev do
     |> Keyword.delete(:id)
     |> Keyword.put(:root, root)
     |> Keyword.put_new(:session, :default)
-    |> Keyword.update(:watch_dirs, [], &Enum.map(&1, fn path -> Path.expand(path) end))
-    |> Keyword.update(:reload_dirs, [], &Enum.map(&1, fn path -> Path.expand(path) end))
+    |> Keyword.update(:watch_dirs, [], &Enum.map(&1, fn path -> Volt.Paths.expand(path) end))
+    |> Keyword.update(:reload_dirs, [], &Enum.map(&1, fn path -> Volt.Paths.expand(path) end))
   end
 
   defp verify_configuration(supervisor, pid, opts) do
diff --git a/lib/volt/dev_server.ex b/lib/volt/dev_server.ex
index d3744b4..efff655 100644
--- a/lib/volt/dev_server.ex
+++ b/lib/volt/dev_server.ex
@@ -32,7 +32,7 @@ defmodule Volt.DevServer do
   require Logger
 
   alias Plug.Conn
-  alias Volt.{Config, URL}
+  alias Volt.{Config, Paths, URL}
 
   @support_modules {:volt, "ts"}
   @runtime_rewrites %{"../hmr" => "/@volt/client.js"}
@@ -47,7 +47,7 @@ defmodule Volt.DevServer do
     server_config = Config.server(profile, build_opts)
 
     root = Keyword.get(opts, :root) || to_string(config.root)
-    expanded_root = Path.expand(root)
+    expanded_root = Paths.expand(root)
 
     node_modules = NPM.Resolution.PackageResolver.find_node_modules(expanded_root)
     plugins = config.plugins
@@ -75,7 +75,7 @@ defmodule Volt.DevServer do
       if server_config.watch and is_nil(Keyword.get(opts, :session_supervisor)) do
         watch_dirs =
           if tailwind_root && server_config.watch_dirs == [] do
-            [Volt.Paths.lib()]
+            [Paths.lib()]
           else
             server_config.watch_dirs
           end
@@ -103,7 +103,11 @@ defmodule Volt.DevServer do
           resolve_dirs: config.resolve_dirs,
           module_types: module_types,
           define:
-            Volt.Env.define(mode: "development", root: File.cwd!(), env_prefix: config.env_prefix)
+            Volt.Env.define(
+              mode: "development",
+              root: Paths.root(),
+              env_prefix: config.env_prefix
+            )
         ]
       end
 
@@ -121,7 +125,11 @@ defmodule Volt.DevServer do
       resolve_dirs: config.resolve_dirs,
       module_types: module_types,
       define:
-        Volt.Env.define(mode: "development", root: File.cwd!(), env_prefix: config.env_prefix),
+        Volt.Env.define(
+          mode: "development",
+          root: Paths.root(),
+          env_prefix: config.env_prefix
+        ),
       hmr_timeout: server_config.hmr_timeout,
       morph: server_config.morph,
       stylesheet_url: tailwind_root && tailwind_root.dev_url,
@@ -992,7 +1000,7 @@ defmodule Volt.DevServer do
   # any script in this response could run.
   defp send_compile_error(conn, path, errors, config) do
     Volt.HMR.error(path, errors, session: config.session)
-    message = "[Volt] Could not compile #{Path.relative_to_cwd(path)}"
+    message = "[Volt] Could not compile #{Path.relative_to(path, Paths.root())}"
 
     conn
     |> Conn.put_resp_content_type(Volt.MIME.javascript())
diff --git a/lib/volt/js/vendor.ex b/lib/volt/js/vendor.ex
index d2f5327..a2378c9 100644
--- a/lib/volt/js/vendor.ex
+++ b/lib/volt/js/vendor.ex
@@ -19,7 +19,7 @@ defmodule Volt.JS.Vendor do
 
   defp cache_dir do
     build_path = System.get_env("MIX_BUILD_PATH") || "_build"
-    Path.join(build_path, "volt/vendor")
+    Volt.Paths.expand(Path.join(build_path, "volt/vendor"))
   end
 
   defp context_dir(module_dirs, plugins, module_types) do
@@ -537,7 +537,7 @@ defmodule Volt.JS.Vendor do
   end
 
   defp project_root([module_dir | _]), do: Path.dirname(module_dir)
-  defp project_root([]), do: File.cwd!()
+  defp project_root([]), do: Volt.Paths.root()
 
   defp ensure_cache_dir(module_dirs, plugins, module_types) do
     File.mkdir_p!(context_dir(module_dirs, plugins, module_types))
@@ -653,12 +653,12 @@ defmodule Volt.JS.Vendor do
     |> Enum.flat_map(&lockfiles_in/1)
   end
 
-  defp lockfile_roots([]), do: [File.cwd!()]
+  defp lockfile_roots([]), do: [Volt.Paths.root()]
 
   defp lockfile_roots(module_dirs) do
     module_dirs
     |> Enum.map(&Path.dirname/1)
-    |> Kernel.++([File.cwd!()])
+    |> Kernel.++([Volt.Paths.root()])
     |> Enum.uniq()
   end
 
diff --git a/lib/volt/paths.ex b/lib/volt/paths.ex
index 0d5c72d..6e2c20d 100644
--- a/lib/volt/paths.ex
+++ b/lib/volt/paths.ex
@@ -17,6 +17,28 @@ defmodule Volt.Paths do
     def unquote(name)(), do: unquote(value)
   end
 
+  @root {__MODULE__, :root}
+
+  @doc """
+  Remember the working directory as the project root. Called when Volt starts.
+
+  The working directory belongs to the whole VM, and Mix changes it while it
+  compiles a dependency, as `Phoenix.CodeReloader` does for a reloadable path
+  dependency during a request. A relative path resolved in that window lands in
+  the dependency's directory, so the development server resolves paths from the
+  root captured here instead.
+  """
+  @spec capture_root() :: :ok
+  def capture_root, do: :persistent_term.put(@root, File.cwd!())
+
+  @doc "The project root: the working directory when Volt started, or the current one."
+  @spec root() :: String.t()
+  def root, do: :persistent_term.get(@root, nil) || File.cwd!()
+
+  @doc "Expand a path from the project root."
+  @spec expand(String.t()) :: String.t()
+  def expand(path), do: Path.expand(path, root())
+
   def ignored_dirs, do: @ignored_dirs
   def ignored_globs, do: Enum.map(@ignored_dirs, &"#{&1}/**")
 end
diff --git a/lib/volt/public_dir.ex b/lib/volt/public_dir.ex
index b95ebc1..3846a27 100644
--- a/lib/volt/public_dir.ex
+++ b/lib/volt/public_dir.ex
@@ -16,7 +16,7 @@ defmodule Volt.PublicDir do
   @spec resolve(String.t() | false | nil) :: String.t() | nil
   def resolve(false), do: nil
   def resolve(nil), do: nil
-  def resolve(path), do: Path.expand(path)
+  def resolve(path), do: Volt.Paths.expand(path)
 
   @doc """
   Copies all files from `public_dir` into `static_root`.
diff --git a/lib/volt/watcher.ex b/lib/volt/watcher.ex
index 32b904f..7ed38f4 100644
--- a/lib/volt/watcher.ex
+++ b/lib/volt/watcher.ex
@@ -37,6 +37,7 @@ defmodule Volt.Watcher do
   alias Volt.HMR
   alias Volt.HMR.StyleGraph
   alias Volt.JS.Extensions
+  alias Volt.Paths
 
   @dialyzer {:nowarn_function, detect_changes: 2}
 
@@ -85,9 +86,9 @@ defmodule Volt.Watcher do
         owner when is_pid(owner) -> Process.monitor(owner)
       end
 
-    root = Keyword.fetch!(opts, :root) |> Path.expand()
-    watch_dirs = Keyword.get(opts, :watch_dirs, []) |> Enum.map(&Path.expand/1)
-    reload_dirs = Keyword.get(opts, :reload_dirs, []) |> Enum.map(&Path.expand/1)
+    root = Keyword.fetch!(opts, :root) |> Paths.expand()
+    watch_dirs = Keyword.get(opts, :watch_dirs, []) |> Enum.map(&Paths.expand/1)
+    reload_dirs = Keyword.get(opts, :reload_dirs, []) |> Enum.map(&Paths.expand/1)
     tailwind_outdir = Keyword.get(opts, :tailwind_outdir) |> maybe_expand()
     tailwind_name = Keyword.get(opts, :tailwind_name, "app")
     tailwind_url = Keyword.get(opts, :tailwind_url, "/assets/css/#{tailwind_name}.css")
@@ -121,7 +122,7 @@ defmodule Volt.Watcher do
 
     source_dirs =
       if config[:tailwind] do
-        Enum.map(configured_tailwind_sources || [], &Path.expand(&1.base))
+        Enum.map(configured_tailwind_sources || [], &Paths.expand(&1.base))
       else
         []
       end
@@ -264,7 +265,7 @@ defmodule Volt.Watcher do
     end
   end
 
-  defp read_tailwind_css(nil), do: {:ok, {nil, File.cwd!()}}
+  defp read_tailwind_css(nil), do: {:ok, {nil, Paths.root()}}
 
   defp read_tailwind_css(path) do
     case File.read(path) do
@@ -572,7 +573,7 @@ defmodule Volt.Watcher do
   end
 
   defp handle_reload_change(path, state) do
-    path = Path.relative_to_cwd(path)
+    path = Path.relative_to(path, Paths.root())
     HMR.document_update(path, session: state.session)
   end
 
@@ -791,5 +792,5 @@ defmodule Volt.Watcher do
   end
 
   defp maybe_expand(nil), do: nil
-  defp maybe_expand(path), do: Path.expand(path)
+  defp maybe_expand(path), do: Paths.expand(path)
 end
diff --git a/lib/volt/watcher/ignore.ex b/lib/volt/watcher/ignore.ex
index 906f78f..5a5bebc 100644
--- a/lib/volt/watcher/ignore.ex
+++ b/lib/volt/watcher/ignore.ex
@@ -16,7 +16,7 @@ defmodule Volt.Watcher.Ignore do
   # Configured patterns also resolve from the project directory, so that
   # `_build/**` matches a watch root that itself lives inside `_build`.
   def compile_explicit(patterns, roots),
-    do: compile_patterns(patterns, Enum.uniq([File.cwd!() | roots]))
+    do: compile_patterns(patterns, Enum.uniq([Volt.Paths.root() | roots]))
 
   defp compile_patterns(patterns, roots) do
     patterns
diff --git a/test/volt/js/vendor_test.exs b/test/volt/js/vendor_test.exs
index 45f8ff3..342e419 100644
--- a/test/volt/js/vendor_test.exs
+++ b/test/volt/js/vendor_test.exs
@@ -73,6 +73,33 @@ defmodule Volt.JS.VendorTest do
                "Pre-bundled"
     end
 
+    @tag :tmp_dir
+    test "writes the cache under the project root while the working directory is elsewhere",
+         %{tmp_dir: elsewhere} do
+      # Mix changes the VM's working directory while it compiles a dependency,
+      # as Phoenix's code reloader does during a request.
+      {:ok, vendor_map} =
+        File.cd!(elsewhere, fn ->
+          Volt.JS.Vendor.prebundle(
+            root: Path.join(@fixture_dir, "src"),
+            node_modules: @node_modules,
+            force: true
+          )
+        end)
+
+      assert File.ls!(elsewhere) == []
+
+      for {_specifier, path} <- vendor_map do
+        assert String.starts_with?(path, Volt.Paths.expand("_build"))
+        assert File.regular?(path)
+      end
+
+      assert {:ok, _code} =
+               File.cd!(elsewhere, fn ->
+                 Volt.JS.Vendor.read("fake-lib", node_modules: @node_modules)
+               end)
+    end
+
     test "caches bundled files on disk" do
       Volt.JS.Vendor.prebundle(
         root: Path.join(@fixture_dir, "src"),

From fc1dc3194f64c6315b881bc078eb208d8148fbeb Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Mon, 5 Oct 2026 16:50:35 +0400
Subject: [PATCH 4/5] Pre-bundle once per source change instead of on every
 request

Phoenix runs a plug's init/1 on every request in development, and
Volt.DevServer.init/1 pre-bundles vendor packages. Two things made that
expensive and unsafe:

A bare import that resolves to no package, such as one the host page
provides, is never written to the cache, so it never counted as fresh
and every call bundled all packages again. Concurrent requests then
replaced cache files that other requests were reading, which fits the
module graph failing to load right after a restart. Such imports are no
longer part of the freshness check.

Even with a fresh cache, each request scanned every source file for
imports. With a watcher, the dev server now pre-bundles once and again
only after the watcher sees a source file change, and requests with the
same options take turns. Without a watcher nothing says when sources
change, so it scans on every init as before.

Fixes #59
---
 .reach.exs                   |  1 +
 CHANGELOG.md                 |  1 +
 lib/volt/application.ex      |  1 +
 lib/volt/dev/prebundled.ex   | 38 ++++++++++++++++++++++++++++++++++
 lib/volt/dev_server.ex       | 27 +++++++++++++++---------
 lib/volt/js/vendor.ex        |  6 ++++++
 lib/volt/watcher.ex          |  2 ++
 test/volt/js/vendor_test.exs | 40 ++++++++++++++++++++++++++++++++++++
 test/volt/watcher_test.exs   | 18 ++++++++++++++++
 9 files changed, 124 insertions(+), 10 deletions(-)
 create mode 100644 lib/volt/dev/prebundled.ex

diff --git a/.reach.exs b/.reach.exs
index 95d1719..b5c372c 100644
--- a/.reach.exs
+++ b/.reach.exs
@@ -141,6 +141,7 @@ infrastructure = [
   "Volt.Cache",
   "Volt.Dev",
   "Volt.Dev.Cleanup",
+  "Volt.Dev.Prebundled",
   "Volt.Dev.Error",
   "Volt.Priv.Vendor",
   "Volt.DevServer.ClientTag",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d73840f..82df75a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Leave Vue `<script>` blocks in other languages, such as `<script lang="elixir">`, out of the script modules that `mix volt.js.check` lints and type-checks. Every block was treated as JavaScript, so such a block was reported as TypeScript syntax errors. `lang="jsx"` blocks are now checked as JSX ([#57](https://github.com/elixir-volt/volt/issues/57)).
 - Serve the `@oxc-project/runtime` helpers that the dev server's own output imports. With a `:target` below ES2022, a class with fields compiles to an import of such a helper, which `/@vendor/` answered with 404 unless the npm package was installed, so the importing module and everything importing it failed to load with no error shown. The helpers now come from the bundler, as in production builds ([#58](https://github.com/elixir-volt/volt/issues/58)).
+- Stop the dev server scanning sources and pre-bundling packages on every request. Phoenix initializes plugs per request in development, and one import that resolves to no package, such as one the page provides, made every request bundle all packages again, with concurrent requests replacing cache files others were reading. Pre-bundling now runs once and again after a source file changes, requests take turns, and unresolvable imports no longer count as stale ([#59](https://github.com/elixir-volt/volt/issues/59)).
 - Resolve the dev server's paths from the directory Volt started in, not the current working directory. `Phoenix.CodeReloader` changes the VM's working directory while it compiles a reloadable path dependency, so a vendor request served at the same time wrote its cache into the dependency's `_build`, or failed with `could not write to file`. The vendor cache, asset root, watched directories and Tailwind input are affected ([#56](https://github.com/elixir-volt/volt/issues/56)).
 
 ## 0.20.0 - 2026-10-03
diff --git a/lib/volt/application.ex b/lib/volt/application.ex
index 5eae0f6..4ecf084 100644
--- a/lib/volt/application.ex
+++ b/lib/volt/application.ex
@@ -12,6 +12,7 @@ defmodule Volt.Application do
     Volt.HMR.StyleGraph.create_table()
     Volt.HMR.ModuleGraph.create_table()
     Volt.HMR.Errors.create_table()
+    Volt.Dev.Prebundled.create_table()
 
     # Watchers release their Tailwind contexts when they terminate, so the
     # Tailwind processes start before them and stop after them.
diff --git a/lib/volt/dev/prebundled.ex b/lib/volt/dev/prebundled.ex
new file mode 100644
index 0000000..2201052
--- /dev/null
+++ b/lib/volt/dev/prebundled.ex
@@ -0,0 +1,38 @@
+defmodule Volt.Dev.Prebundled do
+  @moduledoc false
+  # Which sets of vendor options have been pre-bundled since the sources last
+  # changed.
+  #
+  # Phoenix initializes plugs on every request in development, so the dev
+  # server asks for a pre-bundle on every request. Scanning the sources each
+  # time is wasted work, and concurrent requests bundling at once would replace
+  # cache files that others are reading.
+
+  @table :volt_vendor_prebundled
+
+  def create_table, do: Volt.ETS.create_named_set(@table)
+
+  @doc """
+  Run `prebundle` unless it already ran for `opts` since `forget/0`. Callers
+  with the same options take turns, so one bundles and the rest find it done.
+  """
+  @spec ensure(keyword(), (-> term())) :: :ok
+  def ensure(opts, prebundle) when is_function(prebundle, 0) do
+    :global.trans(
+      {{__MODULE__, opts}, self()},
+      fn ->
+        if :ets.lookup(@table, opts) == [] do
+          prebundle.()
+          Volt.ETS.put(@table, {opts})
+        end
+      end,
+      [node()]
+    )
+
+    :ok
+  end
+
+  @doc "Make `ensure/2` run again. A changed source may import a package that is not bundled yet."
+  @spec forget() :: :ok
+  def forget, do: Volt.ETS.clear(@table)
+end
diff --git a/lib/volt/dev_server.ex b/lib/volt/dev_server.ex
index efff655..0163683 100644
--- a/lib/volt/dev_server.ex
+++ b/lib/volt/dev_server.ex
@@ -58,7 +58,19 @@ defmodule Volt.DevServer do
       if Volt.Config.Tailwind.enabled?(tailwind_config),
         do: Volt.Config.Tailwind.new(tailwind_config)
 
-    prebundle_vendor(expanded_root, node_modules, plugins, config.resolve_dirs, module_types)
+    # A watcher says when sources change, so the scan can wait for that.
+    watched? = server_config.watch or not is_nil(Keyword.get(opts, :session_supervisor))
+
+    prebundle_vendor(
+      [
+        root: expanded_root,
+        node_modules: node_modules,
+        plugins: plugins,
+        resolve_dirs: config.resolve_dirs,
+        module_types: module_types
+      ],
+      watched?
+    )
 
     session =
       if server_config.watch do
@@ -935,15 +947,10 @@ defmodule Volt.DevServer do
 
   # ── Vendor pre-bundling ───────────────────────────────────────────
 
-  defp prebundle_vendor(root, node_modules, plugins, resolve_dirs, module_types) do
-    Volt.JS.Vendor.prebundle(
-      root: root,
-      node_modules: node_modules,
-      plugins: plugins,
-      resolve_dirs: resolve_dirs,
-      module_types: module_types
-    )
-  end
+  defp prebundle_vendor(opts, true),
+    do: Volt.Dev.Prebundled.ensure(opts, fn -> Volt.JS.Vendor.prebundle(opts) end)
+
+  defp prebundle_vendor(opts, false), do: Volt.JS.Vendor.prebundle(opts)
 
   defp serve_vendor(specifier, config, browser_hash) do
     vendor_opts = vendor_opts(config)
diff --git a/lib/volt/js/vendor.ex b/lib/volt/js/vendor.ex
index a2378c9..11ed2cf 100644
--- a/lib/volt/js/vendor.ex
+++ b/lib/volt/js/vendor.ex
@@ -191,6 +191,12 @@ defmodule Volt.JS.Vendor do
   defp prebundle_vendors([], _module_dirs, _force, _plugins, _module_types), do: {:ok, %{}}
 
   defp prebundle_vendors(specifiers, module_dirs, force, plugins, module_types) do
+    # A bare import that resolves to no package, such as one a plugin or the
+    # host page provides, is never written to the cache. Counting it as stale
+    # would bundle every package again on each call.
+    specifiers =
+      Enum.filter(specifiers, &match?({:ok, _, _}, bundle_entry_for(&1, module_dirs, plugins)))
+
     vendor_map = Map.new(specifiers, &{&1, cache_path(&1, module_dirs, plugins, module_types)})
 
     if not force and Enum.all?(specifiers, &cache_fresh?(&1, module_dirs, plugins, module_types)) do
diff --git a/lib/volt/watcher.ex b/lib/volt/watcher.ex
index 7ed38f4..3b4909c 100644
--- a/lib/volt/watcher.ex
+++ b/lib/volt/watcher.ex
@@ -297,6 +297,8 @@ defmodule Volt.Watcher do
           {:noreply, state}
 
         ext in Extensions.watchable_js(state.config[:plugins] || []) ->
+          # The change may add an import of a package that is not bundled yet.
+          Volt.Dev.Prebundled.forget()
           state = schedule_rebuild(state, path)
           state = maybe_schedule_tailwind(state, path)
           {:noreply, state}
diff --git a/test/volt/js/vendor_test.exs b/test/volt/js/vendor_test.exs
index 342e419..1d14363 100644
--- a/test/volt/js/vendor_test.exs
+++ b/test/volt/js/vendor_test.exs
@@ -100,6 +100,46 @@ defmodule Volt.JS.VendorTest do
                end)
     end
 
+    test "an import that resolves to no package does not bundle the others again" do
+      File.write!(
+        Path.join(@fixture_dir, "src/provided.ts"),
+        "import { value } from 'fake-lib'\nimport host from 'provided-by-the-page'\nconsole.log(value, host)"
+      )
+
+      on_exit(fn -> File.rm(Path.join(@fixture_dir, "src/provided.ts")) end)
+      opts = [root: Path.join(@fixture_dir, "src"), node_modules: @node_modules]
+
+      {:ok, vendor_map} = Volt.JS.Vendor.prebundle(Keyword.put(opts, :force, true))
+      assert Map.has_key?(vendor_map, "fake-lib")
+      refute Map.has_key?(vendor_map, "provided-by-the-page")
+
+      refute ExUnit.CaptureLog.capture_log(fn -> Volt.JS.Vendor.prebundle(opts) end) =~
+               "Pre-bundled"
+    end
+
+    test "is not repeated on every request until the sources are said to have changed" do
+      opts = [root: Path.join(@fixture_dir, "src"), node_modules: @node_modules]
+
+      prebundle = fn ->
+        Volt.Dev.Prebundled.ensure(opts, fn -> Volt.JS.Vendor.prebundle(opts) end)
+      end
+
+      Volt.Dev.Prebundled.forget()
+      on_exit(&Volt.Dev.Prebundled.forget/0)
+
+      :ok = prebundle.()
+      [cached] = Path.wildcard("_build/volt/vendor/*/fake-lib.js")
+      File.rm!(cached)
+
+      # Asked again, as on every request: nothing is scanned or bundled.
+      :ok = prebundle.()
+      refute File.exists?(cached)
+
+      Volt.Dev.Prebundled.forget()
+      :ok = prebundle.()
+      assert File.exists?(cached)
+    end
+
     test "caches bundled files on disk" do
       Volt.JS.Vendor.prebundle(
         root: Path.join(@fixture_dir, "src"),
diff --git a/test/volt/watcher_test.exs b/test/volt/watcher_test.exs
index c8b5d91..274178e 100644
--- a/test/volt/watcher_test.exs
+++ b/test/volt/watcher_test.exs
@@ -357,6 +357,24 @@ defmodule Volt.WatcherTest do
     GenServer.stop(pid)
   end
 
+  test "a changed source makes the next request scan for new package imports", %{
+    watch_dir: watch_dir
+  } do
+    source = Path.join(watch_dir, "app.ts")
+    File.write!(source, "export const x = 1")
+    opts = [root: watch_dir, node_modules: Path.join(watch_dir, "node_modules")]
+
+    :ok = Volt.Dev.Prebundled.ensure(opts, fn -> :ok end)
+    assert :ets.lookup(:volt_vendor_prebundled, opts) != []
+
+    {:ok, pid} = Volt.Watcher.start_link(root: watch_dir, name: :test_watcher_forget_prebundled)
+    state = send_file_event(pid, source)
+    Process.cancel_timer(state.pending[source])
+
+    assert :ets.lookup(:volt_vendor_prebundled, opts) == []
+    GenServer.stop(pid)
+  end
+
   test "ignores configured watcher paths", %{watch_dir: watch_dir} do
     generated_dir = Path.join(watch_dir, ".generated")
     entry = Path.join(generated_dir, "entry.ts")

From 66ba43c4b3a2256c84258aa265d5390004e0c7d4 Mon Sep 17 00:00:00 2001
From: Danila Poyarkov <dev@dannote.net>
Date: Mon, 5 Oct 2026 16:56:59 +0400
Subject: [PATCH 5/5] Type-check component scripts with the project's tsconfig

The script of a .vue or .svelte file goes to tsgolint as a virtual
module in its source overrides. tsgolint assigns a file to a project by
the nearest tsconfig.json that includes it, and expands include by
listing directories on disk. Its overlay for the overrides answers
"does this file exist" and "read it", but directory listings still come
from disk, so a virtual module is never included and lands in an
inferred project: no paths, and none of the project's declaration
files.

tsgolint reads a tsconfig.json through the same overlay. So the nearest
tsconfig.json is overridden with one that extends the original, carried
unchanged under another name beside it, and names the virtual modules
in files. The original's own files are repeated, since files replaces
the extended config's, and the default include is spelled out when the
original relied on it.

Fixes #60
---
 .reach.exs                                  |  1 +
 CHANGELOG.md                                |  1 +
 lib/volt/js/check.ex                        |  5 +-
 lib/volt/js/lint/tsconfig_overlay.ex        | 99 +++++++++++++++++++++
 test/mix/tasks/volt/js/check_test.exs       | 58 ++++++++++++
 test/volt/js/lint/tsconfig_overlay_test.exs | 72 +++++++++++++++
 6 files changed, 235 insertions(+), 1 deletion(-)
 create mode 100644 lib/volt/js/lint/tsconfig_overlay.ex
 create mode 100644 test/volt/js/lint/tsconfig_overlay_test.exs

diff --git a/.reach.exs b/.reach.exs
index b5c372c..f4e26ce 100644
--- a/.reach.exs
+++ b/.reach.exs
@@ -102,6 +102,7 @@ logic = [
   "Volt.JS.Check",
   "Volt.JS.CommonJS",
   "Volt.JS.Lint.Config",
+  "Volt.JS.Lint.TSConfigOverlay",
   "Volt.JS.Extensions",
   "Volt.JS.Format",
   "Volt.JS.Discovery",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82df75a..7969a2e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
 
 - Leave Vue `<script>` blocks in other languages, such as `<script lang="elixir">`, out of the script modules that `mix volt.js.check` lints and type-checks. Every block was treated as JavaScript, so such a block was reported as TypeScript syntax errors. `lang="jsx"` blocks are now checked as JSX ([#57](https://github.com/elixir-volt/volt/issues/57)).
 - Serve the `@oxc-project/runtime` helpers that the dev server's own output imports. With a `:target` below ES2022, a class with fields compiles to an import of such a helper, which `/@vendor/` answered with 404 unless the npm package was installed, so the importing module and everything importing it failed to load with no error shown. The helpers now come from the bundler, as in production builds ([#58](https://github.com/elixir-volt/volt/issues/58)).
+- Type-check the scripts of `.vue` and `.svelte` files with the project's `tsconfig.json`. `mix volt.js.check --type-aware --type-check` checked them in a project of their own with default options, so imports through `paths` aliases and of other components failed with TS2307 even with a `declare module "*.vue"` declaration ([#60](https://github.com/elixir-volt/volt/issues/60)).
 - Stop the dev server scanning sources and pre-bundling packages on every request. Phoenix initializes plugs per request in development, and one import that resolves to no package, such as one the page provides, made every request bundle all packages again, with concurrent requests replacing cache files others were reading. Pre-bundling now runs once and again after a source file changes, requests take turns, and unresolvable imports no longer count as stale ([#59](https://github.com/elixir-volt/volt/issues/59)).
 - Resolve the dev server's paths from the directory Volt started in, not the current working directory. `Phoenix.CodeReloader` changes the VM's working directory while it compiles a reloadable path dependency, so a vendor request served at the same time wrote its cache into the dependency's `_build`, or failed with `could not write to file`. The vendor cache, asset root, watched directories and Tailwind input are affected ([#56](https://github.com/elixir-volt/volt/issues/56)).
 
diff --git a/lib/volt/js/check.ex b/lib/volt/js/check.ex
index 88b6631..ab89ee6 100644
--- a/lib/volt/js/check.ex
+++ b/lib/volt/js/check.ex
@@ -76,7 +76,10 @@ defmodule Volt.JS.Check do
       [
         type_aware: true,
         type_check: opts[:type_check] == true,
-        source_overrides: Map.merge(source_overrides, Keyword.get(config, :source_overrides, %{}))
+        source_overrides:
+          source_overrides
+          |> Map.merge(Volt.JS.Lint.TSConfigOverlay.overrides(Map.keys(source_overrides)))
+          |> Map.merge(Keyword.get(config, :source_overrides, %{}))
       ] ++ type_aware_options(config)
 
     files
diff --git a/lib/volt/js/lint/tsconfig_overlay.ex b/lib/volt/js/lint/tsconfig_overlay.ex
new file mode 100644
index 0000000..718087c
--- /dev/null
+++ b/lib/volt/js/lint/tsconfig_overlay.ex
@@ -0,0 +1,99 @@
+defmodule Volt.JS.Lint.TSConfigOverlay do
+  @moduledoc """
+  Puts virtual modules, such as the scripts of a `.vue` file, into the TypeScript
+  project that covers them.
+
+  tsgolint assigns a file to a project by the nearest `tsconfig.json` that
+  includes it, and expands `include` by listing directories on disk. A virtual
+  module is not on disk, so it lands in an inferred project with default
+  options: the project's `paths` do not apply to it, and the declaration files
+  the project includes are not in its program.
+
+  tsgolint does read file contents, and a `tsconfig.json` among them, through
+  the same overrides that carry the virtual modules. So the nearest
+  `tsconfig.json` is overridden with one that extends the original and names
+  the virtual modules in `files`. The original is carried unchanged under
+  another name beside it, so relative paths in it keep their meaning.
+  """
+
+  @base "tsconfig.volt-base.json"
+
+  @doc """
+  Return the source overrides that add `virtual_files` to their projects.
+
+  A virtual module without a `tsconfig.json` above it, or whose `tsconfig.json`
+  cannot be read as an object, is left to the inferred project.
+  """
+  @spec overrides([String.t()]) :: %{String.t() => String.t()}
+  def overrides(virtual_files) do
+    virtual_files
+    |> Enum.group_by(&nearest_tsconfig(Path.dirname(&1)))
+    |> Enum.flat_map(fn
+      {nil, _files} -> []
+      {tsconfig, files} -> project(tsconfig, Enum.sort(files))
+    end)
+    |> Map.new()
+  end
+
+  defp nearest_tsconfig(dir) do
+    tsconfig = Path.join(dir, "tsconfig.json")
+    parent = Path.dirname(dir)
+
+    cond do
+      File.regular?(tsconfig) -> tsconfig
+      parent == dir -> nil
+      true -> nearest_tsconfig(parent)
+    end
+  end
+
+  defp project(tsconfig, virtual_files) do
+    with {:ok, source} <- File.read(tsconfig),
+         {:ok, properties} <- properties(source) do
+      [
+        {Path.join(Path.dirname(tsconfig), @base), source},
+        {tsconfig, Jason.encode!(extending(properties, virtual_files))}
+      ]
+    else
+      _unreadable -> []
+    end
+  end
+
+  # `files` in a config replaces the `files` of the config it extends, and a
+  # config with `files` and no `include` includes nothing else. So the original's
+  # own `files` are repeated, and the default `include` is spelled out when the
+  # original relied on it.
+  defp extending(properties, virtual_files) do
+    config = %{
+      "extends" => "./" <> @base,
+      "files" => string_elements(properties["files"]) ++ virtual_files
+    }
+
+    if Enum.any?(["files", "include", "extends"], &Map.has_key?(properties, &1)),
+      do: config,
+      else: Map.put(config, "include", ["**/*"])
+  end
+
+  # A tsconfig may have comments and trailing commas, which makes it a
+  # JavaScript object literal rather than JSON.
+  defp properties(source) do
+    case OXC.parse("(" <> source <> "\n)", "tsconfig.js") do
+      {:ok, %{body: [%{expression: %{expression: %{type: :object_expression} = object}}]}} ->
+        properties =
+          for %{key: key, value: value} <- object.properties,
+              {:ok, name} <- [Volt.JS.AST.property_key(key)],
+              into: %{},
+              do: {name, value}
+
+        {:ok, properties}
+
+      _other ->
+        :error
+    end
+  end
+
+  defp string_elements(%{type: :array_expression, elements: elements}) do
+    for %{type: :literal, value: value} <- elements, is_binary(value), do: value
+  end
+
+  defp string_elements(_absent), do: []
+end
diff --git a/test/mix/tasks/volt/js/check_test.exs b/test/mix/tasks/volt/js/check_test.exs
index 99c6e30..0502492 100644
--- a/test/mix/tasks/volt/js/check_test.exs
+++ b/test/mix/tasks/volt/js/check_test.exs
@@ -208,6 +208,64 @@ defmodule Mix.Tasks.Volt.Js.CheckTest do
              "svelteValue"
   end
 
+  @tsgolint Path.expand("node_modules/.bin/tsgolint")
+
+  # Runs the real tsgolint, which CI and `npm ci` install.
+  @tag skip: not File.exists?(@tsgolint)
+  test "component scripts are type-checked with the project's tsconfig" do
+    write = fn path, content ->
+      path = Path.join(@tmp_dir, path)
+      File.mkdir_p!(Path.dirname(path))
+      File.write!(path, content)
+    end
+
+    write.("tsconfig.json", """
+    {
+      "compilerOptions": {
+        "strict": true,
+        "noEmit": true,
+        "moduleResolution": "Bundler",
+        "paths": { "@/*": ["./assets/js/*"] }
+      },
+      "include": ["assets/js/**/*.ts", "lib/**/*.ts"]
+    }
+    """)
+
+    write.("assets/js/ui/variants.ts", "export const button = (n: number) => n\n")
+    write.("assets/js/ui/Button.vue", "<template><button /></template>\n")
+
+    write.("assets/js/vue.d.ts", """
+    declare module "*.vue" {
+      const component: unknown
+      export default component
+    }
+    """)
+
+    write.("lib/app_web/Tally.vue", """
+    <script setup lang="ts">
+    import Button from "@/ui/Button.vue"
+    import { button } from "@/ui/variants"
+    const probe: (n: number) => void = (n: string) => n
+    console.log(Button, button, probe)
+    </script>
+    <template><p /></template>
+    """)
+
+    Application.put_env(:volt, :sources, ["lib/**/*.vue"])
+    Application.put_env(:volt, :lint, tsgolint: @tsgolint, rules: %{})
+
+    output =
+      capture_io(:stderr, fn ->
+        catch_exit(Mix.Tasks.Volt.Js.Check.run(["--type-aware", "--type-check"]))
+      end)
+
+    # The script is type-checked, and with the project's options: the path
+    # alias and the `*.vue` declaration resolve.
+    assert output =~ "TS2322"
+    refute output =~ "TS2307"
+    refute output =~ "Cannot find module"
+  end
+
   test "type-aware overrides batch by effective rules and use original SFC paths" do
     files = Enum.map(["app.ts", "Component.vue", "Widget.svelte"], &Path.join(@tmp_dir, &1))
     [app, vue, svelte] = files
diff --git a/test/volt/js/lint/tsconfig_overlay_test.exs b/test/volt/js/lint/tsconfig_overlay_test.exs
new file mode 100644
index 0000000..bfeb21e
--- /dev/null
+++ b/test/volt/js/lint/tsconfig_overlay_test.exs
@@ -0,0 +1,72 @@
+defmodule Volt.JS.Lint.TSConfigOverlayTest do
+  use ExUnit.Case, async: true
+
+  alias Volt.JS.Lint.TSConfigOverlay
+
+  @moduletag :tmp_dir
+
+  defp write!(root, path, content) do
+    path = Path.join(root, path)
+    File.mkdir_p!(Path.dirname(path))
+    File.write!(path, content)
+    path
+  end
+
+  test "adds virtual modules to the project of the nearest tsconfig", %{tmp_dir: root} do
+    original = """
+    {
+      // comments and trailing commas are allowed in a tsconfig
+      "compilerOptions": { "paths": { "@/*": ["./assets/js/*"] }, },
+      "include": ["assets/js/**/*.ts"],
+    }
+    """
+
+    tsconfig = write!(root, "tsconfig.json", original)
+    first = Path.join(root, "lib/app_web/Tally.vue.script0.ts")
+    second = Path.join(root, "assets/js/Card.vue.script0.ts")
+
+    overrides = TSConfigOverlay.overrides([first, second])
+
+    # The original is carried unchanged beside the tsconfig that replaces it.
+    assert overrides[Path.join(root, "tsconfig.volt-base.json")] == original
+
+    assert Jason.decode!(overrides[tsconfig]) == %{
+             "extends" => "./tsconfig.volt-base.json",
+             "files" => [second, first]
+           }
+  end
+
+  test "keeps the files the original names, which `files` would replace", %{tmp_dir: root} do
+    tsconfig = write!(root, "tsconfig.json", ~s({ files: ["src/main.ts", "./env.d.ts"] }))
+    virtual = Path.join(root, "src/App.vue.script0.ts")
+
+    assert %{"files" => ["src/main.ts", "./env.d.ts", ^virtual]} =
+             TSConfigOverlay.overrides([virtual])[tsconfig] |> Jason.decode!()
+  end
+
+  test "spells out the default include a tsconfig without one relies on", %{tmp_dir: root} do
+    tsconfig = write!(root, "tsconfig.json", ~s({ "compilerOptions": { "strict": true } }))
+    virtual = Path.join(root, "App.vue.script0.ts")
+
+    assert %{"include" => ["**/*"], "files" => [^virtual]} =
+             TSConfigOverlay.overrides([virtual])[tsconfig] |> Jason.decode!()
+  end
+
+  test "uses the nearest tsconfig for each virtual module", %{tmp_dir: root} do
+    outer = write!(root, "tsconfig.json", ~s({ "include": ["**/*"] }))
+    inner = write!(root, "assets/tsconfig.json", ~s({ "include": ["**/*"] }))
+    in_lib = Path.join(root, "lib/Page.vue.script0.ts")
+    in_assets = Path.join(root, "assets/js/App.vue.script0.ts")
+
+    overrides = TSConfigOverlay.overrides([in_lib, in_assets])
+
+    assert %{"files" => [^in_lib]} = Jason.decode!(overrides[outer])
+    assert %{"files" => [^in_assets]} = Jason.decode!(overrides[inner])
+  end
+
+  test "leaves virtual modules alone without a readable tsconfig above them", %{tmp_dir: root} do
+    write!(root, "broken/tsconfig.json", "not a config")
+
+    assert TSConfigOverlay.overrides([Path.join(root, "broken/App.vue.script0.ts")]) == %{}
+  end
+end