> This is the Markdown rendition of https://pyxle.dev/docs/core-concepts/pyxl-files, served for AI agents and assistants.
> Append `.md` to any pyxle.dev URL to fetch its Markdown; the links below already do.
> Index of every page: https://pyxle.dev/llms.txt · Whole docs in one file: https://pyxle.dev/llms-full.txt
> Search the docs: https://pyxle.dev/api/docs-search?q=YOUR+QUERY (returns matching pages as Markdown links)
# `.pyxl` Files
A `.pyxl` file is the fundamental building block of a Pyxle application. It combines Python server logic with a React component in a single file -- your data fetching and your UI live together.
## Anatomy of a `.pyxl` file
A `.pyxl` file has two sections:
```pyxl
# 1. Python section -- runs on the server
from datetime import datetime
@server
async def load_page(request):
return {"now": datetime.now().isoformat()}
// 2. JSX section -- runs on both server (SSR) and client
import { Head } from 'pyxle/client';
export default function MyPage({ data }) {
return (
<>
My Page
Current time: {data.now}
);
}
```
The compiler finds the boundary automatically: it grows the largest region that parses as valid **Python** (using Python's own AST), and treats whatever isn't valid Python as **JSX**. There are no separator comments or directives to write.
## The Python section
The Python section runs entirely on the server. It can:
- **Import modules** -- any Python package available in your environment
- **Define a `@server` loader** -- an async function that fetches data for the component
- **Define `@action` mutations** -- async functions callable from the client
```python
from pyxle.runtime import server, action
import httpx
@server
async def load_users(request):
async with httpx.AsyncClient() as client:
resp = await client.get("https://api.example.com/users")
return {"users": resp.json()}
@action
async def delete_user(request):
body = await request.json()
user_id = body["id"]
# ... delete from database ...
return {"deleted": user_id}
```
### Rules for the Python section
- **One `@server` loader per file.** The loader receives a Starlette `Request` and must return a JSON-serializable dict.
- **Multiple `@action` functions are allowed.** Each becomes a callable endpoint.
- **The `@server` function must be `async`.** Pyxle enforces this at compile time.
- **Use any Python imports.** Standard `import` / `from` statements stay in the Python section because they parse as valid Python. (A JavaScript import such as `import React from 'react'` isn't valid Python, so it is correctly treated as part of the JSX section — the split is by what parses, not by the leading keyword.)
- **The `@server` and `@action` decorators are available globally** -- you do not need to import them (the compiler injects the import automatically).
- **An optional `CACHE = {"revalidate": N}` directive** caches the rendered page for `N` seconds (server-side, with incremental regeneration). See [Caching](https://pyxle.dev/docs/guides/caching.md).
## The JSX section
The JSX section is a standard React component. It runs on both the server (for SSR) and the client (for hydration and interactivity).
```jsx
import { Head } from 'pyxle/client';
export default function MyPage({ data }) {
const [count, setCount] = React.useState(0);
return (
<>
Users
Users: {data.users.length}
);
}
```
### Rules for the JSX section
- **Must have a default export.** The default export is the page component.
- **Receives `{ data }` as props.** The `data` prop contains whatever the `@server` loader returned. If there is no loader, `data` is an empty object `{}`.
- **Can import from `pyxle/client`.** This gives you ``, `