Skip to content

Commit d463fd2

Browse files
ArchmongerArchmonger
authored
Add comprehensive GitHub Copilot instructions with development best practices for ReactPy (#1303)
2 parents 9a02db4 + 8ea5868 commit d463fd2

File tree

1 file changed

+368
-0
lines changed

1 file changed

+368
-0
lines changed

‎.github/copilot-instructions.md‎

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

0 commit comments

Comments
 (0)