Skip to content

Commit 9f44070

Browse files
CopilotArchmonger
Copilot
and
Archmonger
committed
Add comprehensive GitHub Copilot instructions for ReactPy development
Co-authored-by: Archmonger <16909269+Archmonger@users.noreply.github.com>
1 parent 2321b54 commit 9f44070

File tree

1 file changed

+268
-0
lines changed

1 file changed

+268
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 268 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,268 @@
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+
## Working Effectively
8+
9+
### Bootstrap, Build, and Test the Repository
10+
11+
**Prerequisites:**
12+
- Install Python 3.9+ from https://www.python.org/downloads/
13+
- Install Hatch: `pip install hatch`
14+
- Install Bun JavaScript runtime: `curl -fsSL https://bun.sh/install | bash && source ~/.bashrc`
15+
- Install Git
16+
17+
**Initial Setup:**
18+
```bash
19+
git clone https://github.com/reactive-python/reactpy.git
20+
cd reactpy
21+
```
22+
23+
**Install Dependencies for Development:**
24+
```bash
25+
# Install core ReactPy dependencies
26+
pip install fastjsonschema requests lxml anyio typing-extensions
27+
28+
# Install ASGI dependencies for server functionality
29+
pip install orjson asgiref asgi-tools servestatic uvicorn fastapi
30+
31+
# Optional: Install additional servers
32+
pip install flask sanic tornado
33+
```
34+
35+
**Build JavaScript Packages:**
36+
- `hatch run javascript:build` -- takes 15 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
37+
- This builds three packages: event-to-object, @reactpy/client, and @reactpy/app
38+
39+
**Build Python Package:**
40+
- `hatch build --clean` -- takes 10 seconds. NEVER CANCEL. Set timeout to 60+ minutes for safety.
41+
42+
**Run Python Tests:**
43+
- `hatch test` -- takes 10-30 seconds for basic tests. NEVER CANCEL. Set timeout to 60+ minutes for full test suite.
44+
- `hatch test -k test_name` -- run specific tests
45+
- `hatch test tests/test_config.py` -- run specific test files
46+
- Note: Some tests require Playwright browser automation and may fail in headless environments
47+
48+
**Run Python Linting and Formatting:**
49+
- `hatch fmt` -- Run all linters and formatters (~1 second)
50+
- `hatch fmt --check` -- Check formatting without making changes (~1 second)
51+
- `hatch fmt --linter` -- Run only linters
52+
- `hatch fmt --formatter` -- Run only formatters
53+
- `hatch run python:type_check` -- Run Python type checker (~10 seconds)
54+
55+
**Run JavaScript Tasks:**
56+
- `hatch run javascript:check` -- Lint and type-check JavaScript (10 seconds). NEVER CANCEL. Set timeout to 30+ minutes.
57+
- `hatch run javascript:fix` -- Format JavaScript code
58+
- `hatch run javascript:test` -- Run JavaScript tests (note: may fail in headless environments due to DOM dependencies)
59+
60+
## Validation
61+
62+
Always manually validate any new code changes through these steps:
63+
64+
**Basic Functionality Test:**
65+
```python
66+
# Add src to path if not installed
67+
import sys, os
68+
sys.path.insert(0, os.path.join("/path/to/reactpy", "src"))
69+
70+
# Test that imports and basic components work
71+
import reactpy
72+
from reactpy import component, html, use_state
73+
74+
@component
75+
def test_component():
76+
return html.div([
77+
html.h1("Test"),
78+
html.p("ReactPy is working")
79+
])
80+
81+
# Verify component renders
82+
vdom = test_component()
83+
print(f"Component rendered: {type(vdom)}")
84+
```
85+
86+
**Server Functionality Test:**
87+
```python
88+
# Test ASGI server creation (most common deployment)
89+
from reactpy import component, html
90+
from reactpy.executors.asgi.standalone import ReactPy
91+
import uvicorn
92+
93+
@component
94+
def hello_world():
95+
return html.div([
96+
html.h1("Hello, ReactPy!"),
97+
html.p("Server is working!")
98+
])
99+
100+
# Create ASGI app (don't run to avoid hanging)
101+
app = ReactPy(hello_world)
102+
print("✓ ASGI server created successfully")
103+
104+
# To actually run: uvicorn.run(app, host="127.0.0.1", port=8000)
105+
```
106+
107+
**Hooks and State Test:**
108+
```python
109+
from reactpy import component, html, use_state
110+
111+
@component
112+
def counter_component(initial=0):
113+
count, set_count = use_state(initial)
114+
115+
return html.div([
116+
html.h1(f"Count: {count}"),
117+
html.button({
118+
"onClick": lambda event: set_count(count + 1)
119+
}, "Increment")
120+
])
121+
122+
# Test component with hooks
123+
counter = counter_component(5)
124+
print(f"✓ Hook-based component: {type(counter)}")
125+
```
126+
127+
**Always run these validation steps before completing work:**
128+
- `hatch fmt --check` -- Ensure code is properly formatted
129+
- `hatch run python:type_check` -- Ensure no type errors
130+
- `hatch run javascript:check` -- Ensure JavaScript passes linting
131+
- Test basic component creation and rendering as shown above
132+
- Test server creation if working on server-related features
133+
134+
**Integration Testing:**
135+
- ReactPy can be deployed with FastAPI, Flask, Sanic, Tornado via ASGI
136+
- For browser testing, Playwright is used but requires additional setup
137+
- Test component VDOM rendering directly when browser testing isn't available
138+
- Validate that JavaScript builds are included in Python package after changes
139+
140+
## Repository Structure
141+
142+
### Key Directories:
143+
- `src/reactpy/` -- Main Python package source code
144+
- `src/js/` -- JavaScript packages that get bundled with Python
145+
- `src/build_scripts/` -- Build automation scripts
146+
- `tests/` -- Python test suite
147+
- `docs/` -- Documentation source (currently transitioning to MkDocs)
148+
149+
### Important Files:
150+
- `pyproject.toml` -- Python project configuration and build scripts
151+
- `src/js/package.json` -- JavaScript development dependencies
152+
- `src/js/packages/` -- Individual JavaScript packages
153+
- `tests/conftest.py` -- Test configuration and fixtures
154+
155+
### Key Components:
156+
- `src/reactpy/core/` -- Core ReactPy functionality (components, hooks, VDOM)
157+
- `src/reactpy/web/` -- Web module management and exports
158+
- `src/reactpy/widgets/` -- Built-in UI components
159+
- `src/reactpy/pyscript/` -- PyScript integration
160+
- `src/reactpy/_html.py` -- HTML element factory functions
161+
162+
## Common Tasks
163+
164+
### Build Time Expectations:
165+
- JavaScript build: 15 seconds
166+
- Python package build: 10 seconds
167+
- Python linting: 1 second
168+
- JavaScript linting: 10 seconds
169+
- Type checking: 10 seconds
170+
- Full CI pipeline: 5-10 minutes
171+
172+
### Development Workflow:
173+
1. Make code changes
174+
2. Run `hatch fmt` to format code (~1 second)
175+
3. Run `hatch run python:type_check` for type checking (~10 seconds)
176+
4. Run `hatch run javascript:check` if JavaScript was modified (~10 seconds)
177+
5. Run relevant tests with `hatch test`
178+
6. Validate component functionality manually using validation tests above
179+
180+
### Running ReactPy Applications:
181+
182+
**ASGI Standalone (Recommended):**
183+
```python
184+
from reactpy import component, html
185+
from reactpy.executors.asgi.standalone import ReactPy
186+
import uvicorn
187+
188+
@component
189+
def my_app():
190+
return html.h1("Hello World")
191+
192+
app = ReactPy(my_app)
193+
uvicorn.run(app, host="127.0.0.1", port=8000)
194+
```
195+
196+
**With FastAPI:**
197+
```python
198+
from fastapi import FastAPI
199+
from reactpy import component, html
200+
from reactpy.executors.asgi.middleware import ReactPyMiddleware
201+
202+
@component
203+
def my_component():
204+
return html.h1("Hello from ReactPy!")
205+
206+
app = FastAPI()
207+
app.add_middleware(ReactPyMiddleware, component=my_component)
208+
```
209+
210+
### Creating Components:
211+
```python
212+
from reactpy import component, html, use_state
213+
214+
@component
215+
def my_component(initial_value=0):
216+
count, set_count = use_state(initial_value)
217+
218+
return html.div([
219+
html.h1(f"Count: {count}"),
220+
html.button({
221+
"onClick": lambda event: set_count(count + 1)
222+
}, "Increment")
223+
])
224+
```
225+
226+
### Working with JavaScript:
227+
- JavaScript packages are in `src/js/packages/`
228+
- Three main packages: event-to-object, @reactpy/client, @reactpy/app
229+
- Built JavaScript gets bundled into `src/reactpy/static/`
230+
- Always rebuild JavaScript after changes: `hatch run javascript:build`
231+
232+
## Troubleshooting
233+
234+
### Build Issues:
235+
- If JavaScript build fails, try: `hatch run "src/build_scripts/clean_js_dir.py"` then rebuild
236+
- If Python build fails, ensure all dependencies in pyproject.toml are available
237+
- Network timeouts during pip install are common in CI environments
238+
- Missing dependencies error: Install ASGI dependencies with `pip install orjson asgiref asgi-tools servestatic`
239+
240+
### Test Issues:
241+
- Playwright tests may fail in headless environments -- this is expected
242+
- Tests requiring browser DOM should be marked appropriately
243+
- Use `hatch test -k "not playwright"` to skip browser-dependent tests
244+
- JavaScript tests may fail with "window is not defined" in Node.js environment -- this is expected
245+
246+
### Import Issues:
247+
- ReactPy must be installed or src/ must be in Python path
248+
- Main imports: `from reactpy import component, html, use_state`
249+
- Server imports: `from reactpy.executors.asgi.standalone import ReactPy`
250+
- Web functionality: `from reactpy.web import export, module_from_url`
251+
252+
### Server Issues:
253+
- Missing ASGI dependencies: Install with `pip install orjson asgiref asgi-tools servestatic uvicorn`
254+
- For FastAPI integration: `pip install fastapi uvicorn`
255+
- For Flask integration: `pip install flask` (requires additional backend package)
256+
- For development servers, use ReactPy ASGI standalone for simplest setup
257+
258+
## CI/CD Information
259+
260+
The repository uses GitHub Actions with these key jobs:
261+
- `test-python-coverage` -- Python test coverage
262+
- `lint-python` -- Python linting and type checking
263+
- `test-python` -- Cross-platform Python testing
264+
- `lint-javascript` -- JavaScript linting and type checking
265+
266+
The CI workflow is defined in `.github/workflows/check.yml` and uses the reusable workflow in `.github/workflows/.hatch-run.yml`.
267+
268+
Always ensure your changes pass local validation before pushing, as the CI pipeline will run the same checks.

0 commit comments

Comments
 (0)