diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 4967cc2..cc06034 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,18 +10,15 @@ }, "plugins": [ { - "name": "reflex-docs", - "description": "Reflex framework documentation — components, state, events, styling, database, and more", + "name": "reflex", + "description": "Skills for the Reflex web framework — docs, environment setup, and process management", "source": "./", "strict": false, - "skills": ["./skills/reflex-docs"] - }, - { - "name": "setup-python-env", - "description": "Set up a Python virtual environment and install Reflex for new projects", - "source": "./", - "strict": false, - "skills": ["./skills/setup-python-env"] + "skills": [ + "./skills/reflex-docs", + "./skills/setup-python-env", + "./skills/reflex-process-management" + ] } ] } diff --git a/AGENTS.md b/AGENTS.md index cdda6eb..ee434ea 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,3 +13,9 @@ reflex init ``` Then proceed with the user's request. + +## Managing a Reflex Process + +When you need to compile, run, or reload a Reflex application, follow the [reflex-process-management](skills/reflex-process-management/SKILL.md) skill. + +Follow the skill for compiling, running, reloading, and investigating errors in a Reflex app. diff --git a/README.md b/README.md index ac198e7..caf9da5 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Install using the [plugin marketplace](https://code.claude.com/docs/en/discover- ``` /plugin marketplace add reflex-dev/agent-skills -/plugin install reflex-docs@reflex-agent-skills +/plugin install reflex@reflex-agent-skills ``` ### Cursor @@ -41,10 +41,11 @@ Clone this repo and copy the skill folders into the appropriate directory for yo Skills are contextual and auto-loaded based on your conversation. -| Skill | Description | -| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -| [reflex-docs](skills/reflex-docs/SKILL.md) | Framework documentation covering components, state management, events, styling, database, routing, authentication, and more | -| [setup-python-env](skills/setup-python-env/SKILL.md) | Set up a Python virtual environment and install Reflex for new projects | +| Skill | Description | +| ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| [reflex-docs](skills/reflex-docs/SKILL.md) | Framework documentation covering components, state management, events, styling, database, routing, authentication, and more | +| [setup-python-env](skills/setup-python-env/SKILL.md) | Set up a Python virtual environment and install Reflex for new projects | +| [reflex-process-management](skills/reflex-process-management/SKILL.md) | Compile, run, reload, and debug a Reflex application process | ## MCP Servers diff --git a/skills/reflex-process-management/SKILL.md b/skills/reflex-process-management/SKILL.md new file mode 100644 index 0000000..c43df8b --- /dev/null +++ b/skills/reflex-process-management/SKILL.md @@ -0,0 +1,91 @@ +--- +name: reflex-process-management +description: > + Manage Reflex application processes: compile to test, run the server in production mode, + reload a running app by finding and restarting the backend process, and manage logs for + debugging. Use when the user wants to test, run, restart, or reload a Reflex app, + when troubleshooting a running Reflex server, or when investigating errors. +--- + +# Reflex Process Management + +This skill covers how to compile, run, and reload a Reflex application. + +## Compiling (Testing the App) + +To verify the app compiles without errors, run: + +```bash +reflex compile --dry-run +``` + +This checks for syntax errors, import issues, and component problems without starting the server. Use this as a quick validation step after making changes. + +## Running the Server + +When instructed to run the Reflex server, always use production mode and redirect output to a log file: + +```bash +reflex run --env prod 2>&1 | tee reflex.log +``` + +This command starts a long-running server process that **does not support hot reload** in production mode. Code changes will not be picked up automatically — you must stop and restart the server to apply changes (see **Reloading a Running App** below). + +Using `2>&1 | tee reflex.log` captures both stdout and stderr to `reflex.log` while still printing to the terminal. + +> **Important:** Always use `--env prod` unless the user explicitly requests development mode. + +## Reloading a Running App + +To reload the app without manually stopping and restarting from the terminal, follow these steps: + +### Step 1: Determine the backend port + +Read `reflex.log` to find the port the backend is listening on. Look for a line like `Backend running at: http://0.0.0.0:`. Do not assume the port is 8000. + +### Step 2: Find the backend process + +Using the port from Step 1, locate the process: + +```bash +lsof -i : -t +``` + +If `lsof` is not available, use: + +```bash +ss -tlnp | grep : +``` + +Or: + +```bash +fuser /tcp +``` + +### Step 3: Send an interrupt signal + +Send `SIGINT` (equivalent to Ctrl+C) to gracefully stop the process: + +```bash +kill -INT $(lsof -i : -t) +``` + +If the process doesn't stop, escalate to `SIGTERM`: + +```bash +kill -TERM $(lsof -i : -t) +``` + +### Step 4: Restart the server + +Once the old process has exited, truncate the old log and start the server again: + +```bash +> reflex.log +reflex run --env prod 2>&1 | tee reflex.log +``` + +## Investigating Errors + +When the user reports an error, read `reflex.log` to find and diagnose the issue.