Recommended pattern for splitting a large plugin UI across multiple JS/CSS files?

[nara-falconeer]

We're building a plugin with a substantial in-chart UI (multi-step flows, panel layouts, modals).

The pattern we know is: Application handler → LaunchModalEffect → SimpleAPI route that renders a single HTML template via render_to_string, with all JS and CSS inline.

That's fine for small UIs. We're now past 4,000 lines of inline JS in one template, and the cost compounds:

• Navigation + review: every change diffs against a 4k-line file regardless of size.
• Reuse: can't share helpers across views or plugins without copy-paste.
• Tooling: type checking, linting, and unit-testing JS embedded in a Jinja template is awkward — we lose most of the JS toolchain.
• Debugging: stack traces all point at one template URL with line numbers in the thousands.
• Concurrent work: devs constantly collide in the same file.

Things we looked for and didn't find:

• Static-asset endpoints in a plugin package (e.g. assets/main.js importable via <script type="module">).
• A documented way to ship multiple templates that import from each other.
• A recommended bundling story.

Questions:

1. Is there an existing pattern we've missed?
2. For folks running larger plugin UIs, how do you handle this — inline-everything, external CDN bundles, something else?
3. Is static-asset support on the roadmap?

[rmagier1]

Hi @nara-falconeer,

Good question — there are two patterns supported today that should fit what you're describing. Neither is auto-magic at the framework level, but both are in our published example plugins, so we know they work end-to-end.

Pattern 1: split JS/CSS into separate files, serve each from its own SimpleAPI route

This is the closest analogue to "static-asset endpoints in a plugin package." You add one @api.get per asset and return it with the right content_type:

class MyWebApp(SimpleAPI):
    PREFIX = "/app"

    @api.get("/")
    def page(self) -> list[Response | Effect]:
        return [HTMLResponse(render_to_string("static/app.html", context), status_code=HTTPStatus.OK)]

    @api.get("/main.js")
    def main_js(self) -> list[Response | Effect]:
        return [Response(
            render_to_string("static/main.js").encode(),
            status_code=HTTPStatus.OK,
            content_type="text/javascript",
        )]

    @api.get("/styles.css")
    def styles_css(self) -> list[Response | Effect]:
        return [Response(
            render_to_string("static/styles.css").encode(),
            status_code=HTTPStatus.OK,
            content_type="text/css",
        )]

The HTML then references them as relative URLs, just like normal static assets:

<link rel="stylesheet" href="styles.css">
<script type="text/javascript" src="main.js"></script>

Working examples in the canvas-plugins repo:

• example-plugins/example_provider_companion_app — static/main.js, static/styles.css, static/app.html served from handlers/my_web_app.py.
• example-plugins/example_patient_portal_page — same pattern.
• example-plugins/example_provider_page — same pattern.

Nothing stops you from extending this to as many files as you need — helpers/foo.js, views/encounter.js, views/panel.js, etc. Each gets a route, each is served with the correct content type, and the browser caches them like normal assets.

You can also break a single big JS file into ES modules and load them with <script type="module" src="main.js"> — import / export resolve relative to the served URL, so you get reuse across files without bundling.

Sharing across plugins

SimpleAPI routes are mounted at the absolute path /plugin-io/api/<plugin_name>/<route>, so they're addressable from any other plugin on the same instance. You can package common helpers (e.g. <script src="/plugin-io/api/shared_assets/helpers.js">) in a single "shared assets" plugin and reference them from any other plugin's HTML — no copy-paste between plugins needed. Browser-side they're plain HTTP requests, and since everything is same-origin under the customer's Canvas domain, session auth on the shared-assets plugin works without any cross-origin setup.

Pattern 2: bundle with Vite (or your tool of choice), ship a single inlined template

If you want the full JS toolchain — TypeScript, linting, unit tests, HMR during dev, tree-shaking — the preact_hello_world example is the reference:

• Source lives in frontend/src/ (TSX, CSS, whatever).
• vite.config.ts uses vite-plugin-singlefile to inline everything into one HTML.
• scripts/build.py runs npm run build and copies frontend/dist/index.html into plugin_name/templates/counter.html.
• The handler does the usual LaunchModalEffect(content=render_to_string("templates/counter.html")).

You keep multi-file source code, full toolchain, and unit-testable JS — but ship one template at runtime. This addresses every cost you listed (navigation, reuse, tooling, debugging, concurrent work).

Replace preact with react, Svelte, vanilla TS, etc., however you like. The pattern is just: build → single HTML → copy → render.

On your three questions, directly

1. Existing pattern you missed: yes — Pattern 1 above (multiple @api.get routes, one per asset) is documented through the example plugins, even if it isn't called out as a "split your JS" pattern in the SDK docs. Pattern 2 (bundling) is also there as a complete reference.
2. What folks running larger UIs do: the two examples above are the patterns we'd point you at.
3. Static-asset support on the roadmap: I don't have anything to point at on the roadmap for first-class plugin static-asset endpoints (i.e. drop a file in static/ and have the runner serve it automatically without writing a route per file). If you want to submit that as a feature request, we can log a Github Issue for the request.

Let me know if either of those patterns gets you unblocked, or if there's a specific shape of "shared across plugins" that doesn't fit the URL-reference approach above.