Fragments & SSR IPC Reference¶

get_component_css_urls(component)

Extract all CSS file URLs for a component from manifest or dev server.

In production mode, looks up the component in the parsed manifest.json, collects its direct 'css' array, and recursively traverses 'imports' chunks to collect imported CSS dependencies with cycle detection. Normalizes paths using POSIX formatting to support Windows environments.

In development mode, returns the direct component CSS URL or Vite dev server URL only for dedicated stylesheet files, omitting component entries such as .vue and .tsx to prevent browser MIME type rejections.

Parameters:

Name	Type	Description	Default
component	str	Relative path to the component, e.g. 'components/UserProfile.vue'.	required

Returns:

Type	Description
list[str]	List of resolved CSS URLs.

generate_component_css_tags(component, newline='\n')

Generate HTML link tags for a component's scoped styles.

Parameters:

Name	Type	Description	Default
component	str	Relative path to the component entrypoint.	required
newline	str	Line ending character to join multiple tags.	'\n'

Returns:

Type	Description
str	String of HTML link tags, or empty string if no CSS is associated.

render_fragment(component, props=None, mode='static')

Render a UI component fragment to HTML asynchronously.

Sends render request to the background IPC worker, retrieves the rendered markup, and prepends scoped CSS link tags resolved from manifest.json.

Parameters:

Name	Type	Description	Default
component	str	Path to the component entrypoint, e.g. 'components/Counter.vue'.	required
props	dict[str, Any] | None	Optional dictionary of component props.	None
mode	Literal['static', 'island']	Rendering mode, either 'static' (zero JS) or 'island' (interactive).	'static'

Returns:

Type	Description
str	Rendered HTML string with scoped CSS links prepended.

Raises:

Type	Description
ImproperlyConfiguredException	If the IPC worker reports a render error.

render_fragment_sync(component, props=None, mode='static')

Render a UI component fragment synchronously for template engines.

Executes the async render_fragment method on the worker loop using anyio. Falls back to anyio.run when no event loop is active on the current thread.

Parameters:

Name	Type	Description	Default
component	str	Path to the component entrypoint.	required
props	dict[str, Any] | None	Optional dictionary of component props.	None
mode	Literal['static', 'island']	Rendering mode.	'static'

Returns:

Type	Description
str	Rendered HTML string with scoped CSS links prepended.

close()

Close the underlying IPC transport if initialized.

to_asgi_response(
    app,
    request,
    *,
    background=None,
    cookies=None,
    encoded_headers=None,
    headers=None,
    is_head_response=False,
    media_type=None,
    status_code=None,
    type_encoders=None,
)

Construct the ASGI response that renders the component fragment.

Parameters:

Name	Type	Description	Default
app	Any	The Litestar application instance.	required
request	Request[Any, Any, Any]	The incoming request.	required
background	BackgroundTask | BackgroundTasks | None	Optional background tasks.	None
cookies	Any	Optional cookies.	None
encoded_headers	Any	Optional encoded headers.	None
headers	dict[str, str] | None	Optional headers dictionary.	None
is_head_response	bool	Whether the request is a HEAD request.	False
media_type	Any	Response media type.	None
status_code	int | None	Optional status code override.	None
type_encoders	Any	Type encoders mapping.	None

Returns:

Type	Description
ASGIResponse	An ASGIResponse callable that executes the fragment rendering.

start()

Start or initialize the IPC transport.

close()

Gracefully shut down the IPC transport and release all resources.

send_request(payload, timeout=10.0)

Send a JSON payload and return the response.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Request dictionary payload.	required
timeout	float	Maximum duration in seconds to wait for a response.	10.0

Returns:

Type	Description
dict[str, Any]	Decoded response payload dictionary from the worker.

start()

Spawn the background worker process and launch asynchronous I/O readers.

send_request(payload, timeout=10.0)

Send an NDJSON request to the worker and await the correlated response.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Request dictionary payload.	required
timeout	float	Maximum time in seconds to await response.	10.0

Returns:

Type	Description
dict[str, Any]	Worker response dictionary.

Raises:

Type	Description
IPCTimeoutError	When response is not received within timeout.
IPCWorkerCrashError	When child worker exits unexpectedly.
IPCError	When worker reports an execution failure.

close()

Gracefully terminate worker subprocess and release reader tasks.

start()

Initialize the dedicated worker thread and evaluate the SSR bundle.

close()

Shut down the worker thread and release the QuickJS context.

send_request(payload, timeout=10.0)

Serialize a request, dispatch it to the in-process SSR worker, and decode the response.

Dispatches are serialized on a single engine thread. timeout bounds the execution of this request only; time spent waiting for an earlier request to finish is not counted, so a queued request never resets a healthy engine.

Parameters:

Name	Type	Description	Default
payload	dict[str, Any]	Outbound IPC request dictionary.	required
timeout	float	Maximum duration in seconds to wait for a response once dispatched.	10.0

Returns:

Type	Description
dict[str, Any]	Decoded response dictionary from the SSR worker.

start()

Initialize the client connection pool if needed.

close()

Release pooled connections.

send_request(payload, timeout=10.0)

Send an RPC request within a total deadline and validate its response.

Raises:

Type	Description
IPCTimeoutError	The request exceeded its total deadline.
IPCError	The connection failed or the server returned an invalid response.

to_dict()

Convert the request into a JSON-serializable dictionary.

Returns:

Type	Description
dict[str, Any]	Dictionary payload adhering to the RPC framing contract.

can_execute()

Determine whether an outbound request is permitted through the breaker.

Returns:

Type	Description
bool	True if request is allowed, False if breaker is open.

allow_request()

Return whether an outbound request is permitted through the circuit breaker.

Returns:

Type	Description
bool	True if request is allowed, False if breaker is open.

record_success()

Record a successful execution, resetting failures and closing the circuit.

record_failure(exc=None)

Record an execution failure, potentially tripping the circuit to OPEN.

Parameters:

Name	Type	Description	Default
exc	BaseException | None	Optional exception that caused the failure.	None

reset()

Manually reset the circuit breaker to closed state.