Skip to content

Commit aa33aaf

Browse files
ArchmongerArchmonger
committed
Merge remote-tracking branch 'origin/main' into new-docs
2 parents d4f9252 + 4b765d4 commit aa33aaf

1 file changed

Lines changed: 391 additions & 0 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 391 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,391 @@
1+
# ReactPy Development Instructions
2+
3+
ReactPy is a Python library for building user interfaces without JavaScript. It creates React-like components that render to web pages using a Python-to-JavaScript bridge.
4+
5+
Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
6+
7+
**IMPORTANT**: This package uses modern Python tooling with Hatch for all development workflows. Always use Hatch commands for development tasks.
8+
9+
**BUG INVESTIGATION**: When investigating whether a bug was already resolved in a previous version, always prioritize searching through `docs/source/about/changelog.rst` first before using Git history. Only search through Git history when no relevant changelog entries are found.
10+
11+
## Working Effectively
12+
13+
### Bootstrap, Build, and Test the Repository
14+
15+
**Prerequisites:**
16+
17+
- Install Python 3.9+ from https://www.python.org/downloads/
18+
- Install Hatch: `pip install hatch`
19+
- Install Bun JavaScript runtime: `curl -fsSL https://bun.sh/install | bash && source ~/.bashrc`
20+
- Install Git
21+
22+
**Initial Setup:**
23+
24+
```bash
25+
git clone https://github.com/reactive-python/reactpy.git
26+
cd reactpy
27+
```
28+
29+
**Install Dependencies for Development:**
30+
31+
```bash
32+
# Install core ReactPy dependencies
33+
pip install fastjsonschema requests lxml anyio typing-extensions
34+
35+
# Install ASGI dependencies for server functionality
36+
pip install orjson asgiref asgi-tools servestatic uvicorn fastapi
37+
38+
# Optional: Install additional servers
39+
pip install flask sanic tornado
40+
```
41+
42+
**Build JavaScript Packages:**
43+
44+
- `hatch run javascript:build` -- takes 15 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
45+
- This builds two packages: @reactpy/client, and @reactpy/app
46+
47+
**Build Python Package:**
48+
49+
- `hatch build --clean` -- takes 10 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
50+
51+
**Run Python Tests:**
52+
53+
- `hatch test --parallel` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 2 minutes for full test suite. **All tests must always pass - failures are never expected or allowed.**
54+
- `hatch test --parallel --cover` -- run tests with coverage reporting (used in CI)
55+
- `hatch test --parallel -k test_name` -- run specific tests
56+
- `hatch test --parallel tests/test_config.py` -- run specific test files
57+
58+
**Run Python Linting and Formatting:**
59+
60+
- `hatch fmt` -- Run all linters and formatters (~1 second)
61+
- `hatch fmt --check` -- Check formatting without making changes (~1 second)
62+
- `hatch fmt --linter` -- Run only linters
63+
- `hatch fmt --formatter` -- Run only formatters
64+
- `hatch run python:type_check` -- Run Python type checker (~10 seconds)
65+
66+
**Run JavaScript Tasks:**
67+
68+
- `hatch run javascript:check` -- Lint and type-check JavaScript (10 seconds). NEVER CANCEL. Set timeout to 30+ minutes.
69+
- `hatch run javascript:fix` -- Format JavaScript code
70+
- `hatch run javascript:test` -- Run JavaScript tests
71+
72+
**Interactive Development Shell:**
73+
74+
- `hatch shell` -- Enter an interactive shell environment with all dependencies installed
75+
- `hatch shell default` -- Enter the default development environment
76+
- Use the shell for interactive debugging and development tasks
77+
78+
## Validation
79+
80+
Always manually validate any new code changes through these steps:
81+
82+
**Basic Functionality Test:**
83+
84+
```python
85+
# Add src to path if not installed
86+
import sys, os
87+
sys.path.insert(0, os.path.join("/path/to/reactpy", "src"))
88+
89+
# Test that imports and basic components work
90+
import reactpy
91+
from reactpy import component, html, use_state
92+
93+
@component
94+
def test_component():
95+
return html.div([
96+
html.h1("Test"),
97+
html.p("ReactPy is working")
98+
])
99+
100+
# Verify component renders
101+
vdom = test_component()
102+
print(f"Component rendered: {type(vdom)}")
103+
```
104+
105+
**Server Functionality Test:**
106+
107+
```python
108+
# Test ASGI server creation (most common deployment)
109+
from reactpy import component, html
110+
from reactpy.executors.asgi.standalone import ReactPy
111+
import uvicorn
112+
113+
@component
114+
def hello_world():
115+
return html.div([
116+
html.h1("Hello, ReactPy!"),
117+
html.p("Server is working!")
118+
])
119+
120+
# Create ASGI app (don't run to avoid hanging)
121+
app = ReactPy(hello_world)
122+
print("✓ ASGI server created successfully")
123+
124+
# To actually run: uvicorn.run(app, host="127.0.0.1", port=8000)
125+
```
126+
127+
**Hooks and State Test:**
128+
129+
```python
130+
from reactpy import component, html, use_state
131+
132+
@component
133+
def counter_component(initial=0):
134+
count, set_count = use_state(initial)
135+
136+
return html.div([
137+
html.h1(f"Count: {count}"),
138+
html.button({
139+
"onClick": lambda event: set_count(count + 1)
140+
}, "Increment")
141+
])
142+
143+
# Test component with hooks
144+
counter = counter_component(5)
145+
print(f"✓ Hook-based component: {type(counter)}")
146+
```
147+
148+
**Always run these validation steps before completing work:**
149+
150+
- `hatch fmt --check` -- Ensure code is properly formatted (never expected to fail)
151+
- `hatch run python:type_check` -- Ensure no type errors (never expected to fail)
152+
- `hatch run javascript:check` -- Ensure JavaScript passes linting (never expected to fail)
153+
- Test basic component creation and rendering as shown above
154+
- Test server creation if working on server-related features
155+
- Run relevant tests with `hatch test --parallel` -- **All tests must always pass - failures are never expected or allowed**
156+
157+
**Integration Testing:**
158+
159+
- ReactPy can be deployed with FastAPI, Flask, Sanic, Tornado via ASGI
160+
- For browser testing, Playwright is used but requires additional setup
161+
- Test component VDOM rendering directly when browser testing isn't available
162+
- Validate that JavaScript builds are included in Python package after changes
163+
164+
## Repository Structure and Navigation
165+
166+
### Key Directories:
167+
168+
- `src/reactpy/` -- Main Python package source code
169+
- `core/` -- Core ReactPy functionality (components, hooks, VDOM)
170+
- `web/` -- Web module management and exports
171+
- `executors/` -- Server integration modules (ASGI, etc.)
172+
- `testing/` -- Testing utilities and fixtures
173+
- `pyscript/` -- PyScript integration
174+
- `static/` -- Bundled JavaScript files
175+
- `_html.py` -- HTML element factory functions
176+
- `src/js/` -- JavaScript packages that get bundled with Python
177+
- `packages/@reactpy/client/` -- Client-side React integration
178+
- `packages/@reactpy/app/` -- Application framework
179+
- `src/build_scripts/` -- Build automation scripts
180+
- `tests/` -- Python test suite with comprehensive coverage
181+
- `docs/` -- Documentation source (MkDocs-based, transitioning setup)
182+
183+
### Important Files:
184+
185+
- `pyproject.toml` -- Python project configuration and Hatch environments
186+
- `src/js/package.json` -- JavaScript development dependencies
187+
- `tests/conftest.py` -- Test configuration and fixtures
188+
- `docs/source/about/changelog.rst` -- Version history and changes
189+
- `.github/workflows/check.yml` -- CI/CD pipeline configuration
190+
191+
## Common Tasks
192+
193+
### Build Time Expectations:
194+
195+
- JavaScript build: 15 seconds
196+
- Python package build: 10 seconds
197+
- Python linting: 1 second
198+
- JavaScript linting: 10 seconds
199+
- Type checking: 10 seconds
200+
- Full CI pipeline: 5-10 minutes
201+
202+
### Running ReactPy Applications:
203+
204+
**ASGI Standalone (Recommended):**
205+
206+
```python
207+
from reactpy import component, html
208+
from reactpy.executors.asgi.standalone import ReactPy
209+
import uvicorn
210+
211+
@component
212+
def my_app():
213+
return html.h1("Hello World")
214+
215+
app = ReactPy(my_app)
216+
uvicorn.run(app, host="127.0.0.1", port=8000)
217+
```
218+
219+
**With FastAPI:**
220+
221+
```python
222+
from fastapi import FastAPI
223+
from reactpy import component, html
224+
from reactpy.executors.asgi.middleware import ReactPyMiddleware
225+
226+
@component
227+
def my_component():
228+
return html.h1("Hello from ReactPy!")
229+
230+
app = FastAPI()
231+
app.add_middleware(ReactPyMiddleware, component=my_component)
232+
```
233+
234+
### Creating Components:
235+
236+
```python
237+
from reactpy import component, html, use_state
238+
239+
@component
240+
def my_component(initial_value=0):
241+
count, set_count = use_state(initial_value)
242+
243+
return html.div([
244+
html.h1(f"Count: {count}"),
245+
html.button({
246+
"onClick": lambda event: set_count(count + 1)
247+
}, "Increment")
248+
])
249+
```
250+
251+
### Working with JavaScript:
252+
253+
- JavaScript packages are in `src/js/packages/`
254+
- Two main packages: @reactpy/client, @reactpy/app
255+
- Built JavaScript gets bundled into `src/reactpy/static/`
256+
- Always rebuild JavaScript after changes: `hatch run javascript:build`
257+
258+
## Common Hatch Commands
259+
260+
The following are key commands for daily development:
261+
262+
### Development Commands
263+
264+
```bash
265+
hatch test --parallel # Run all tests (**All tests must always pass**)
266+
hatch test --parallel --cover # Run tests with coverage (used in CI)
267+
hatch test --parallel -k test_name # Run specific tests
268+
hatch fmt # Format code with all formatters
269+
hatch fmt --check # Check formatting without changes
270+
hatch run python:type_check # Run Python type checker
271+
hatch run javascript:build # Build JavaScript packages (15 seconds)
272+
hatch run javascript:check # Lint JavaScript code (10 seconds)
273+
hatch run javascript:fix # Format JavaScript code
274+
hatch build --clean # Build Python package (10 seconds)
275+
```
276+
277+
### Environment Management
278+
279+
```bash
280+
hatch env show # Show all environments
281+
hatch shell # Enter default shell
282+
hatch shell default # Enter development shell
283+
```
284+
285+
### Build Timing Expectations
286+
287+
- **NEVER CANCEL**: All commands complete within 60 seconds in normal operation
288+
- **JavaScript build**: 15 seconds (hatch run javascript:build)
289+
- **Python package build**: 10 seconds (hatch build --clean)
290+
- **Python linting**: 1 second (hatch fmt)
291+
- **JavaScript linting**: 10 seconds (hatch run javascript:check)
292+
- **Type checking**: 10 seconds (hatch run python:type_check)
293+
- **Unit tests**: 10-30 seconds (varies by test selection)
294+
- **Full CI pipeline**: 5-10 minutes
295+
296+
## Development Workflow
297+
298+
Follow this step-by-step process for effective development:
299+
300+
1. **Bootstrap environment**: Ensure you have Python 3.9+ and run `pip install hatch`
301+
2. **Make your changes** to the codebase
302+
3. **Run formatting**: `hatch fmt` to format code (~1 second)
303+
4. **Run type checking**: `hatch run python:type_check` for type checking (~10 seconds)
304+
5. **Run JavaScript linting** (if JavaScript was modified): `hatch run javascript:check` (~10 seconds)
305+
6. **Run relevant tests**: `hatch test --parallel` with specific test selection if needed. **All tests must always pass - failures are never expected or allowed.**
306+
7. **Validate component functionality** manually using validation tests above
307+
8. **Build JavaScript** (if modified): `hatch run javascript:build` (~15 seconds)
308+
9. **Update documentation** when making changes to Python source code (required)
309+
10. **Add changelog entry** for all significant changes to `docs/source/about/changelog.rst`
310+
311+
**IMPORTANT**: Documentation must be updated whenever changes are made to Python source code. This is enforced as part of the development workflow.
312+
313+
**IMPORTANT**: Significant changes must always include a changelog entry in `docs/source/about/changelog.rst` under the appropriate version section.
314+
315+
## Troubleshooting
316+
317+
### Build Issues:
318+
319+
- If JavaScript build fails, try: `hatch run "src/build_scripts/clean_js_dir.py"` then rebuild
320+
- If Python build fails, ensure all dependencies in pyproject.toml are available
321+
- Network timeouts during pip install are common in CI environments
322+
- Missing dependencies error: Install ASGI dependencies with `pip install orjson asgiref asgi-tools servestatic`
323+
324+
### Import Issues:
325+
326+
- ReactPy must be installed or src/ must be in Python path
327+
- Main imports: `from reactpy import component, html, use_state`
328+
- Server imports: `from reactpy.executors.asgi.standalone import ReactPy`
329+
- Web functionality: `from reactpy.web import export, module_from_url`
330+
331+
### Server Issues:
332+
333+
- Missing ASGI dependencies: Install with `pip install orjson asgiref asgi-tools servestatic uvicorn`
334+
- For FastAPI integration: `pip install fastapi uvicorn`
335+
- For Flask integration: `pip install flask` (requires additional backend package)
336+
- For development servers, use ReactPy ASGI standalone for simplest setup
337+
338+
## Package Dependencies
339+
340+
Modern dependency management via pyproject.toml:
341+
342+
**Core Runtime Dependencies:**
343+
344+
- `fastjsonschema >=2.14.5` -- JSON schema validation
345+
- `requests >=2` -- HTTP client library
346+
- `lxml >=4` -- XML/HTML processing
347+
- `anyio >=3` -- Async I/O abstraction
348+
- `typing-extensions >=3.10` -- Type hints backport
349+
350+
**Optional Dependencies (install via extras):**
351+
352+
- `asgi` -- ASGI server support: `orjson`, `asgiref`, `asgi-tools`, `servestatic`, `pip`
353+
- `jinja` -- Template integration: `jinja2-simple-tags`, `jinja2 >=3`
354+
- `uvicorn` -- ASGI server: `uvicorn[standard]`
355+
- `testing` -- Browser automation: `playwright`
356+
- `all` -- All optional dependencies combined
357+
358+
**Development Dependencies (managed by Hatch):**
359+
360+
- **JavaScript tooling**: Bun runtime for building packages
361+
- **Python tooling**: Hatch environments handle all dev dependencies automatically
362+
363+
## CI/CD Information
364+
365+
The repository uses GitHub Actions with these key jobs:
366+
367+
- `test-python-coverage` -- Python test coverage with `hatch test --parallel --cover`
368+
- `lint-python` -- Python linting and type checking via `hatch fmt --check` and `hatch run python:type_check`
369+
- `test-python` -- Cross-platform Python testing across Python 3.10-3.13 and Ubuntu/macOS/Windows
370+
- `lint-javascript` -- JavaScript linting and type checking
371+
372+
The CI workflow is defined in `.github/workflows/check.yml` and uses the reusable workflow in `.github/workflows/.hatch-run.yml`.
373+
374+
**Build Matrix:**
375+
376+
- **Python versions**: 3.10, 3.11, 3.12, 3.13
377+
- **Operating systems**: Ubuntu, macOS, Windows
378+
- **Test execution**: Hatch-managed environments ensure consistency across platforms
379+
380+
Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.
381+
382+
## Important Notes
383+
384+
- **This is a Python-to-JavaScript bridge library**, not a traditional web framework - it enables React-like components in Python
385+
- **Component rendering uses VDOM** - components return virtual DOM objects that get serialized to JavaScript
386+
- **All builds and tests run quickly** - if something takes more than 60 seconds, investigate the issue
387+
- **Hatch environments provide full isolation** - no need to manage virtual environments manually
388+
- **JavaScript packages are bundled into Python** - the build process combines JS and Python into a single distribution
389+
- **Documentation updates are required** when making changes to Python source code
390+
- **Always update this file** when making changes to the development workflow, build process, or repository structure
391+
- **All tests must always pass** - failures are never expected or allowed in a healthy development environment

0 commit comments

Comments
 (0)