RFC: streamlit_folium_vnext — Streamlit Components v2 rewrite

[blackary]

Summary

• Introduces streamlit_folium_vnext, a ground-up rewrite of the Folium integration built on Streamlit Custom Components v2 (CCv2). It lives alongside the existing streamlit_folium package and does not change any existing APIs.
• Zero-flicker map rendering: map instances are cached in JS module scope and re-attached on every rerender without rebuilding the DOM or re-fetching tiles.
• View state (center, zoom, bounds) is emitted immediately on first load — no pan or zoom required.
• Rich click events for map background, markers, circle markers, GeoJSON features, and drawn shapes — each click carries the clicked object's identity and geometry.
• Leaflet.Draw integration with draw.created / draw.edited / draw.deleted events.
• Optional accumulated state API: pass state={"clicks": [], "drawn_features": []} to automatically persist click history and drawn features across reruns via st.session_state, without any manual wiring.
• Multi-map support: each map is independently keyed with no cross-talk.
• A FoliumMap → MapSpec compiler walks the folium layer tree (markers, circle markers, GeoJSON, feature groups, draw plugin, layer control) and produces a JSON spec that the TypeScript/Vite frontend renders via Leaflet.

New structure

streamlit_folium_vnext/
  api.py                  # st_folium_vnext(), st_leaflet(), compile_folium()
  compiler/               # folium → MapSpec compiler
  component/mount.py      # CCv2 component registration
  frontend/src/index.ts   # TypeScript/Vite CCv2 renderer (Leaflet)
  models/                 # MapSpec, MapNode dataclasses

vnext_demo_app/           # 6-page Streamlit demo app
  pages/1_Basic_Map.py
  pages/2_Click_Events.py
  pages/3_Drawing.py
  pages/4_GeoJSON.py
  pages/5_Multiple_Maps.py
  pages/6_Accumulated_State.py

Test plan

• Run pytest tests/test_vnext_package.py tests/test_vnext_e2e.py tests/test_vnext_frontend.py
• Start the demo app: streamlit run vnext_demo_app/Home.py
• Verify no flicker when panning/zooming on Basic Map
• Verify center/zoom/bounds update without requiring interaction
• Verify center/zoom/bounds still show correctly after navigating away and back
• Click a marker → event shows kind: "marker" with tooltip
• Click a circle marker → event shows kind: "circle_marker"
• Click a GeoJSON feature → event shows kind: "geojson" with feature properties
• Draw a shape → draw.created event fires with GeoJSON
• Click a drawn shape → click event fires with kind: "drawn" and the shape's GeoJSON
• Verify accumulated state accumulates clicks and drawn features across reruns
• Verify both Tokyo and London maps on Multiple Maps page work independently

.... Generated with Cortex Code

[randyzwitch]

Is the thought here that we’d maintain parallel versions for a while, before moving to v2 permanently?

[blackary]

@randyzwitch not necessarily, I think it might make sense to either:

• just hard-switch over to a new one with a breaking version release
• release it as a new package

I mostly wanted to do it as a scratch implementation to make it simpler than trying to rewrite piece-by-piece.

[randyzwitch]

@blackary I don't think it makes sense to make it a new package. One thing that the Julia community did when making changes like this was to bundle them into the same major version, adding a deprecation notice. Then, immediately release a major version bump without the old code in it.

That way, people can use the old one while they figure out the new one, then make a major version change to make it permanent.

[blackary]

@randyzwitch @hansthen Here's an (AI-generated, but accurate, I believe) summary of this new POC version of the plugin https://refined-github-html-preview.kidonng.workers.dev/blackary/streamlit-folium/raw/84441d74b650e479fb39984a8cbef1061310775a/docs/plugin-registry-architecture.html

Here's the demo app https://folium-ccv2.streamlit.app/

[hansthen]

@blackary This is amazing work! I really like your compiler idea to render Folium nodes.

Would it make sense though if upstream Folium already provided support for the compilation step? Then Folium itself could be the plugin registry.

I had been toying with a similar idea for Folium itself to solve some quirks in Folium. (But I was not competent or persistent enough to actually get it to work). The issue in Folium is that we cannot dynamically render some elements. E.g. we have separate classes for Popup and for GeoJsonPopup. My intuition is that your compilation idea would also be able to solve that issue.

[hansthen]

There are some other ideas that I would like to steal from you. For instance, your way of generating id's makes much more sense to me than the native method in Folium.

[blackary]

FULL DISCLOSURE -- this code was generated with Cortex Code, Snowflake's coding agent. That did get put in the PR description footer, but wanted to make sure it was clear. :)

I like the idea of Folium being the plugin registry, and handling the compilation -- I just really love that this solution doesn't involve generating and then monkeypatching and then eval-ing the js 😁 So, if we can push the compilation into Folium, that seems great to me.