diff --git a/cookiecutter/v1/{{ cookiecutter.package_name }}/README.md b/cookiecutter/v1/{{ cookiecutter.package_name }}/README.md
index 77681783..dd2287d2 100644
--- a/cookiecutter/v1/{{ cookiecutter.package_name }}/README.md	
+++ b/cookiecutter/v1/{{ cookiecutter.package_name }}/README.md	
@@ -18,4 +18,25 @@ from {{ cookiecutter.import_name }} import {{ cookiecutter.import_name }}
 value = {{ cookiecutter.import_name }}()
 
 st.write(value)
-```
\ No newline at end of file
+```
+
+## Local development
+
+1. Start Streamlit from the project root:
+
+   ```sh
+   streamlit run {{ cookiecutter.import_name }}/example.py
+   ```
+
+2. In another terminal, run the Vite dev server from `{{ cookiecutter.import_name }}/frontend`:
+
+   ```sh
+   npm install
+   npm run start
+   ```
+
+### Important dev server notes
+
+- The browser connects to the Vite dev server directly. Streamlit does **not** proxy this port, so the Vite port must be reachable from the client just like the Streamlit port.
+- Vite listens on the value of `VITE_PORT` (default `3001`). This variable lives in `{{ cookiecutter.import_name }}/frontend/.env`. Update that file whenever you need to change the port, and remember that Windows/WSL/Hyper-V or dev containers may silently remap addresses like `3001`.
+- If a port is unavailable or blocked by a firewall/mobile connection, set `VITE_PORT=5173` (Vite's default) or any other open port inside the `.env` file before running `npm run start`, and ensure that port is reachable from your browser.
diff --git a/templates/v1/template-reactless/README.md b/templates/v1/template-reactless/README.md
index 758c8241..3bb1f3de 100644
--- a/templates/v1/template-reactless/README.md
+++ b/templates/v1/template-reactless/README.md
@@ -18,4 +18,25 @@ from my_component import my_component
 value = my_component()
 
 st.write(value)
-```
\ No newline at end of file
+```
+
+## Local development
+
+1. Start Streamlit from the project root:
+
+   ```sh
+   streamlit run my_component/example.py
+   ```
+
+2. In another terminal, run the Vite dev server from `my_component/frontend`:
+
+   ```sh
+   npm install
+   npm run start
+   ```
+
+### Important dev server notes
+
+- The browser connects to the Vite dev server directly. Streamlit does **not** proxy this port, so the Vite port must be reachable from the client just like the Streamlit port.
+- Vite listens on the value of `VITE_PORT` (default `3001`). This variable lives in `my_component/frontend/.env`. Update that file whenever you need to change the port, and remember that Windows/WSL/Hyper-V or dev containers may silently remap addresses like `3001`.
+- If a port is unavailable or blocked by a firewall/mobile connection, set `VITE_PORT=5173` (Vite's default) or any other open port inside the `.env` file before running `npm run start`, and ensure that port is reachable from your browser.
diff --git a/templates/v1/template/README.md b/templates/v1/template/README.md
index 758c8241..3bb1f3de 100644
--- a/templates/v1/template/README.md
+++ b/templates/v1/template/README.md
@@ -18,4 +18,25 @@ from my_component import my_component
 value = my_component()
 
 st.write(value)
-```
\ No newline at end of file
+```
+
+## Local development
+
+1. Start Streamlit from the project root:
+
+   ```sh
+   streamlit run my_component/example.py
+   ```
+
+2. In another terminal, run the Vite dev server from `my_component/frontend`:
+
+   ```sh
+   npm install
+   npm run start
+   ```
+
+### Important dev server notes
+
+- The browser connects to the Vite dev server directly. Streamlit does **not** proxy this port, so the Vite port must be reachable from the client just like the Streamlit port.
+- Vite listens on the value of `VITE_PORT` (default `3001`). This variable lives in `my_component/frontend/.env`. Update that file whenever you need to change the port, and remember that Windows/WSL/Hyper-V or dev containers may silently remap addresses like `3001`.
+- If a port is unavailable or blocked by a firewall/mobile connection, set `VITE_PORT=5173` (Vite's default) or any other open port inside the `.env` file before running `npm run start`, and ensure that port is reachable from your browser.