orionplace-js

Set up a plain JavaScript storefront for your personal Orionplace marketplace API. The package includes a setup CLI, a small Node.js server that serves your static files and forwards /api requests to your backend, and browser modules with typed AppLoad initialization. There is no framework and no build step.

Requires Node.js 20.19+ and a Node server. Static-only hosting 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:

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

The first command creates the server, the starter page and the integration README. The first frontend becomes the local MIMIC domain. Open http://localhost:3000; 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 JavaScript project

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

The CLI preserves unrelated scripts and environment variables, and never replaces your own public/index.html, styles, public/js/app.js or editor configuration: it keeps your file and prints its path so you can merge the starter yourself. The project must use ES modules ("type": "module"). Projects that already depend on Nuxt, Next.js, SvelteKit, React, Vue, Svelte or Angular are refused: use that framework's Orionplace package instead.

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-js init [directory]
npx orionplace-js update
npx orionplace-js set backend your-project.orionplace.app
npx orionplace-js add frontend shop.example.com
npx orionplace-js add frontend www.shop.example.com
npx orionplace-js remove frontend www.shop.example.com
npx orionplace-js set mimic shop.example.com
npx orionplace-js 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 | | --- | --- | | server/index.mjs | Node.js server: static files plus the /api gateway. | | public/index.html | Starter page shell; replace it with your storefront. | | public/js/app.js | Renders the AppLoad state and wires the reload button. | | public/js/orionplace/appLoad.js | Browser request with timeout and abort. | | public/js/orionplace/appLoadResult.js | HTTP, form-error and bootstrap-envelope checks. | | public/js/orionplace/store.js | Snapshot, status, merged discovery, selectors and subscriptions. | | public/js/orionplace/index.js | One import for everything above. | | public/styles.css | Starter page styles. | | types/orionplace/ | The AppLoad response envelope and every nested model as .d.ts. | | jsconfig.json | Keeps the types in scope for editors; nothing is compiled. | | 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-js 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 the server after domain changes so it 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.

The server sends pages with Cache-Control: private, no-store and other files with no-cache, refuses paths outside the public directory, answers unknown files with 404, and falls back to the page only for extensionless client routes. PUBLIC_DIR, SITEMAPS_DIR, HOST and PORT select directories and the address.

AppLoad starter

This starter has no server-side rendering. The page is static and the browser initializes the marketplace once through the same-origin /api gateway, so the visitor's own request establishes the session. createOrionplaceStore() never starts a request by itself: initialize() loads once and does nothing when data is present, refresh() always reloads, and reset() clears everything and aborts pending work. Initialization never opens an authentication prompt, and a failure is stored rather than retried automatically.

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.

import { createOrionplaceStore, selectIsReady, selectProducts } from './orionplace/index.js';

const marketplace = createOrionplaceStore();
marketplace.subscribe(state => {
	if (selectIsReady(state)) console.log(selectProducts(state).length, 'products');
});
await marketplace.initialize();

The type declarations in types/orionplace/ are plain .d.ts files referenced from JSDoc comments, so editors provide completion without any compilation.

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.

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-js update

It runs the latest CLI, adds new template files, refreshes unchanged generated files, updates the package dependency and runs npm install. Edited files are preserved and listed in the output. Review their new versions under node_modules/orionplace-js/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 the server or redeploy after updating.

npx orionplace-js 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 JavaScript frontend
• Marketplace API documentation

Development

npm test
npm pack --dry-run

The tests import the shipped browser modules directly; no build or dev dependency is required. The published tarball includes only the CLI, runtime source, README, license, starter templates, and package metadata.