Ship the frontend runtime JavaScript as an installable npm package

Abierto
  • ¿Algo no está bien?
#7,609 1 comentario 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
bun, javascript, python, react, vite
Área
backend, build-system, devtools, frontend

Línea de trabajo

Start by reading the pending-work checklist and the implementation branch claude/reflex-frontend-js-package-ockox9, then compare its install-flow changes with #7235 and #7451. Rebase the branch onto current main, open a PR, and review the breaking-change fragment and local-packages documentation. Done means the PR is ready and the release pipeline confirms the tarball is bundled in a pre-release wheel.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

roadmap

Problem

The JavaScript Reflex ships to every app (state.js, react-theme.js, upload.js, the helpers and components under utils/, style-reset.css, the vite plugins) lives in packages/reflex-base/src/reflex_base/.templates/web/ and is copied verbatim into each app's .web/ directory. That design has several costs:

  • Compiler/runtime drift. Compiled output and the copied runtime are only guaranteed to match by wiping and re-initializing .web on every Reflex version change, which also throws away node_modules and lockfiles.
  • Untestable runtime. The shipped modules import per-app generated artifacts ($/env.json, $/reflex.json, $/utils/context.js), so they cannot be loaded outside a compiled app, let alone unit-tested. state.js importing reflex.json is also one of the two causes of non-reproducible builds in #7562.
  • Dependency versions live in Python. react, react-dom, react-router, socket.io-client, universal-cookie and the build toolchain are maintained as PackageJson.DEPENDENCIES/DEV_DEPENDENCIES constants and pinned at the top level of the app's package.json; the REACT_VERSION/REACT_ROUTER_VERSION env vars are the only override. json5 is used but never declared.
  • Path-coupled imports. Component packages and user custom code reference the runtime through $/utils/... specifiers tied to the .web layout.

Proposal

Ship the non-generated frontend runtime as a real npm package, @reflex-dev/reflex-base, at packages/reflex-base/src/reflex_base/frontend/, bundled inside the reflex-base wheel.

Packaging

  • A stdlib-only hatch build hook packs a deterministic npm-format tarball into the wheel. The release build has no JS toolchain, and byte-stable tarballs keep the file: integrity hashes in committed reflex.lock lockfiles valid across rebuilds. The sdist keeps the JS source so wheels rebuild from it.
  • The package version derives from reflex-base's own version.
  • A verify-frontend-tgz release check asserts the wheel bundles exactly the right tarball and leaks neither source nor node_modules.

Install into .web

  • Each run installs the package like any other dependency (file:./<tarball>). Editable installs of reflex-base link the live source directory instead (link: for bun, file: for npm) so framework JS edits hot-reload without a reinstall.
  • The install flow writes the package entry itself and reconciles it: an unchanged entry keeps the frozen-lockfile install byte-for-byte; a superseded tarball frozen-installs first and is rewritten after; an unresolvable entry is rewritten up front. Legacy top-level framework pins are swept, superseded tarballs pruned, and the install cache keyed on the package version.
  • A Reflex version change no longer wipes .web: needs_reinit() narrows to missing-directory cases and a new refresh_web_directory() overwrite-copies the remaining templates, deletes files owned by older versions and re-renders generated configs, keeping node_modules, lockfiles and the project hash.

Runtime decoupling

  • Shipped modules stop importing generated files. A @reflex-dev/reflex-base/runtime registry is populated by the generated utils/context.js via configureReflexRuntime() in its module body; the two module-scope reads of app config (EVENTURL, the embed-mode locationRef seed) become lazy.
  • ColorModeContext moves into react-theme.js and the generated context re-exports it. Compiled components read env values through getEnv() instead of importing env.json.

Compiler and imports

  • Generated code and component import declarations reference the package by bare specifier (@reflex-dev/reflex-base/state, .../react-theme, .../helpers/*, .../components/*, .../style-reset.css). constants.FrontendPackage is the single Python-side source of these specifiers, with a unit test asserting each resolves to a shipped file.
  • Back-compat for user code is three-layered: merge_imports normalizes legacy $/utils/... specifiers in Python import declarations, the generated vite config aliases them for user JS, and the app root keeps the window.__reflex["$/utils/state"] registry key for backend-evaluated dynamic components. Dirs.STATE_PATH and ResetStylesheet remain as deprecated fallbacks.

Dependencies

  • Runtime framework deps resolve transitively through the package manifest; the app-level toolchain is copied from its devDependencies; shiki and @glideapps/glide-data-grid are optional peer deps deduped to the app root.
  • User version control moves to overrides in reflex.lock/package.json. REACT_VERSION/REACT_ROUTER_VERSION are deprecated (warn now, removed in 1.0). react-helmet is only installed when rx.helmet is used.

Tests

  • Vitest unit tests live inside the package (frontend/tests/) and run as a js-unit-tests CI job; state.js becomes unit-testable for the first time. The JS test tooling itself is tracked in #7611.

Pending work

The implementation lives on branch claude/reflex-frontend-js-package-ockox9 (7 commits, +4775/-348 across 99 files). It was validated end to end with reflex compile and reflex export of a scratch app in source mode, bun and npm installs of the packed tarball, and the wheel in a clean venv. No PR has been opened for it yet.

  • Rebase onto current main: the branch is based on #6919 (late August) and predates later changes to the install flow (for example #7235 and the open #7451).
  • Open the PR; re-check the breaking-change fragment (news/+frontend-npm-package.breaking.md) and the docs/wrapping-react/local-packages.md section describing the file:/link: entry and overrides.
  • Confirm the release pipeline builds the tarball into the wheel (verify-frontend-tgz in scripts/release.py) on an actual pre-release.

Related

  • #7611 JS unit tests for the shipped frontend
  • #7562 / #7564 reproducible production builds
Lenguaje dominante
Python
Estrellas
29k
Forks
1.8k
Merge medio
2 d 22 h
PR fusionados (30 d)
143

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de reflex-dev/reflex

Todos los issues de reflex-dev/reflex

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.