orionplace-react

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

Requires Node.js 20.9+ and a Node server deployment. Static export and edge-only hosting are not supported by this filesystem-based integration.

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.9+ and npm installed, run this from the parent folder; no existing Next.js project is needed:

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

The first command creates the Next.js configuration, App Router starter and integration README. The first frontend becomes the local MIMIC domain. Open the local URL printed by Next.js (normally 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 Next.js 16 project

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

The CLI preserves unrelated Next.js settings, scripts, and environment variables. It supports the App Router in app/ or src/app/, and never replaces your own layout.tsx, page.tsx, global styles or proxy.ts. Resolve an existing /api rewrite, redirect or catch-all route before setup. Projects using the Pages Router or output: 'export' require manual integration.

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-react init [directory]
npx orionplace-react update
npx orionplace-react set backend your-project.orionplace.app
npx orionplace-react add frontend shop.example.com
npx orionplace-react add frontend www.shop.example.com
npx orionplace-react remove frontend www.shop.example.com
npx orionplace-react set mimic shop.example.com
npx orionplace-react 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 | | --- | --- | | app/api/[...orionplace]/route.ts | Route handler serving /api/... from your project. | | app/layout.tsx | Awaits initialization and provides the marketplace store. | | app/page.tsx | Starter page showing the AppLoad state; replace it with your storefront. | | proxy.ts | Marks personalized pages private, no-store. | | lib/orionplace/ | Server transport, browser transport, envelope checks and domain resolution. | | stores/orionplace.ts | Typed snapshot, status, merged discovery and selectors. | | providers/OrionplaceProvider.tsx | One store per browser session, hydrated from the server render. | | hooks/useOrionplaceAppLoad.ts | Explicit initialize, refresh and reset actions. | | interfaces/orionplace/ | The AppLoad response envelope and every nested model. | | 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. |

Projects that use src/ receive the application source under src/ instead. 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-react 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 Next.js 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.

Browser requests use /api/.... Server components call the same gateway in process through 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 awaits POST /api/appload in light mode before the page renders, then hands the snapshot to the client provider. getOrionplaceAppLoad() is cached per render, so a layout and a server component share one request. Client components read the same snapshot through useOrionplace(selector); hydration does not repeat the request. useOrionplaceAppLoad() provides explicit initialize, refresh and reset actions. Reading the store or hook never starts a request, and initialization never opens an authentication prompt.

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.

The server render forwards the incoming cookies to the gateway. React Server Components cannot write response cookies, so a backend cookie created during that render is not relayed to the browser; the browser establishes and updates its own session through /api/... requests. requestAppLoad() returns the raw Set-Cookie values if you relay them from your own route handler or server action.

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-react 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-react/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-react 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 Next.js 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.