Streamlit Rebase

Rebase the stlite customization branch onto a new upstream Streamlit release.

1. Navigate to the /streamlit submodule directory

2. Fetch the latest tags from upstream:

   git fetch upstream --tags

3. Infer the current base branch such as stlite-1.44.0-4. Our project naming convention is stlite-[upstream-version](-[customization-version])?. Use this to determine the previous upstream version tag, and ask me to confirm it before proceeding. The base Streamlit version tag can be inferred from the current branch name as well.

   CURRENT_STLITE_BRANCH="INFERRED_BRANCH_NAME_HERE"
   CURRENT_BASE_STREAMLIT_VERSION_TAG="INFERRED_TAG_NAME_HERE"

4. Assume NEW_BASE_STREAMLIT_VERSION_TAG is the tag name of the new upstream release, e.g., 1.45.0.

   NEW_BASE_STREAMLIT_VERSION_TAG=$ARGUMENTS

5. Determine the new stlite customized branch name, e.g., stlite-1.45.0.

   NEW_STLITE_BRANCH=stlite-$ARGUMENTS

6. Create the new stlite customization branch from the current one:

   git checkout -b $NEW_STLITE_BRANCH $CURRENT_STLITE_BRANCH

7. Rebase onto the new upstream tag:

   git rebase --onto $NEW_BASE_STREAMLIT_VERSION_TAG $CURRENT_BASE_STREAMLIT_VERSION_TAG $NEW_STLITE_BRANCH

8. If conflicts occur:

   • Run git status to identify conflicting files
   • Read each conflicting file to understand both versions
   • Resolve conflicts by preserving stlite customizations while incorporating upstream changes
     • If the conflict is so large, ask the developer for review and help
   • Run git add on resolved files
   • Continue with git rebase --continue

9. Repeat until rebase completes

10. Verify with git log --oneline that customization commits are on top of the new tag

11. Self double-check the rebase with two diff comparisons. Both should match except for trivially explainable differences (e.g., files the stlite customization deletes, conflict-resolution overhead in files you manually merged):

    a. The diff between $CURRENT_STLITE_BRANCH and $NEW_STLITE_BRANCH should match the diff between $CURRENT_BASE_STREAMLIT_VERSION_TAG and $NEW_BASE_STREAMLIT_VERSION_TAG (upstream delta preserved):

    git diff $CURRENT_STLITE_BRANCH..$NEW_STLITE_BRANCH --stat > /tmp/stlite-delta.txt
    git diff $CURRENT_BASE_STREAMLIT_VERSION_TAG..$NEW_BASE_STREAMLIT_VERSION_TAG --stat > /tmp/upstream-delta.txt
    diff /tmp/stlite-delta.txt /tmp/upstream-delta.txt

    b. The diff between $NEW_BASE_STREAMLIT_VERSION_TAG and $NEW_STLITE_BRANCH should match the diff between $CURRENT_BASE_STREAMLIT_VERSION_TAG and $CURRENT_STLITE_BRANCH (customization delta preserved). In particular, the set of customized files should be identical:

    git diff $NEW_BASE_STREAMLIT_VERSION_TAG..$NEW_STLITE_BRANCH --name-only | sort > /tmp/files-new.txt
    git diff $CURRENT_BASE_STREAMLIT_VERSION_TAG..$CURRENT_STLITE_BRANCH --name-only | sort > /tmp/files-old.txt
    diff /tmp/files-old.txt /tmp/files-new.txt  # should be empty

    Summarize any differences (what file, how many lines, and why it's expected) and show the summary to the user so they can confirm the rebase is clean.

12. After the rebase, update shared dependency versions in packages/*/package.json to match streamlit/frontend/*/package.json. For each dependency that appears in both a packages/*/package.json and a streamlit/frontend/*/package.json, if the version in streamlit/frontend/*/package.json is newer, update the version in packages/*/package.json to match. Note: @vitejs/plugin-react in packages/* and @vitejs/plugin-react-swc in streamlit/frontend/* are different packages — do not align them. After updating, run yarn install to regenerate the lockfile.

    Alignment policy: follow upstream as long as it works. The dep alignment is best-effort, not strict. Most of stlite's packages have their own build pipelines and don't share a module graph with upstream, so build-tool bumps in particular are landing into different blast radii than upstream's CI saw. Past rebases hit three regressions because of blanket alignment:

    • TypeScript 5→6: stricter narrowing surfaces type errors in upstream frontend code that upstream's CI doesn't catch (their build is vite-only, no tsc gate). Symptom: make kernel exits non-zero from packages/react's tsc --noEmit && vite build.
    • Yarn 4.5.3→4.13.0: streamlit's .yarnrc.yml introduces newer settings (e.g. npmMinimalAgeGate) that older Yarn rejects. Symptom: make kernel fails before any TS compiles, on workspace install.
    • Vite 7→8: Rolldown handles CJS deps differently from Rollup + @rollup/plugin-commonjs, breaking @stlite/react's bundle in the browser even though make browser exits clean. Symptom: page-load Calling \require` for "react" in an environment that doesn't expose the `require` function`. Only surfaces in a real browser, not in CI.

    A second, separate failure mode comes from stlite deleting streamlit/frontend/yarn.lock so the fork joins the parent workspace: every dependency of streamlit/frontend/* is then resolved fresh, landing on newer patch releases than the ones upstream's own lockfile pins and tests. Nothing in packages/* has to change for this to bite. Symptom: a build or typecheck failure inside streamlit/frontend that does not reproduce on the upstream tag. Which repair applies depends on what the newer release broke:

    • The fork's own source no longer satisfies it. A newer TypeScript rejected two @ts-expect-error directives that a newer @microlink/react-json-view had made unused. Fix these in the fork, as a patch on the stlite-<version> branch; a pin would only defer the same edit to the next rebase.
    • A prebuilt artifact no longer loads under it. A newer Vite carried a rolldown whose swc_core refused the @swc/plugin-emotion wasm plugin upstream declares. There is nothing to edit here, so pin the package with a resolutions entry in the root package.json and record the reason under the "//resolutions" key. Run yarn install before retrying the build; the entry does not reach the dependency graph until the lockfile is regenerated.

    Rule of thumb: build-tool deps (vite, vitest, typescript, the various vite-plugin-*, and the packageManager Yarn pin) should match upstream only if the build chain stays green and a manual yarn start in packages/browser (loaded in a real browser) shows no console errors. Otherwise, leave them at their current versions in packages/* and leave a top-level "//" comment in the affected package.json noting the pin and the follow-up condition for retrying the bump (see packages/react/package.json for an example).

    Runtime/type-shared deps still align unconditionally — anything imported across the package boundary (e.g. protobufjs because we consume @streamlit/protobuf, @types/react, @emotion/*).

13. Verify the rebase produces a working browser bundle, not just clean builds. CI's make browser only compiles — it doesn't execute. After the dep alignment in step 12 (especially after any vite, plugin-react, or @emotion bump), run:

    yarn workspace @stlite/browser start

    Then load http://localhost:3001/demos/basic-mount/ in a real browser (or via Playwright MCP) and confirm:

    • Zero console errors after the demo finishes loading
    • The Streamlit script actually renders (e.g. st.write("Hello") shows)

    If errors surface, narrow the dep bump that caused it and either pin that one dep back or update the alignment skip-list above.

14. When opening the stlite PR, link the submodule diff from the description, so a reviewer can read the fork's customizations against the new upstream release without cloning the submodule. Compare across forks, with the upstream release tag as the base: that tag lives in streamlit/streamlit and is not pushed to whitphx/streamlit, so a same-repo compare cannot name it.

    https://github.com/streamlit/streamlit/compare/$NEW_BASE_STREAMLIT_VERSION_TAG...whitphx:streamlit:$NEW_STLITE_BRANCH

    Open the link before submitting and confirm it shows only the customization commits. The head side names a branch, and stlite-<version> stays force-pushable until its release, so re-check the link after any force-push: the branch tip has to keep matching the SHA the submodule is pinned to (git ls-tree HEAD streamlit) or the reviewer is reading a diff this PR does not merge.