@base44/app-plugin-commerce 0.8.3 → 0.8.4

package/README.md

@@ -85,12 +85,18 @@ From your existing Base44 app:
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
    See [`src/commerce/admin/README.md`](./src/commerce/admin/README.md) for the exact shadcn component list.
-5. **Mount the admin router** in your app:
+5. **Mount the admin** as a layout route in your app's `src/App.jsx` — Base44 discovers an app's pages by reading the literal `<Route>` JSX in that file, so the screens that should be listed as pages are declared there and the rest run off a splat handled by the kit's own router:
    ```jsx
-   import AdminApp from "@/commerce/admin";
+   import AdminApp, { AdminRoutes } from "@/commerce/admin";
    // inside your <Routes>:
-   <Route path="/store-admin/*" element={<AdminApp />} />
+   <Route path="/store-admin" element={<AdminApp />}>
+     <Route index element={<Dashboard />} />
+     <Route path="orders" element={<OrdersList />} />
+     {/* …products, customers, coupons, reports… */}
+     <Route path="*" element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
+   </Route>
    ```
+   Name the section they group under in `base44/ui.jsonc` (app-owned — edit in place): `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
 6. **Grant yourself the `admin` role** (Base44 dashboard → users, or `users.inviteUser(email, "admin")`). The admin UI refuses non-admins.
 7. **Seed the store.** Either open `/store-admin` and click **Initialize store defaults** on the first-run setup screen, or call `commerce/seed-store` directly — it creates the settings groups, the payment gateway rows (`offline` enabled, `card` off — enable it only with a provider wired) and — unless you pass your own `locations` — a fallback Shipping & Tax Location, plus the catalog: pass `products` (whole products with attributes — variants, categories, ribbons and taxonomy are created internally) or `with_sample_data: true` for the generic demo. Either way pass `store_name` (the app's name) — it is required on a first seed and becomes both the email subject prefix and the sender name. Once the `general` settings group exists the store counts as ready and the first-run screen stops appearing. Worked example: [`skills/commerce/install/03-data.md`](./skills/commerce/install/03-data.md); the full payload contract: [`skills/commerce/docs/api-admin.md`](./skills/commerce/docs/api-admin.md). Shipping zones are part of the same call — `locations` takes `continents: ["EU"]` and `rest_of_world: true`, so "€20 in Europe, €100 worldwide" is six lines.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@base44/app-plugin-commerce",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Base44 Commerce plugin — entities, backend functions, shared commerce engine, admin UI and the commerce skill, shipped as copyable source",
   "keywords": [
     "base44",

package/scripts/install.js

@@ -217,8 +217,10 @@
     "\n" +
     "  1. No deps to add: sonner, recharts and react-markdown ship with the default\n" +
     "     Base44 template — check package.json and npm i only what is truly missing\n" +
-    '  2. Mount the admin router: <Route path="/store-admin/*" element={<AdminApp />} />\n' +
-    "     plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
+    '  2. Mount the admin in src/App.jsx: <Route path="/store-admin" element={<AdminApp />}>\n' +
+    "     with the main screens as literal child <Route>s (that file is what the platform\n" +
+    '     discovers pages from) and <Route path="*" element={<AdminRoutes />} /> for the\n' +
+    "     rest, plus the mandatory /order-received route (useOrderReturn + your markup)\n" +
     "  3. Seed the store — one commerce/seed-store call (store_name required) takes the\n" +
     "     catalog, currency, shipping locations and payment methods\n" +
     "  4. CLI installs only: npx base44 agents push (the hosted runtime syncs agents on write)"

package/skills/commerce/SKILL.md

@@ -122,7 +122,7 @@ batch (above).
 
 | Topic | Open when | Size |
 |---|---|---|
-| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 6K |
+| [`install/01-install.md`](./install/01-install.md) | installing — routes you to 02 and 03 | 8K |
 | [`install/02-storefront.md`](./install/02-storefront.md) | building storefront pages | 38K |
 | [`install/03-data.md`](./install/03-data.md) | seeding catalog, shipping rates/zones, payments; re-callable per slice | 11K |
 | [`docs/entities.md`](./docs/entities.md) | any direct entity read/write ("which entity holds X") | 11K |

package/skills/commerce/install/01-install.md

@@ -1,9 +1,10 @@
 ---
 stage: install/01
 read_when: "The commerce kit's files were just copied into the app, or you are installing it now."
-skip_when: "The admin already mounts at /store-admin/* behind the shipped AuthGuard and / routes somewhere real."
+skip_when: "src/App.jsx already declares the admin's screens as literal <Route> JSX under a /store-admin layout route, and / routes somewhere real."
 forget_when: "The checklist at the bottom of this file passes (admin mounts, / routes somewhere real, /order-received exists)."
 carry_forward:
+  - "The admin's six picker-visible routes are literal <Route> JSX in src/App.jsx (the platform discovers pages by reading that file — an array or a .map() discovers nothing); the rest run off its <Route path=\"*\" element={<AdminRoutes />} />."
   - "Admin enforcement is three layers — AuthGuard (UI), admin-only entity RLS, requireAdmin() in every admin function. Never weaken any of them."
   - "/order-received must exist as a route: every payment link returns there, and confirming is what marks an order paid."
   - "The storefront header shows a visible \"Store manager\" link to /store-admin when the signed-in user's role is admin, and nothing for everyone else."
@@ -41,18 +42,33 @@ Image generation is the slowest step and nothing depends on it until seed time;
 
 The only dependency edges are *image URLs → seed payload* and *seed done → real products on the pages*.
 
-## Mount the admin router
+## Mount the admin
 
-```jsx
-import AdminApp from "@/commerce/admin";
-import { Navigate } from "react-router-dom";
+The admin mounts as a **layout route in the app's own `src/App.jsx`**: the six screens the store owner opens from the builder are declared there as literal `<Route>` JSX, and everything deeper goes to `<AdminRoutes />` on a splat. The platform discovers an app's pages by reading that file — a screen declared anywhere else is unreachable from the page picker.
 
-<Route path="/store-admin/*" element={<AdminApp />} />
+```jsx
+import AdminApp, { AdminRoutes } from "@/commerce/admin";
+import Dashboard from "@/commerce/admin/pages/Dashboard";   // …and orders/OrdersList,
+// products/ProductsList, customers/CustomersList, coupons/CouponsList, reports/Reports
+
+{/* Literal JSX — the platform reads this file, it never runs it. Do not refactor into a map. */}
+<Route path="/store-admin" element={<AdminApp />}>
+  <Route index            element={<Dashboard />} />
+  <Route path="orders"    element={<OrdersList />} />
+  <Route path="products"  element={<ProductsList />} />
+  <Route path="customers" element={<CustomersList />} />
+  <Route path="coupons"   element={<CouponsList />} />
+  <Route path="reports"   element={<Reports />} />
+  <Route path="*"         element={<AdminRoutes />} />   {/* editors, settings, webhooks */}
+</Route>
 <Route path="/" element={<Navigate to="/store-admin" replace />} />   {/* until a storefront exists */}
 <Route path="/order-received" element={<OrderReceived />} />          {/* mandatory — see below */}
 ```
 
-- **The `/*` splat is required** — without it every nested admin link 404s. Mounting elsewhere: `<AdminApp basePath="/backoffice" />` (prefix without the splat).
+- **Those seven lines, as they are.** The splat is what keeps the app's listed pages to six instead of 26: `path="*"` is skipped, so the editors, settings tabs and webhook screens stay navigable without appearing there, and `<AdminRoutes />` still serves the admin's own 404.
+- **Don't add `settings` to the list** — it is a tabbed layout around a nested route, so it only renders correctly from the splat.
+- **Elsewhere than `/store-admin`**: change the layout route's path and pass the prefix — `<AdminApp basePath="/backoffice" />`; the children are unchanged.
+- **Name the group** in `base44/ui.jsonc` — app-owned, so edit it in place, keep any other keys, never recreate a deleted one: `{ "version": 1, "sections": [{ "path": "/store-admin/*", "name": "Store Management" }] }`
 - **Give `/` something** — a blank app has no `/` route, and "page not found" at the app's own URL reads like a broken install.
 - **Link the admin from the storefront header** — otherwise the merchant has no way in but typing the URL. Resolve the signed-in user once (`base44.auth.me()`, rejection/no session = not an admin, never blocking the page) and render a plainly visible "Store manager" link to `/store-admin` in the header when `role === "admin"` — and nothing at all for everyone else.
 - **`/order-received` is mandatory**, even offline-only: every payment link returns there, and confirming is what marks an order paid — without it a paying customer hits a 404 and the order stays unpaid. The page is one hook, `useOrderReturn()` ([`./02-storefront.md`](./02-storefront.md)). A different path must be set in Settings → General (`general.order_received_path`).
@@ -69,7 +85,7 @@ Storefront functions are public on purpose (per-action verification, above). To
 
 ## Done — forget this file
 
-- [ ] `/store-admin/*` mounted with the splat, behind the shipped `AuthGuard`; the three enforcement layers untouched.
+- [ ] The `/store-admin` layout route is in `src/App.jsx` with its six literal `<Route>` screens and the `path="*"` → `<AdminRoutes />` splat; `base44/ui.jsonc` names the section; the three enforcement layers untouched.
 - [ ] `/` routes somewhere real; `/order-received` is a route.
 - [ ] The storefront header shows a visible `/store-admin` link to signed-in admins, and to nobody else.
 - [ ] Anonymous function invocation is allowed in the app's settings.

package/skills/commerce/install/02-storefront.md

@@ -50,7 +50,7 @@ import AdminApp from "@/commerce/admin";
       <Route path="/product/:slug" element={<ProductPage />} />
       {/* /bag, /checkout, and /order-received — which is mandatory */}
     </Route>
-    <Route path="/store-admin/*" element={<AdminApp />} />   {/* own chrome, outside the provider */}
+    <Route path="/store-admin" element={<AdminApp />}>…</Route>   {/* own chrome, outside the provider */}
   </Routes>
 </BrowserRouter>
 

package/src/commerce/admin/README.md

@@ -25,12 +25,20 @@ Tailwind + shadcn/ui + React Router) to get a full store back office.
    npx npq install <only the missing names>   # npq audits the package before npm installs it
    ```
 
-4. Mount the app in your router:
+4. Mount it as a layout route in the app's own `src/App.jsx` — that is the file
+   Base44 discovers an app's pages from, so the screens that should be listed as
+   pages are declared there literally, and the rest go to `<AdminRoutes />` on a
+   splat. The full step is the skill's `install/01-install.md`.
 
    ```jsx
-   import AdminApp from "@/commerce/admin";
-
-   <Route path="/store-admin/*" element={<AdminApp />} />
+   import AdminApp, { AdminRoutes } from "@/commerce/admin";
+
+   <Route path="/store-admin" element={<AdminApp />}>
+     <Route index element={<Dashboard />} />
+     <Route path="orders" element={<OrdersList />} />
+     {/* …products, customers, coupons, reports… */}
+     <Route path="*" element={<AdminRoutes />} />
+   </Route>
    // mounted elsewhere? → <AdminApp basePath="/backoffice" />
    ```
 
@@ -75,8 +83,8 @@ npx shadcn@latest add <component>
 ## Layout of this folder
 
 ```
-index.jsx        AdminApp: providers → auth guard → layout → routes
-routes.jsx       Route table + <AdminRoutes/>
+index.jsx        AdminApp: providers → auth guard → layout → <Outlet/>
+routes.jsx       Route table + <AdminRoutes/> (the splat handler App.jsx delegates to)
 layout/          AdminLayout, Sidebar, Topbar, AuthGuard (admin-role gate), AccessDenied
 bot/             StoreAdminBot (chat panel over the commerce/StoreAdmin agent), Markdown (GFM renderer)
 context/         SettingsContext (store settings + first-run seeding), BasePathContext

package/src/commerce/admin/index.jsx

@@ -1,4 +1,5 @@
 import React from "react";
+import { useOutlet } from "react-router-dom";
 import { Toaster } from "sonner";
 import AuthGuard from "./layout/AuthGuard";
 import AdminLayout from "./layout/AdminLayout";
@@ -6,27 +7,50 @@ import AdminRoutes from "./routes";
 import { SettingsProvider } from "./context/SettingsContext";
 import { BasePathProvider } from "./context/BasePathContext";
 
+export { default as AdminRoutes } from "./routes";
+
 /**
  * The store admin application.
  *
- * Mount inside your app's router:
- *   <Route path="/store-admin/*" element={<AdminApp />} />
+ * Mount it as a *layout route* in the app's own `src/App.jsx`: declare the few
+ * screens that should be listed among the app's pages there, as literal `<Route>`
+ * JSX, and hand everything deeper to `<AdminRoutes />` on a splat. Base44
+ * discovers an app's pages by reading that file rather than running it, so a
+ * route declared anywhere else is reachable by URL but never listed — and a
+ * splat is skipped by discovery, which is what keeps the editors and the
+ * settings tabs off the list while leaving them navigable.
+ *
+ *   <Route path="/store-admin" element={<AdminApp />}>
+ *     <Route index element={<Dashboard />} />
+ *     <Route path="orders" element={<OrdersList />} />
+ *     …
+ *     <Route path="*" element={<AdminRoutes />} />
+ *   </Route>
  *
  * If mounted somewhere other than /store-admin, pass the prefix:
- *   <Route path="/backoffice/*" element={<AdminApp basePath="/backoffice" />} />
+ *   <Route path="/backoffice" element={<AdminApp basePath="/backoffice" />}>
+ *
+ * The providers belong here, above the outlet, and must not be repeated per
+ * route: SettingsProvider fetches commerce.StoreSettings on mount, so wrapping
+ * each route would cost a round trip and a remounted sidebar on every admin
+ * navigation.
  *
  * Requires an authenticated user with role "admin" (enforced by AuthGuard,
  * and independently by entity RLS + requireAdmin() in backend functions).
  */
 export default function AdminApp({ basePath = "/store-admin" }) {
+  // Installs from before the routes moved into App.jsx mount the whole admin
+  // behind one splat route (`<Route path="/store-admin/*" element={<AdminApp />} />`)
+  // and declare no children, so nothing ever fills the outlet. Fall back to the
+  // kit's own router there rather than drawing an empty page area under the
+  // sidebar; those apps keep working until an agent rewrites their App.jsx.
+  const outlet = useOutlet();
   return (
     <BasePathProvider value={basePath}>
       <Toaster richColors position="top-right" />
       <AuthGuard>
         <SettingsProvider>
-          <AdminLayout>
-            <AdminRoutes />
-          </AdminLayout>
+          <AdminLayout>{outlet ?? <AdminRoutes />}</AdminLayout>
         </SettingsProvider>
       </AuthGuard>
     </BasePathProvider>

package/src/commerce/admin/lib/paths.js

@@ -1,8 +1,9 @@
 /**
  * Mount-path handling for the admin app.
  *
- * The admin is mounted with a splat route — `<Route path="/store-admin/*">` — and both
- * halves of that pattern leak into places they shouldn't: the `basePath` prop
+ * Installs from before the routes moved into App.jsx mount the admin with a splat
+ * route — `<Route path="/store-admin/*">` — and both halves of that pattern leak
+ * into places they shouldn't: the `basePath` prop
  * gets the pattern pasted in verbatim, and the literal URL `/store-admin/*` gets
  * opened (pattern copied into the address bar, or a nav link built from the
  * route table). Neither is a real page, so both are normalized here rather than

package/src/commerce/admin/routes.jsx

@@ -92,7 +92,20 @@ function UnmatchedRoute() {
   return isMountPatternPath(params["*"]) ? <Navigate to={href()} replace /> : <NotFound />;
 }
 
-/** All admin routes. Rendered inside AdminLayout; mount AdminApp at `/store-admin/*`. */
+/**
+ * Every admin route, matched relative to the mount point.
+ *
+ * The app's `src/App.jsx` declares the handful of screens that should be listed
+ * among the app's pages — discovery only sees literal `<Route>` JSX in that file —
+ * and sends the rest here on a splat: `<Route path="*" element={<AdminRoutes />} />`.
+ * A descendant `<Routes>` needs exactly that trailing splat to resolve against.
+ * The overlap is deliberate: a path declared in App.jsx wins there, and the same
+ * entry here keeps this table complete for anything App.jsx does not name —
+ * `orders/:id` and the settings tabs among them.
+ *
+ * With no splat and no children at all — an install predating the move into
+ * App.jsx — `index.jsx` renders this component directly instead.
+ */
 export default function AdminRoutes() {
   return (
     <Routes>