Single-page apps

Most of a site is best built as server-rendered pages — they're fast, indexable, and translated automatically. But for app-like surfaces — a dashboard, a client portal, an interactive tool — you can mount a single-page app (React, Vue, Svelte, anything that builds to static assets) under a path on the site, while the rest stays server-rendered. This path is CLI-only.

The model

You choose a path prefix — say /app or /portal — and configure it so that any URL under that prefix serves your app's shell. Your client-side router then takes over in the browser and renders the right view. Outside that prefix, the site behaves normally: server-rendered, translated, SEO-friendly pages.

Your app's built files live in the site's /assets/ folder and load by their own paths, so code-splitting and lazy chunks work as your bundler emits them.

Your toolchain, your repo

You build the app however you like — vite build, or whatever your framework uses — with the output directed into the site's /assets/ folder. Then you publish the site with the CLI. Only the built bundle is published; your framework source stays in your own repository. A typical loop:

# in your app's repo
npm run build            # output into the pulled site's /assets/

# in the pulled site
acira publish -m "Update the portal app"

If your bundler also emits the site's stylesheet, turn the platform's CSS build off in the site's root configuration — otherwise the platform regenerates the stylesheet at publish from the Tailwind classes in your server-rendered templates, replacing your bundler's output.

Talking to the backend

Your app doesn't need a separate API. It calls the site's own page handlers as a same-origin JSON API — the handlers return JSON, your app fetches them — and it reuses the site's sessions, auth, database, and email unchanged. So a logged-in visitor in your SPA is the same session the rest of the site sees.

Tradeoffs to know

• No auto-translation or SEO inside the SPA. Views rendered client-side aren't server-rendered, so they fall outside automatic translation and search indexing. Use SPA areas for app/portal surfaces; keep marketing and content as server-rendered pages.
• Assets are public by filename. Anything sensitive must be a database attachment served through access control, never a file in /assets/.
• CLI-only. The AI coding agent authors server-rendered pages, not framework builds — SPA areas are built and published with the CLI.