[feat] Add v2 cookiecutter support (#113)

### TL;DR

Added a v2 component template with Cookiecutter support, providing both React and pure TypeScript options for Streamlit component development.

This has the full implementation for the React example, and a stub placeholder for the template without React.

### What changed?

- Created a new v2 component template structure with Cookiecutter integration
- Added support for two frontend frameworks: "React + TypeScript" and "Pure TypeScript"
- Fixed code formatting in existing e2e test files
- Updated template.json with more appropriate default values

Author: sfc-gh-bnisco

cookiecutter/v1/{{ cookiecutter.package_name }}/e2e/test_template.py

@@ -1,14 +1,13 @@
 from pathlib import Path
 
 import pytest
-
-from playwright.sync_api import Page, expect
-
 from e2e_utils import StreamlitRunner
+from playwright.sync_api import Page, expect
 
 ROOT_DIRECTORY = Path(__file__).parent.parent.absolute()
 BASIC_EXAMPLE_FILE = ROOT_DIRECTORY / "my_component" / "example.py"
 
+
 @pytest.fixture(autouse=True, scope="module")
 def streamlit_app():
     with StreamlitRunner(BASIC_EXAMPLE_FILE) as runner:
@@ -23,15 +22,11 @@ def go_to_app(page: Page, streamlit_app: StreamlitRunner):
 
 
 def test_should_render_template(page: Page):
-    frame_0 = page.frame_locator(
-        'iframe[title="my_component\\.my_component"]'
-    ).nth(0)
-    frame_1 = page.frame_locator(
-        'iframe[title="my_component\\.my_component"]'
-    ).nth(1)
+    frame_0 = page.frame_locator('iframe[title="my_component\\.my_component"]').nth(0)
+    frame_1 = page.frame_locator('iframe[title="my_component\\.my_component"]').nth(1)
 
-    st_markdown_0 = page.get_by_role('paragraph').nth(0)
-    st_markdown_1 = page.get_by_role('paragraph').nth(1)
+    st_markdown_0 = page.get_by_role("paragraph").nth(0)
+    st_markdown_1 = page.get_by_role("paragraph").nth(1)
 
     expect(st_markdown_0).to_contain_text("You've clicked 0 times!")
 
@@ -66,7 +61,7 @@ def test_should_change_iframe_height(page: Page):
     locator = page.locator('iframe[title="my_component\\.my_component"]').nth(1)
 
     page.wait_for_timeout(1000)
-    init_frame_height = locator.bounding_box()['height']
+    init_frame_height = locator.bounding_box()["height"]
     assert init_frame_height != 0
 
     page.get_by_label("Enter a name").click()
@@ -77,13 +72,13 @@ def test_should_change_iframe_height(page: Page):
     expect(frame.get_by_text("Streamlit Streamlit Streamlit")).to_be_visible()
 
     page.wait_for_timeout(1000)
-    frame_height = locator.bounding_box()['height']
+    frame_height = locator.bounding_box()["height"]
     assert frame_height > init_frame_height
 
     page.set_viewport_size({"width": 150, "height": 150})
 
     expect(frame.get_by_text("Streamlit Streamlit Streamlit")).not_to_be_in_viewport()
 
     page.wait_for_timeout(1000)
-    frame_height_after_viewport_change = locator.bounding_box()['height']
+    frame_height_after_viewport_change = locator.bounding_box()["height"]
     assert frame_height_after_viewport_change > frame_height

cookiecutter/v2/README.md

@@ -0,0 +1,18 @@
+# Streamlit template for CookieCutter
+
+Template for creating a streamlit component
+
+## Usage
+
+### Run Cookiecutter via uvx
+
+```
+uvx cookiecutter https://github.com/streamlit/component-template.git --directory=cookiecutter/v2
+```
+
+Follow the prompts to generate your project.
+
+More info:
+
+- Cookiecutter: `https://pypi.org/project/cookiecutter/`
+- uv tools: `https://docs.astral.sh/uv/guides/tools/`

cookiecutter/v2/cookiecutter.json

@@ -0,0 +1,20 @@
+{
+  "author_name": "John Smith",
+  "author_email": "[email protected]",
+  "project_name": "Streamlit Component X",
+  "package_name": "{{ cookiecutter.project_name.lower().replace(' ', '-') }}",
+  "import_name": "{{ cookiecutter.package_name.lower().replace('-', '_') }}",
+  "description": "Streamlit component that allows you to do X",
+  "open_source_license": [
+    "MIT license",
+    "BSD license",
+    "ISC license",
+    "Apache Software License 2.0",
+    "GNU General Public License v3",
+    "Not open source"
+  ],
+  "framework": [
+    "React + Typescript",
+    "Pure Typescript"
+  ]
+}

cookiecutter/v2/hooks/post_gen_project.py

@@ -0,0 +1,14 @@
+import shutil
+from pathlib import Path
+
+project_dir = Path("{{ cookiecutter.import_name }}").absolute()
+
+framework = "{{ cookiecutter.framework }}"
+if framework == "React + Typescript":
+    shutil.move(str(project_dir / "frontend-react"), str(project_dir / "frontend"))
+    shutil.rmtree(str(project_dir / "frontend-reactless"))
+elif framework == "Pure Typescript":
+    shutil.move(str(project_dir / "frontend-reactless"), str(project_dir / "frontend"))
+    shutil.rmtree(str(project_dir / "frontend-react"))
+else:
+    raise Exception(f"Unsupported option: {framework!r}")

cookiecutter/v2/{{ cookiecutter.package_name }}/LICENSE

@@ -0,0 +1 @@
+YOUR LICENSE HERE

cookiecutter/v2/{{ cookiecutter.package_name }}/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include {{ cookiecutter.import_name }}/frontend/build *
+include pyproject.toml

cookiecutter/v2/{{ cookiecutter.package_name }}/README.md

@@ -0,0 +1,21 @@
+# {{ cookiecutter.package_name }}
+
+{{ cookiecutter.description }}
+
+## Installation instructions
+
+```sh
+pip install {{ cookiecutter.package_name }}
+```
+
+## Usage instructions
+
+```python
+import streamlit as st
+
+from {{ cookiecutter.import_name }} import {{ cookiecutter.import_name }}
+
+value = {{ cookiecutter.import_name }}()
+
+st.write(value)
+```

cookiecutter/v2/{{ cookiecutter.package_name }}/example.py

@@ -0,0 +1,28 @@
+import streamlit as st
+from {{ cookiecutter.import_name }} import {{ cookiecutter.import_name }}
+
+# Add some test code to play with the component while it's in development.
+# During development, we can run this just as we would any other Streamlit
+# app: `$ streamlit run {{ cookiecutter.import_name }}/example.py`
+
+st.subheader("Component with constant args")
+
+# Create an instance of our component with a constant `name` arg, and
+# print its output value.
+result = {{ cookiecutter.import_name }}("World")
+st.markdown("You've clicked %s times!" % int(result["num_clicks"]))
+
+st.markdown("---")
+st.subheader("Component with variable args")
+
+# Create a second instance of our component whose `name` arg will vary
+# based on a text_input widget.
+#
+# We use the special "key" argument to assign a fixed identity to this
+# component instance. By default, when a component's arguments change,
+# it is considered a new instance and will be re-mounted on the frontend
+# and lose its current state. In this case, we want to vary the component's
+# "name" argument without having it get recreated.
+name_input = st.text_input("Enter a name", value="Streamlit")
+result = {{ cookiecutter.import_name }}(name_input, key="foo")
+st.markdown("You've clicked %s times!" % int(result["num_clicks"]))

cookiecutter/v2/{{ cookiecutter.package_name }}/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "{{ cookiecutter.package_name }}"
+version = "0.0.1"
+description = "{{ cookiecutter.description }}"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "{{ cookiecutter.author_name }}", email = "{{ cookiecutter.author_email }}" },
+]
+# TODO: Restore this
+# dependencies = ["streamlit >= 1.51"]
+
+[project.optional-dependencies]
+devel = [
+  "wheel",
+  "pytest==7.4.0",
+  "playwright==1.48.0",
+  "requests==2.31.0",
+  "pytest-playwright-snapshot==1.0",
+  "pytest-rerunfailures==12.0",
+]
+
+[project.license]
+file = "LICENSE"
+
+[tool.setuptools.packages.find]
+include = ["{{ cookiecutter.import_name }}*"]
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+{{ cookiecutter.import_name }} = ["frontend/build/**/*", "pyproject.toml"]
+
+[[tool.streamlit.component.components]]
+name = "{{ cookiecutter.import_name }}"
+asset_dir = "{{ cookiecutter.import_name }}/frontend/build"

cookiecutter/v2/{{ cookiecutter.package_name }}/{{ cookiecutter.import_name }}/__init__.py

@@ -0,0 +1,62 @@
+from typing import TYPE_CHECKING
+
+import streamlit as st
+
+if TYPE_CHECKING:
+    from streamlit.components.v2.bidi_component import BidiComponentResult
+
+out = st.components.v2.component(
+    "{{ cookiecutter.package_name }}.{{ cookiecutter.import_name }}",
+    js="index-*.js",
+    html='<div class="react-root"></div>',
+)
+
+
+def on_num_clicks_change():
+    """Callback function for when the number of clicks changes in the frontend."""
+    pass
+
+
+# Create a wrapper function for the component.
+#
+# This is an optional best practice. We could simply expose the component
+# function returned by `st.components.v2.component` and call it done.
+#
+# The wrapper allows us to customize our component's API: we can pre-process its
+# input args, post-process its output value, and add a docstring for users.
+def {{ cookiecutter.import_name }}(name, key=None):
+    """Create a new instance of "{{ cookiecutter.import_name }}".
+
+    Parameters
+    ----------
+    name: str
+        The name of the thing we're saying hello to. The component will display
+        the text "Hello, {name}!"
+    key: str or None
+        An optional key that uniquely identifies this component.
+
+    Returns
+    -------
+    int
+        The number of times the component's "Click Me" button has been clicked.
+        (This is the value passed to `Streamlit.setComponentValue` on the
+        frontend.)
+
+    """
+    # Call through to our private component function. Arguments we pass here
+    # will be sent to the frontend, where they'll be available in an "args"
+    # dictionary.
+    #
+    # "default" is a special argument that specifies the initial return
+    # value of the component before the user has interacted with it.
+    component_value = out(
+        name=name,
+        key=key,
+        default={"num_clicks": 0},
+        data={"name": name},
+        on_num_clicks_change=on_num_clicks_change,
+    )
+
+    # We could modify the value returned from the component if we wanted.
+    # There's no need to do this in our simple example - but it's an option.
+    return component_value