orionplace-nuxt

orionplace-nuxt

Set up a Nuxt 4 storefront for your personal Orionplace marketplace API. The package includes a Nuxt module, a setup CLI, and commented server source that is copied into your project alongside an integration README.

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

New project

Your personal backend domain is already provided in your account at orionmarket.place. You can change it there. Use that domain below and the public domain of your own storefront.

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

The first setup command creates the Nuxt configuration and app if needed. The final npm install installs the dependencies added to package.json. 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.

You can also scaffold before installing:

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

Existing Nuxt 4 project

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

The CLI preserves unrelated Nuxt settings, scripts, and environment variables. It supports a standard root nuxt.config.ts, .js, or .mjs with a literal configuration object and module array. Resolve existing /api proxy or catch-all conflicts before setup. Custom source/server directories, Nuxt layers, and dynamic configuration expressions 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-nuxt init [directory]
npx orionplace-nuxt update
npx orionplace-nuxt set backend your-project.orionplace.app
npx orionplace-nuxt add frontend shop.example.com
npx orionplace-nuxt add frontend www.shop.example.com
npx orionplace-nuxt remove frontend www.shop.example.com
npx orionplace-nuxt set mimic shop.example.com
npx orionplace-nuxt 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

The module executes the generated local runtime files. You can read and customize them. Later setup runs preserve edited runtime files and the project README, reporting which files were preserved. Unchanged generated files can be refreshed with npx orionplace-nuxt 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 to refresh Vite's allowed hosts and Nuxt's environment. 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.

Existing 0.1.0 setup state is migrated automatically, including other domain mappings recorded in its generated-file manifest.

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.

Browser requests use /api/.... For SSR, use Nuxt's useRequestFetch() to pass the current request's domain and authentication to the same gateway. See the project README for examples and cookie handling.

The module sets private runtimeConfig.mimicFrontDomain, adds domain Vary headers, extends Vite's allowed hosts from .cfg filenames, and defaults Nitro to node-server. It does not set a fixed public site URL or generate canonical links for your pages; use the resolved request domain for your own SEO metadata.

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.

Documentation

• Create a Nuxt frontend
• Connect your personal backend
• Marketplace API documentation

Development

npm install
npm test
npm pack --dry-run

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

AppLoad starter

The CLI generates an AppLoad debug app/app.vue, an SSR-aware useOrionplaceAppLoad() composable, validation helpers and the full nested TypeScript contract under app/interfaces/orionplace/. The first page loads POST /api/appload, shows request state and section counts, and supports reload. It preserves custom apps and edited generated files. Generated instructions in orionplace/README.md explain how to integrate the composable in an existing app.

Update an existing project

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

npx orionplace-nuxt 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-nuxt/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-nuxt 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.

For a project on 0.1.2 or older, bootstrap the new command once:

npx --yes orionplace-nuxt@latest update

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.