Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
14e28d3
Type the stubs of imported JavaScript modules from TypeScript and JSDoc
FarhanAliRaza Nov 20, 2026
54ff968
Merge branch 'farhan/focused-darwin-dx76ek-js-modules' into farhan/fo…
FarhanAliRaza Nov 20, 2026
478796a
Stub review fixes: name collisions, trailing defaults, untyped export…
FarhanAliRaza Nov 20, 2026
3b74ea7
Merge branch 'farhan/focused-darwin-dx76ek-js-modules' into farhan/fo…
FarhanAliRaza Nov 20, 2026
cc8f1b0
Merge branch 'farhan/focused-darwin-dx76ek-js-modules' into farhan/fo…
FarhanAliRaza Nov 20, 2026
209f572
Merge branch 'farhan/focused-darwin-dx76ek-js-modules' into farhan/fo…
FarhanAliRaza Nov 20, 2026
709b8b1
Merge branch 'farhan/focused-darwin-dx76ek-js-modules' into farhan/fo…
FarhanAliRaza Nov 20, 2026
770af5e
Alias the stub's type names; key stubs on the types a module reads
FarhanAliRaza Nov 20, 2026
1e6faf7
Remove merge markers from a docstring; compare whole stubs in tests
FarhanAliRaza Nov 20, 2026
10f0c7b
Resolve the runtime file of an import, and track its declaration besi…
FarhanAliRaza Nov 20, 2026
7c653f1
Track a directory's index.d.ts for a types-only import
FarhanAliRaza Nov 20, 2026
7a8bad9
Find the generated stub next to the module Python imported
FarhanAliRaza Nov 20, 2026
87e5006
Merge farhan/focused-darwin-dx76ek-js-modules into the stubs branch
FarhanAliRaza Nov 21, 2026
cc0cb90
Merge farhan/focused-darwin-dx76ek-js-modules into the stubs branch
FarhanAliRaza Nov 21, 2026
6c55085
Do not reload the backend when a type stub is written
FarhanAliRaza Nov 21, 2026
d36ac6f
Document the typed stubs usage-first, with every warning
FarhanAliRaza Nov 21, 2026
3afdcd0
Test that a production compile writes no stub and installs no typescript
FarhanAliRaza Nov 21, 2026
789a235
Tidy the stub compile loop; name the signatures script in the README
FarhanAliRaza Nov 21, 2026
dd9f006
Format the signatures fixture as biome does
FarhanAliRaza Nov 21, 2026
f7f7b9e
Use the parameters of the JSDoc fixture, which biome flagged as unused
FarhanAliRaza Nov 21, 2026
902693f
Cover re-exported names in the signatures fixture; drop a dead branch
FarhanAliRaza Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 86 additions & 2 deletions docs/api-reference/browser_javascript.md
Original file line number Diff line number Diff line change
Expand Up @@ -360,8 +360,81 @@ Apps whose Content Security Policy forbids `unsafe-eval` can use them.
- In a `.jsx` or `.tsx` file, JSX is read as JSX. In a `.js` or `.ts` file,
`<` is never JSX, so a quote in what would be JSX text hides the code after
it on that line.
- Reflex writes a type stub (`party.pyi`) next to the module when it compiles
the app, so type checkers resolve the import.

### Type Stubs

While you develop, Reflex writes a type stub next to each module the app
imports, `party.pyi` beside `party.js`, so type checkers resolve the import and
check each call. Argument types come from TypeScript annotations or, in a `.js`
file, JSDoc:

```javascript
// my_app/scripts/party.js
/**
* @param {number} count
* @param {string} elementId
* @param {"left" | "right"} [side]
*/
export function celebrate(count, elementId, side) { /* ... */ }
```

gives this stub, shown without its imports and with each private alias, such
as `_float`, as the name it stands for:

```python
# my_app/scripts/party.pyi
def celebrate(
count: float | Var[float],
elementId: str | Var[str] | EventCallback[*tuple[Any, ...]],
side: Literal["left", "right"] | Var[Literal["left", "right"]] = ...,
/,
) -> EventSpec: ...
```

so `celebrate("lots", "results")` is a type error. Arguments are positional,
as JavaScript passes them, and each also takes a var. A function reads its
arguments as JSON, so each type becomes the type of the JSON value Python sends:

| TypeScript or JSDoc | Python |
| --- | --- |
| `string` | `str`, or an event handler, sent as its name |
| `number` | `float` |
| `boolean` | `bool` |
| `null`, `undefined`, `void` | `None` |
| `"a" \| "b"`, `1 \| 2`, `true` | `Literal["a", "b"]`, `Literal[1, 2]`, `Literal[True]` |
| an enum | `Literal` of its values |
| `T[]`, `[T, U]` | `Sequence[T]`, `Sequence[T \| U]` |
| `Record<string, T>`, `{ [key: string]: T }` | `Mapping[str, T]` |
| an object type or interface of your own | `Mapping[str, Any]` |
| `A \| B` | the union of their types, `Any` if either is `Any` |
| no type, `any`, `unknown`, `object`, `bigint`, `A & B`, a type parameter | `Any` |
| a function, a class, `Date`, `Map`, `Set`, `Promise`, `HTMLElement` and other types of the browser or an npm package | `Any` |
| `x?: T`, or a default value | `x: T = ...`, when no required parameter follows |
| `...rest: T[]` | `*rest: T` |

An overloaded function gets one `@overload` per signature. An export
TypeScript knows is only a type, such as `export interface Options`, or is not
a function, is left out of the stub.

- Commit the stubs, so your editor and type checks in CI see them without
running the app. A stub only changes when the types do: Reflex rewrites it
when the module, a file it imports or reads types from (a `.d.ts` file,
`import type`, a JSDoc `import("./types")`), the app's frontend packages or
Reflex's stub generator changes. Writing a stub does not reload the backend.
- Stubs are written only in development. `reflex export` and `reflex run --env
prod` leave your source tree alone.
- When the app stops importing a module, Reflex removes the stub it wrote for
it. It never removes a `.pyi` file it did not write.
- Reflex reads the types with TypeScript, which it installs with the app's
frontend packages, run by Node.js or, without it, Bun.
- Pyright reports a stub that has no Python module beside it as
`reportMissingModuleSource`. Turn that rule off:

```toml
# pyproject.toml
[tool.pyright]
reportMissingModuleSource = "none"
```

### Errors

Expand All @@ -384,6 +457,17 @@ Apps whose Content Security Policy forbids `unsafe-eval` can use them.
not export a function of that name, or the frontend was built before the
backend imported it. Export the function, or restart `reflex run` to rebuild
the frontend.
- `Reflex could not read the argument types of the JavaScript modules
.../party.js, so their type stubs accept any arguments: reading them needs
Node.js or Bun, and neither was found.` The app still runs, but type
checkers accept any arguments. Install Node.js 22.22.0 or newer, then run
the app again.
- `Reflex could not read the argument types of the JavaScript modules
.../party.js, so their type stubs accept any arguments: script-signatures.js
failed: ...` The error after `failed:` says why. Reflex retries on the next
compile; if it keeps failing, delete `.web/node_modules` so the next run
reinstalls TypeScript, or report the error at
https://github.com/reflex-dev/reflex/issues.

## Using React Hooks

Expand Down
1 change: 1 addition & 0 deletions news/+js-module-stubs.feature.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
While you develop, the type stub Reflex writes next to an imported JavaScript module types each function's arguments from its TypeScript annotations or JSDoc, so type checkers catch a wrong argument in Python, such as `celebrate("lots")` for `@param {number} count`. Production builds leave the source tree alone, and writing a stub does not reload the backend; see [Type Stubs](https://reflex.dev/docs/api-reference/browser-javascript/#type-stubs).
1 change: 1 addition & 0 deletions packages/reflex-base/news/+js-module-stubs.feature.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
The type stub written next to a JavaScript module imported from Python types each function's arguments from TypeScript annotations or JSDoc, as the JSON value Python sends (`number` is `float`, `"a" | "b"` is `Literal["a", "b"]`, a `Map` or `HTMLElement` is `Any`), and declares only the functions the module exports at runtime.
3 changes: 3 additions & 0 deletions packages/reflex-base/src/reflex_base/constants/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,9 @@ class Dirs(SimpleNamespace):
SCRIPTS_PATH = UTILS + "/scripts"
# The directory those modules are copied to.
SCRIPT_MODULES_PATH = UTILS + "/script_modules"
# The type stubs written next to those modules in development, so the next
# compile removes the stub of a module the app no longer imports.
SCRIPT_STUBS = "script_stubs.json"
# The name of the output directory.
BUILD_DIR = "build"
# The name of the static files directory.
Expand Down
29 changes: 0 additions & 29 deletions packages/reflex-base/src/reflex_base/js/modules.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@
import dataclasses
import functools
import inspect
import keyword
from pathlib import Path
from types import ModuleType
from typing import Any, NoReturn
Expand Down Expand Up @@ -203,31 +202,3 @@ def _load_module(module: ModuleType, path: Path) -> None:
"__getattr__",
functools.partial(_missing_export, module.__name__, path, script),
)


def _render_stub(path: Path, functions: list[str]) -> str:
"""Render a type stub for a JavaScript module, so type checkers see it.

Exports that are not Python identifiers cannot be imported and are left
out. The arguments are untyped.

Args:
path: The JavaScript file.
functions: Its exported functions.

Returns:
The ``.pyi`` source.
"""
lines = [
f"# Generated by Reflex from {path.name}; rewritten when it changes.",
"from typing import Any",
"",
"from reflex_base.event import EventSpec",
"",
]
lines.extend(
f"def {name}(*args: Any) -> EventSpec: ..."
for name in functions
if name.isidentifier() and not keyword.iskeyword(name)
)
return "\n".join(lines) + "\n"
125 changes: 106 additions & 19 deletions packages/reflex-base/src/reflex_base/js/source.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

import dataclasses
import re
from collections.abc import Iterator, Sequence
from collections.abc import Iterator, Mapping, Sequence
from pathlib import Path

# Files whose imports are followed; other local files (CSS, JSON) are copied.
Expand All @@ -22,11 +22,18 @@
STYLESHEET_EXTENSION = ".css"
# Tried in order for an import without an extension, as the bundler does.
_RESOLVE_EXTENSIONS = (".ts", ".tsx", ".js", ".jsx", ".mjs")
# The extension of the declaration file that types a runtime file.
_DECLARATION_EXTENSION = ".d.ts"

_CSS_COMMENT_RE = re.compile(r"/\*.*?\*/", re.DOTALL)
_CSS_REFERENCE_RE = re.compile(
r"""@import\s+(?:url\(\s*)?["']?([^"')\s;]+)|url\(\s*["']?([^"')\s]+)["']?\s*\)"""
)
# The files a module reads types from in comments, which no tokenizer sees:
# JSDoc `import("./types")` and `/// <reference path="types.d.ts" />`.
_TYPE_REFERENCE_RE = re.compile(
r"""\bimport\(\s*["'](\.[^"']+)["']\s*\)|///\s*<reference\s+path=["']([^"']+)["']"""
)
# Whitespace and comments; an unterminated block comment runs to the end.
_SPACE_RE = re.compile(r"(?:\s+|//[^\n]*|/\*.*?(?:\*/|\Z))*", re.DOTALL)
# Identifiers, keywords and numbers.
Expand Down Expand Up @@ -95,6 +102,10 @@ class ScriptSource:
values: list[str]
# The specifiers it imports from, without TypeScript's type-only imports.
imports: list[str]
# The local files it reads only types from, relative to it: those of its
# type-only imports, and of JSDoc `import("./types")` and triple-slash
# references in comments.
type_imports: list[str]


def _read_string(source: str, start: int) -> tuple[str, int]:
Expand Down Expand Up @@ -680,51 +691,52 @@ def _statement_start(tokens: Sequence[Token], index: int) -> int:
return index


def _is_runtime_import(tokens: Sequence[Token], index: int) -> bool:
"""Whether a string is the specifier of a module the source loads.

Covers ``import ... from "x"``, ``import "x"``, ``import("x")`` and
``export ... from "x"``, but not TypeScript's ``import type`` and
``export type``, which load nothing.
def _import_kind(tokens: Sequence[Token], index: int) -> str | None:
"""Tell whether a string is the specifier of an import, and of which kind.

Args:
tokens: The tokens.
index: The index of the string.

Returns:
Whether it is such a specifier.
"runtime" for a module the source loads: ``import ... from "x"``,
``import "x"``, ``import("x")`` and ``export ... from "x"``; "type" for
TypeScript's ``import type`` and ``export type``, which load nothing
but types; None for any other string.
"""
if _is(_at(tokens, index - 1), "punct", "("):
return _is_keyword(tokens, index - 2, "import")
return "runtime" if _is_keyword(tokens, index - 2, "import") else None
if _is_keyword(tokens, index - 1, "import"):
return True
return "runtime"
if not _is(_at(tokens, index - 1), "name", "from"):
return False
return None
start = _statement_start(tokens, index - 2)
# `import type X from` loads nothing, but `import type from` and
# `import type, { x } from` import a default export named type.
after = _at(tokens, start + 2)
return not (
type_only = (
_is(tokens[start + 1], "name", "type")
and not _is(after, "name", "from")
and not _is(after, "punct", ",")
)
return "type" if type_only else "runtime"


def _runtime_imports(tokens: Sequence[Token]) -> Iterator[str]:
"""Yield the specifiers of the modules some tokens load.
def _imports(tokens: Sequence[Token]) -> Iterator[tuple[str, str]]:
"""Yield the specifiers some tokens import from, with their kind.

Args:
tokens: The tokens, which may hold templates and JSX with expressions.

Yields:
Each specifier, including those inside a template's or JSX's expressions.
Each specifier's ``_import_kind`` and the specifier, including those
inside a template's or JSX's expressions.
"""
for index, token in enumerate(tokens):
if token.kind == "string" and _is_runtime_import(tokens, index):
yield token.value
if token.kind == "string" and (kind := _import_kind(tokens, index)):
yield kind, token.value
elif token.inner:
yield from _runtime_imports(token.inner)
yield from _imports(token.inner)


def parse_script(text: str, jsx: bool = False) -> ScriptSource:
Expand All @@ -749,12 +761,24 @@ def parse_script(text: str, jsx: bool = False) -> ScriptSource:
if _is_keyword(tokens, index, "export"):
for name, callable_ in _export_names(tokens, index + 1):
exports.setdefault(name, callable_)
imports: dict[str, None] = {}
type_imports: dict[str, None] = {}
for kind, specifier in _imports(tokens):
if kind == "runtime":
imports[specifier] = None
elif specifier.startswith("."):
type_imports[specifier] = None
for jsdoc, reference in _TYPE_REFERENCE_RE.findall(text):
type_imports[jsdoc or reference] = None
exports.pop("default", None)
return ScriptSource(
text=text,
functions=[name for name, callable_ in exports.items() if callable_],
values=[name for name, callable_ in exports.items() if not callable_],
imports=list(dict.fromkeys(_runtime_imports(tokens))),
imports=list(imports),
type_imports=[
specifier for specifier in type_imports if specifier not in imports
],
)


Expand Down Expand Up @@ -889,3 +913,66 @@ def module_files(path: Path) -> dict[Path, ScriptSource | None]:
files[target] = None
pending.append(target)
return files


def _resolve_declaration(directory: Path, specifier: str) -> Path | None:
"""Find the declaration file TypeScript types a relative import with.

That is ``helpers.d.ts`` for ``./helpers`` and ``./helpers.js`` alike, or
``types/index.d.ts`` for a directory ``./types``.

Args:
directory: The importing file's directory.
specifier: The relative specifier.

Returns:
The declaration file, or None if there is none.
"""
target = directory / strip_query(specifier)
stem = target.with_suffix("") if target.suffix in _RESOLVE_EXTENSIONS else target
candidates = (
stem.with_name(stem.name + _DECLARATION_EXTENSION),
target / f"index{_DECLARATION_EXTENSION}",
)
return next((candidate for candidate in candidates if candidate.is_file()), None)


def type_files(files: Mapping[Path, ScriptSource | None]) -> dict[Path, ScriptSource]:
"""Find the files a module reads types from that the bundler never loads.

These are the declaration files beside the files it imports and the files
its type-only imports, JSDoc ``import("./types")`` and triple-slash
references name, directly or not. They change the module's types, but are
not copied into the compiled app.

Args:
files: The module's files, from ``module_files``.

Returns:
The resolved files not among ``files``, each with its script.
"""
found: dict[Path, ScriptSource] = {}
pending = [(file, script) for file, script in files.items() if script is not None]
while pending:
file, script = pending.pop()
specifiers = [
*(specifier for specifier in script.imports if specifier.startswith(".")),
*script.type_imports,
]
for specifier in specifiers:
for target in (
_resolve_local(file.parent, specifier),
_resolve_declaration(file.parent, specifier),
):
if target is None:
continue
target = target.resolve()
if (
target in files
or target in found
or target.suffix not in SCRIPT_SOURCE_EXTENSIONS
):
continue
found[target] = read_script(target)
pending.append((target, found[target]))
return found
Loading