orionplace-svelte

Set up a SvelteKit 2 storefront for your personal Orionplace marketplace API. The package includes a setup CLI, the SvelteKit starter with typed AppLoad initialization, and commented server source that is copied into your project alongside an integration README.

Requires Node.js 20.19+, Svelte 5 and @sveltejs/adapter-node. Static and edge-only adapters cannot read the domain files this integration uses.

Quick start from zero

Your personal backend domain is already provided in your account at orionmarket.place. You can change it there. Replace your-project.orionplace.app below with that domain and shop.example.com with the public domain of your own storefront. With Node.js 20.19+ and npm installed, run this from the parent folder; no existing SvelteKit project is needed:

npx --yes orionplace-svelte init my-marketplace
cd my-marketplace
npm install
npx orionplace-svelte set backend your-project.orionplace.app
npx orionplace-svelte add frontend shop.example.com
npm run dev

The first command creates the SvelteKit configuration, starter routes and integration README. The first frontend becomes the local MIMIC domain. Open the local URL printed by Vite (normally http://localhost:5173); the starter's AppLoad state should show Loaded. If it shows Failed, check your domain mapping and backend response. The backend command accepts either a hostname or its full HTTPS /api URL. The frontend command accepts a public hostname or its root HTTPS URL.

Existing SvelteKit 2 project

npm install orionplace-svelte
npx orionplace-svelte init --dry-run
npx orionplace-svelte set backend your-project.orionplace.app
npx orionplace-svelte add frontend shop.example.com
npm install
npm run dev

The CLI preserves unrelated SvelteKit settings, scripts, and environment variables. It never replaces your own svelte.config.js, vite.config.ts, src/app.html, src/hooks.server.ts, root layout or home page: it keeps your file and prints its path so you can merge the starter yourself. Switch to @sveltejs/adapter-node and resolve an existing /api catch-all route before setup.

No install or postinstall hook changes your application. Only explicitly running the CLI writes files. Use --cwd <directory> to select a project and --dry-run to inspect planned changes without writing them.

Commands

npx orionplace-svelte init [directory]
npx orionplace-svelte update
npx orionplace-svelte set backend your-project.orionplace.app
npx orionplace-svelte add frontend shop.example.com
npx orionplace-svelte add frontend www.shop.example.com
npx orionplace-svelte remove frontend www.shop.example.com
npx orionplace-svelte set mimic shop.example.com
npx orionplace-svelte help

Either domain command can run first. Both settings are needed for a usable mapping. After setup, these npm script aliases are also available:

npm run orionplace:backend -- your-project.orionplace.app
npm run orionplace:add-frontend -- shop.example.com
npm run orionplace:remove-frontend -- www.shop.example.com
npm run orionplace:mimic -- shop.example.com
npm run orionplace:help
npm run orionplace:update

npm set belongs to npm's own configuration system; use the commands above. These commands configure local integration files. They do not provision a backend, change your account, create DNS records, configure TLS, or deploy a VPS.

Generated files

| Path | Purpose | | --- | --- | | src/routes/api/[...orionplace]/+server.ts | Route serving /api/... from your project. | | src/routes/+layout.server.ts | Initializes AppLoad before your pages render. | | src/routes/+layout.svelte | Creates the store for this session and puts it in context. | | src/routes/+page.svelte | Starter page showing the AppLoad state; replace it with your storefront. | | src/hooks.server.ts | Marks personalized pages private, no-store and varies them by domain. | | src/lib/orionplace/ | Server transport with cookie relay, browser transport, envelope checks, domain resolution. | | src/lib/orionplace/store.svelte.ts | Typed snapshot, status, merged discovery and derived data as Svelte 5 runes. | | src/lib/interfaces/orionplace/ | The AppLoad response envelope and every nested model. | | svelte.config.js, vite.config.ts | Node adapter, and your storefront domains as allowed development hosts. | | orionplace/runtime/marketplace.mjs | Commented domain lookup and HTTP transport. | | orionplace/README.md | Your settings, API examples, file explanations, verification and VPS deployment. | | orionplace/settings.json | Domain values selected by the CLI. | | orionplace/.generated.json | File hashes used to preserve your edits on subsequent setup. | | sitemaps/shop.example.com.cfg | One line: https://your-project.orionplace.app/api. | | .env | MIMIC_FRONT_DOMAIN="shop.example.com" for localhost. |

All generated source is yours to read and customize. Later setup runs preserve edited files and report which ones were preserved. Unchanged generated files can be refreshed with npx orionplace-svelte update. A manually edited domain file is never silently overwritten. Keep the hash manifest in version control.

Multiple frontend domains

Each frontend gets its own sitemaps/<domain>.cfg. add frontend preserves other domains and can be repeated safely. set backend updates every CLI-managed mapping to the new personal API; it refuses to overwrite a manually edited mapping.

A new project starts with MIMIC_FRONT_DOMAIN="" in .env. Setting a backend alone leaves it empty. The first added frontend becomes MIMIC; further additions preserve that choice. set mimic <domain> selects an already-added frontend and updates MIMIC without changing any domain mappings. Unknown domains are rejected; add them with add frontend first.

help, --help, and -h display commands without writing files. The legacy set frontend <domain> shortcut remains supported: it adds and selects a domain.

remove frontend <domain> removes that domain from the list and deletes only its unchanged generated .cfg. Removing the MIMIC domain selects the first remaining domain. Removing the last one clears MIMIC. Unknown or edited mappings cause a clear error without changing files. Unrelated configurations remain untouched.

Restart development after domain changes so Vite reloads its allowed hosts and SvelteKit reloads .env. Production reloads mapping files on each API request; reload the process environment when changing MIMIC. Configure DNS, TLS, and the hosting proxy for each frontend separately.

Runtime behavior

The hosting proxy must overwrite X-Front-Domain, X-Forwarded-Host, and Host. The gateway selects the first valid public domain in that order, with the request URL hostname as another fallback. On localhost it uses MIMIC_FRONT_DOMAIN. An unknown public domain returns 503; it never uses another domain's mapping.

The corresponding .cfg is read on every request. Backend URLs must use HTTPS, end in /api, and belong to *.orionplace.app. API methods, query strings, bodies, authorization and cookies are forwarded. Backend statuses are retained and cookie Domain attributes are removed to bind cookies to the storefront. Gateway responses use Cache-Control: no-store. Network failures return 502. Cross-site mutations are rejected with 403.

SvelteKit ignores a request body sent without a Content-Type header, so always set it on your own API calls; browsers do this automatically for fetch.

Browser requests use /api/.... Server loads call the same gateway in process through src/lib/orionplace/appLoadServer.ts, which forwards the current request's domain, cookies and language.

Deploy sitemaps with the production server, or set an absolute SITEMAPS_DIR. The production process reads MIMIC_FRONT_DOMAIN without rebuilding. Run the server from the project root or explicitly point it at the configuration directory.

AppLoad starter

The root layout load awaits POST /api/appload in light mode before your pages render and returns the snapshot to every route, so await parent() in a page load reuses it instead of requesting again. The root layout component creates one store per browser session and hydrates it from that snapshot; components read it with getOrionplaceContext(). Reading the store never starts a request, and initialization never opens an authentication prompt. store.refresh() reloads explicitly, and SvelteKit's invalidateAll() also works: the layout load runs again and the store adopts the new snapshot.

Live discovery from page_data.unauth.paths and, for a signed-in session, page_data.auth.paths, is merged into one lookup without mutating the response. Discovery describes availability; the backend still checks permissions on each call.

Session and CSRF cookies

AppLoad establishes the guest/customer session and CSRF cookie through HTTP Set-Cookie headers, not through page_data.init. The browser handles the signed HttpOnly sessionid cookie; never parse, rewrite, log or store its value in the store or localStorage. The readable csrftoken supplies X-CSRFToken for later protected requests through the same-origin /api/ gateway with credentials enabled. Read the CSRF cookie again for every action because login can rotate it.

During a server render the layout load forwards the incoming cookies and relays each backend Set-Cookie separately through SvelteKit's cookie API, preserving the exact signed value and its attributes. Cookies established this way are also visible to later calls in the same render. Never share a cookie jar across visitors.

Use POST /api/csrf_renew with {} to renew CSRF, then re-read the cookie. The backend signals CSRF rejection with HTTP 419 and page_data.csrf: false; a general 403 may mean permissions or origin rejection. Do not automatically replay mutations. After confirmed login/logout, reset and refresh AppLoad. Those store actions update data; they do not authenticate or delete cookies.

Update an existing project

After the initial setup, use one command to get the latest package and components:

npx orionplace-svelte update

It runs the latest CLI, adds new template files, refreshes unchanged generated files, updates the package dependency and runs npm install to synchronize the lockfile and installed dependencies. Edited files are preserved and listed in the output. Review their new versions under node_modules/orionplace-svelte/templates or runtime and merge your changes manually when needed. Removed upstream files are retained locally; the updater does not delete customer source.

Domain mappings, domain settings and .env remain unchanged. The command does not deploy your application: restart development, or rebuild and redeploy the production frontend after updating.

npx orionplace-svelte update --dry-run
npm run orionplace:update

Dry-run downloads the latest CLI into npm's cache to inspect its templates but leaves project files and dependencies unchanged. update --local applies the version of the CLI being executed instead of fetching the latest CLI; it still installs project dependencies. Use this only when intentionally selecting a version.

Updates require the existing orionplace/settings.json and .generated.json. Conflicting untracked files stop the source update before any writes. If dependency installation fails after source generation, run npm install and retry update.

Documentation

• Create a SvelteKit frontend
• Marketplace API documentation

Development

npm install
npm test
npm pack --dry-run

The published tarball includes only the CLI, runtime source, README, license, starter templates, and package metadata.