Streamlit Rebase
Developmentstreamlit-rebaseStreamlit Rebase is an Agent Skill for development published in the whitphx/stlite repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Rebase our custom fork of the Streamlit repository onto new upstream Streamlit release
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/whitphx/stlite/blob/HEAD/.claude/skills/rebase-streamlit/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/streamlit-rebase, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Rebase the stlite customization branch onto a new upstream Streamlit release.
-
Navigate to the
/streamlitsubmodule directory -
Fetch the latest tags from upstream:
git fetch upstream --tags -
Infer the current base branch such as
stlite-1.44.0-4. Our project naming convention isstlite-[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" -
Assume
NEW_BASE_STREAMLIT_VERSION_TAGis the tag name of the new upstream release, e.g.,1.45.0.NEW_BASE_STREAMLIT_VERSION_TAG=$ARGUMENTS -
Determine the new stlite customized branch name, e.g.,
stlite-1.45.0.NEW_STLITE_BRANCH=stlite-$ARGUMENTS -
Create the new stlite customization branch from the current one:
git checkout -b $NEW_STLITE_BRANCH $CURRENT_STLITE_BRANCH -
Rebase onto the new upstream tag:
git rebase --onto $NEW_BASE_STREAMLIT_VERSION_TAG $CURRENT_BASE_STREAMLIT_VERSION_TAG $NEW_STLITE_BRANCH -
If conflicts occur:
- Run
git statusto 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 addon resolved files - Continue with
git rebase --continue
- Run
-
Repeat until rebase completes
-
Verify with
git log --onelinethat customization commits are on top of the new tag -
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_BRANCHand$NEW_STLITE_BRANCHshould match the diff between$CURRENT_BASE_STREAMLIT_VERSION_TAGand$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.txtb. The diff between
$NEW_BASE_STREAMLIT_VERSION_TAGand$NEW_STLITE_BRANCHshould match the diff between$CURRENT_BASE_STREAMLIT_VERSION_TAGand$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 emptySummarize 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.
-
After the rebase, update shared dependency versions in
packages/*/package.jsonto matchstreamlit/frontend/*/package.json. For each dependency that appears in both apackages/*/package.jsonand astreamlit/frontend/*/package.json, if the version instreamlit/frontend/*/package.jsonis newer, update the version inpackages/*/package.jsonto match. Note:@vitejs/plugin-reactinpackages/*and@vitejs/plugin-react-swcinstreamlit/frontend/*are different packages — do not align them. After updating, runyarn installto 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 kernelexits non-zero frompackages/react'stsc --noEmit && vite build. - Yarn 4.5.3→4.13.0: streamlit's
.yarnrc.ymlintroduces newer settings (e.g.npmMinimalAgeGate) that older Yarn rejects. Symptom:make kernelfails 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 thoughmake browserexits clean. Symptom: page-loadCalling \require` for "react" in an environment that doesn't expose the `require` function`. Only surfaces in a real browser, not in CI.
Rule of thumb: build-tool deps (
vite,vitest,typescript, the variousvite-plugin-*, and thepackageManagerYarn pin) should match upstream only if the build chain stays green and a manualyarn startinpackages/browser(loaded in a real browser) shows no console errors. Otherwise, leave them at their current versions inpackages/*and leave a top-level"//"comment in the affectedpackage.jsonnoting the pin and the follow-up condition for retrying the bump (seepackages/react/package.jsonfor an example).Runtime/type-shared deps still align unconditionally — anything imported across the package boundary (e.g.
protobufjsbecause we consume@streamlit/protobuf,@types/react,@emotion/*). - 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:
-
Verify the rebase produces a working browser bundle, not just clean builds. CI's
make browseronly 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 startThen 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.