Skip to content

Type the stubs of imported JavaScript modules from TypeScript and JSDoc - #7951

Draft
FarhanAliRaza wants to merge 21 commits into
farhan/focused-darwin-dx76ek-js-modulesfrom
farhan/focused-darwin-dx76ek-js-stubs
Draft

FarhanAliRaza wants to merge 21 commits into
farhan/focused-darwin-dx76ek-js-modulesfrom
farhan/focused-darwin-dx76ek-js-stubs

Conversation

@FarhanAliRaza

@FarhanAliRaza FarhanAliRaza commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Type of change

  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update

Description

Third of the ENG-9127 stack, on top of #7950.

Problem. Python can now import a JavaScript module's functions, but nothing checks the calls. A wrong argument type, or a missing argument, shows up only in the browser.

Change. In dev mode, Reflex writes a type stub (party.pyi) next to each imported JS/TS module, so pyright and mypy check every call:

// my_app/scripts/typed.ts
export function setText(elementId: string, count: number): void { ... }
export function flags(elementId: string, on: boolean, tags: string[]): void { ... }

becomes

def setText(elementId: str | Var[str] | EventCallback[...], count: float | Var[float], /) -> EventSpec: ...
def flags(elementId: str | Var[str] | EventCallback[...], on: bool | Var[bool], tags: Sequence[str] | Var[Sequence[str]], /) -> EventSpec: ...

Argument types come from TypeScript annotations or, in .js files, from JSDoc. The TypeScript checker classifies each type. Nothing is parsed out of printed type strings.

TypeScript Python
string str (also accepts an event handler, which is sent as its name)
number / boolean float / bool
T[], tuples Sequence[...]
Record<string, T> Mapping[str, T]
literal unions, enums Literal[...]
Set, Map, bigint, Promise, functions, classes, DOM types, untyped Any, because arguments arrive as JSON

Rules.

  • Stubs are written only in dev mode. Production builds write none and don't install typescript.
  • The .pyi extension is ignored by hot reload, so writing a stub doesn't restart the backend.
  • The docs recommend committing stubs, so type checking works in CI without Node.
  • A stub is rewritten only when what it is made from changes:
    • the module's scripts and the files it reads types from;
    • .web/package.json;
    • the stub generator itself.
  • A stub Reflex wrote for a module the app no longer imports is removed. A hand-written .pyi is never touched.
  • A stub declares only names the runtime module really exports as functions. Type-only exports are left out, so a stub never lets pyright accept an import that fails at runtime.
  • A stub imports only the names it uses, and passes pyright in strict mode.
  • Type-only references (JSDoc import("…"), /// <reference>, import type, .d.ts) count toward the stub but are never copied into .web. A type file outside the package is no longer a compile error.

Warnings. Each states the problem, its cause and the fix. When the types can't be read, the stubs accept any arguments and the app still runs. For example:

Reflex could not read the argument types of the JavaScript modules …, so their type stubs accept any arguments: reading them needs Node.js or Bun, and neither was found. The app still runs. Install Node.js 22.22.0 or newer, then run the app again.

Tests

  • Unit: the Python renderer, run on the real output of script-signatures.js from a fixture that vitest also checks. The failure paths run a real subprocess: no runtime, non-zero exit, bad JSON, timeout. The digest is compared exactly, orphaned stubs are removed, and a production compile writes no stub.
  • vitest: script-signatures.js is fully covered.
  • Playwright test_call_script.py: the stub generated for a module is checked against its exact text.
  • Coverage: 100% of the added Python lines and branches and JS statements. ruff, pyright and npm run check are clean.
  • Example app: pyright reports 6 errors on typecheck_bad.py and none on typecheck_good.py or the app.

https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf

The stub written next to an imported JavaScript module typed every function
as `(*args: Any)`. It now reads each export's call signatures with the
TypeScript checker, from annotations in a .ts file or JSDoc in a .js file,
through script-signatures.js, which ships to .web beside the other build
scripts an app runs:

  /** @PARAM {number} count  @PARAM {string} elementId  @PARAM {boolean} [loud] */
  export function celebrate(count, elementId, loud = false) {}

  def celebrate(count: float | Var[float],
                elementId: str | Var[str] | EventCallback[*tuple[Any, ...]],
                loud: bool | Var[bool] = ..., /) -> EventSpec: ...

Arguments are positional-only, as JavaScript passes them. JSON types map to
Python (number to float, T[] to Sequence, unions, literals, `| null`); types
with no JSON form become Any. A string parameter also takes an event handler,
which the call sends as its name. Overloads become @overload, rest parameters
*args, and exports that are not functions are left out.

typescript (pinned to the version reflex-frontend checks itself with, which a
test keeps equal) is installed only with apps that import a module, and runs
after the install, once for every stale module. The stub's header records a
digest of the module and the scripts beside it, so typescript does not run
while they are unchanged. When the types cannot be read (no node or bun, or the
script fails) the stub stays untyped, with a warning, and is retried on the
next compile.

Part of ENG-9127.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
@greptile-apps

greptile-apps Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

RetriggerView in GreptileConfidence Score: 4/5

[Medium impact] The changes affect development builds for apps that import JavaScript modules from Python.

The complete-output testing requirement must be satisfied before merging; recursive types also need a safe fallback.

Findings

  1. P2 Recursive types disable argument checks ▶
  2. P2 Test misses unexpected stub output ▶

Summary

Adds typed Python stubs for imported JavaScript modules using TypeScript annotations and JSDoc.

  • Python calls to imported JavaScript functions now get types from TypeScript and JSDoc.
  • Changes to local type files now refresh the generated JavaScript stub.
  • Development builds refresh generated stubs and remove them when imports disappear.

Reviews (8) · Last reviewed commit: "Cover re-exported names in the signature..." · Reviewed by Greptile

@codspeed

codspeed Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

1 warning

⚠️ 19 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 146 untouched benchmarks
⏩ 8 skipped benchmarks1


Comparing farhan/focused-darwin-dx76ek-js-stubs (7a8bad9) with farhan/focused-darwin-dx76ek-js-modules (c65c654)

Open in CodSpeed

Footnotes

  1. 8 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

…cused-darwin-dx76ek-js-stubs

# Conflicts:
#	packages/reflex-base/src/reflex_base/js/modules.py
#	reflex/compiler/utils.py
#	tests/units/compiler/test_compiler_utils.py
#	tests/units/reflex_base/js/test_modules.py
…s, cache key

- A parameter renamed from a non-identifier (`$value` -> `arg0`) no longer
  takes the name of another parameter, which made the stub invalid Python.
- Only trailing optional parameters get defaults: in `f(prefix = "", count)`
  Python cannot omit `prefix`, so both are required.
- A tuple rest parameter (`...args: [number, string]`) has no single element
  type and becomes `*args: Any` instead of `*args: Sequence[Any]`, which
  rejected the valid call.
- An export of unknown type (`any`, e.g. re-exported from a package without
  declarations) keeps an untyped def instead of disappearing from the stub.
- The stub digest covers the local files the module imports (as copied by the
  compiler) and the app's package.json, so a package upgrade re-reads the
  types; paths are hashed relative to the module, so the header is the same on
  every machine.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
…cused-darwin-dx76ek-js-stubs

# Conflicts:
#	reflex/compiler/utils.py
#	tests/units/compiler/test_compiler_utils.py
…cused-darwin-dx76ek-js-stubs

# Conflicts:
#	tests/units/reflex_base/js/test_modules.py
Comment thread reflex/compiler/utils.py Resolved
Review fixes:

- The stub imports the types it uses under private aliases (`_str`, `_Var`,
  `_Sequence`, ...), so an export named `str`, `Var` or `Sequence` no longer
  replaces the type its annotations name; parameters keep their own names. An
  export named like one of the aliases is left out of the stub. Checked with
  pyright: a stub exporting `str`, `Var` and `any` type-checks, and calls are
  checked against it.
- The stub digest, through module_files, also covers the files a module takes
  types from: `.d.ts` files an import resolves to, JSDoc `import("./types")`
  and `/// <reference path>`. Editing them rewrites the stub.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
An earlier merge left conflict markers, then indented by the formatter, in
compile_script_modules's Returns section; it now describes the three returned
values once. The stub tests that compared only the last line or two of the
rendered stub compare the complete output.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
…de it

Trying `.d.ts` before `.js` when resolving `./helpers` picked helpers.d.ts
whenever both existed, so helpers.js was not copied and a clean frontend build
could not resolve the import. Runtime files resolve as the bundler does again,
and the declaration file that types an import (helpers.d.ts for `./helpers` or
`./helpers.js`, or alone for a types-only import) is tracked beside it, for the
stub digest.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Dropping .d.ts from runtime resolution also dropped the lookup of
types/index.d.ts for `./types`, so editing it left the stub digest unchanged.
The declaration lookup now tries it after types.d.ts.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf

Copy link
Copy Markdown
Contributor Author

The CodSpeed failure on 7c653f1 is not from this change. All three regressions are test_route_matching[10|100|1000] (−4.7% to −6.9%), and CodSpeed itself flags them as having run on different hardware.

  • The commit (git diff 10f0c7bea 7c653f182) touches only reflex_base/js/source.py, the compile-time JS dependency resolver, plus its test. Neither the routing code nor tests/benchmarks/test_routes.py imports it.
  • The previous commit, 10f0c7b, reported no change against the same base.
  • test_route_matching[1000] has swung between about −9% and +10% across today's runs on Import JavaScript modules from Python and call their exports by name #7950 and this PR, each time on mismatched runners.

So this is runner variance. Nothing to fix in the diff; it can be acknowledged on CodSpeed.


Generated by Claude Code

test_js_module_stub failed when another test module had already run an app
named `callscript` in the same process: the harness reloads that package, which
keeps its first directory, so page_script.js and its stub live there, not
under this harness's app_path. The test now takes the module's path from the
imported module, and normalizes the digest in the header, which depends on the
app's package.json (its value is covered by the unit tests), before comparing
the whole stub.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Adapt the stubs to the reworked module API. A stub declares only the names
ScriptSource.functions lists, and names TypeScript reports as types only are
dropped too. module_files is the copy walk again: the files a module reads
types from (declarations beside its imports, type-only imports, JSDoc
import("...") and triple-slash references) are found by type_files, only for
the digest, so a type reference outside the package no longer fails the
compile and type-only files are not copied into .web. The digest hashes the
scripts the copy walk already read.

script-signatures.js now classifies each parameter's type with the checker
into the JSON value Python can send (a small type tree with sorted unions), and
stubs.py only renders it, importing just the aliases a stub uses. Stubs are
written in development only, a stub whose module the app stopped importing is
removed, and failures to read types say what happened and how to fix it.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Read the kind of every import, type-only ones included, through the base's new
walk of template and JSX expressions.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Granian watched .pyi files, so each stub Reflex wrote next to a JavaScript
module restarted the backend once more.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
The Type Stubs section shows what a JSDoc signature becomes, maps each
TypeScript type to its Python type (Any included), says the stubs are written
in development only and recommends committing them, and lists the warnings a
compile can print with their fixes. The news fragments say what changed for
users instead of naming internal files.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
`boolean` is always the union `true | false`, so classify never saw a lone
BooleanLike type. A function re-exported under another name is in the stub,
and a re-exported type is not.

Claude-Session: https://claude.ai/code/session_01LwJUCVxPh3ihrnaFn6CWnf
Comment on lines +115 to +116
const index = checker.getIndexInfoOfType(type, ts.IndexKind.String);
if (index) return { kind: "mapping", value: classify(index.type) };

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Recursive types disable argument checks

A recursive type such as interface Tree { [key: string]: Tree } makes classifyObject call classify on the same type without stopping. The script fails before printing its results, so every stale module gets an untyped stub. Later compiles repeat the failure.

Track types already being visited and use any when a type repeats.

json.dumps([str(handwritten), str(stub_app / "gone.pyi")])
)
_compile_stubs()
assert party_stub.read_text().startswith("# Generated by Reflex from party.js (")

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Test misses unexpected stub output

The new cleanup test checks generated output with startswith, so unexpected declarations after the header still pass. The repository guide requires tests to compare generated output in full.

Before merging, compare the whole stub, deriving or normalizing the digest first.

Context Used: CLAUDE.md (source)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant