create-cartbase 0.1.6 → 0.1.8

package/README.md

@@ -1,16 +1,21 @@
 # create-cartbase
 
 Scaffold a storefront on the [Cartbase](https://cartbase.net) commerce
-platform:
+platform. One input: your store's publishable key, handed out on the
+**Storefront** page of your Cartbase admin.
 
 ```bash
-npm create cartbase my-store
-# or, prefilled from your admin's Settings values:
-npm create cartbase my-store -- --url https://… --client-id … --key pk_…
+npx create-cartbase@latest my-store --key pk_…
+# or
+npm create cartbase my-store -- --key pk_…
+bun create cartbase my-store --key pk_…
 ```
 
 You get a working Next.js storefront wired to your store through
-`@cartbase/storefront`, with the **complete platform docs included in
-`docs/`** and a `CLAUDE.md` brief — hand the folder to a coding agent
-and it has everything it needs offline. Deploy with the
-[`cartbase`](https://www.npmjs.com/package/cartbase) CLI.
+`@cartbase/storefront`, styled, with the **complete platform docs
+included in `docs/`** and a `CLAUDE.md` brief. Hand the folder to a
+coding agent and it has everything it needs offline. `--url` points the
+app at a local or staging platform; without it the app talks to the
+platform. Deploy with the
+[`cartbase`](https://www.npmjs.com/package/cartbase) CLI: `cartbase login`,
+then `cartbase deploy`.

package/dist/index.js

@@ -7,6 +7,8 @@ function parseArgs(argv) {
     let dir;
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--")
+            continue;
         if (arg.startsWith("--")) {
             const name = arg.slice(2);
             const next = argv[i + 1];
@@ -33,16 +35,31 @@ function copyDir(from, to) {
             fs.copyFileSync(src, dest);
     }
 }
+function flag(flags, name) {
+    const v = flags.get(name);
+    return typeof v === "string" ? v.trim() : "";
+}
+/** The .env.local the scaffold writes: the key, plus overrides only when given. */
+function envFile(input) {
+    return [
+        "# Your store's publishable key — Cartbase admin, Storefront page.",
+        `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=${input.key}`,
+        ...(input.url ? [`NEXT_PUBLIC_CARTBASE_URL=${input.url}`] : []),
+        ...(input.clientId ? [`NEXT_PUBLIC_CARTBASE_CLIENT_ID=${input.clientId}`] : []),
+        "",
+    ].join("\n");
+}
 function main() {
     const { dir, flags } = parseArgs(process.argv.slice(2));
     if (!dir || flags.get("help") === true) {
         console.log(`create-cartbase — scaffold a Cartbase storefront
 
 Usage:
-  npm create cartbase <directory> [-- --url <api-origin> --client-id <uuid> --key <pk_…>]
+  npx create-cartbase@latest <directory> --key <pk_…>
 
-The three store inputs live in your Cartbase admin under Settings; given
-as flags they are written into .env.local, otherwise placeholders are.`);
+The key is your store's publishable key (Cartbase admin, Storefront page).
+Given as a flag it is written into .env.local; otherwise a placeholder is.
+--url points at a local or staging platform; the default is the platform.`);
         process.exitCode = dir ? 0 : 1;
         return;
     }
@@ -63,32 +80,23 @@ as flags they are written into .env.local, otherwise placeholders are.`);
         .replace(/[^a-z0-9-]+/g, "-")
         .replace(/^-+|-+$/g, "") || "cartbase-storefront";
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-    const url = typeof flags.get("url") === "string" ? flags.get("url") : "";
-    const clientId = typeof flags.get("client-id") === "string" ? flags.get("client-id") : "";
-    const key = typeof flags.get("key") === "string" ? flags.get("key") : "";
-    fs.writeFileSync(path.join(target, ".env.local"), [
-        "# Your store's inputs — Cartbase admin, Settings.",
-        `NEXT_PUBLIC_CARTBASE_URL=${url}`,
-        `NEXT_PUBLIC_CARTBASE_CLIENT_ID=${clientId}`,
-        `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=${key}`,
-        "",
-    ].join("\n"));
-    const filled = url && clientId;
+    const key = flag(flags, "key");
+    fs.writeFileSync(path.join(target, ".env.local"), envFile({ key, url: flag(flags, "url"), clientId: flag(flags, "client-id") }));
     console.log(`
 Created ${path.basename(target)}/
 
 Next steps:
   cd ${dir}
-  bun install        (or npm install)${filled
+  bun install        (or npm install)${key
         ? ""
         : `
-  → open .env.local and fill in your store's URL, client id and
-    publishable key (Cartbase admin, Settings)`}
+  open .env.local and paste your store's publishable key
+    (Cartbase admin, Storefront page)`}
   bun run dev
 
-The complete storefront reference is in docs/ — hand CLAUDE.md to your
-coding agent and it has everything. Deploy with the Cartbase CLI:
-cartbase login, then cartbase deploy.
+The complete storefront reference is in docs/ — hand CLAUDE.md (or
+AGENTS.md) to your coding agent and it has everything. Deploy with the
+Cartbase CLI: cartbase login, then cartbase deploy.
 `);
 }
 main();

package/package.json

@@ -1,21 +1,21 @@
-{
-  "name": "create-cartbase",
-  "version": "0.1.6",
-  "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "create-cartbase": "./dist/index.js"
-  },
-  "files": ["dist", "template"],
-  "scripts": {
-    "build": "node scripts/build-template.mjs && tsc -p tsconfig.json",
-    "prepack": "node scripts/build-template.mjs && tsc -p tsconfig.json"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "typescript": "^5"
-  }
-}
+{
+  "name": "create-cartbase",
+  "version": "0.1.8",
+  "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-cartbase": "./dist/index.js"
+  },
+  "files": ["dist", "template"],
+  "scripts": {
+    "build": "bun scripts/build-template.mjs && tsc -p tsconfig.json",
+    "prepack": "bun scripts/build-template.mjs && tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}

package/template/app/AGENTS.md

@@ -0,0 +1,35 @@
+# This is a Cartbase storefront
+
+A Next.js app wired to a Cartbase store through `@cartbase/storefront`
+(typed API client + UI components). It is the store's own starting point:
+the same files are already running on the store's permanent preview link,
+and the store's live address shows an "opening soon" page until the
+merchant publishes from their admin (Storefront in the sidebar).
+
+Everything you need is local:
+
+- **docs/** — the complete storefront reference (also at the store's docs
+  site): endpoints, shapes, auth, checkout orchestration, components.
+  Start with docs/BUILD-A-STOREFRONT.md.
+- **.env.local** — ONE input: the store's publishable key
+  (`NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY`). It names the store and scopes
+  the catalog; the merchant's Cartbase admin hands it out on the
+  Storefront page. The API origin is the platform's (a constant); the
+  store's id is not an input (`GET /api/store/store` answers it).
+- **Deploy** with the Cartbase CLI: `cartbase login` then
+  `cartbase deploy`. Every deploy lands on the same preview link; the
+  merchant publishes from their admin. `cartbase pull` fetches the
+  hosted source. Never commit .env.local.
+
+House rules: totals and prices are SERVER truth (render them verbatim);
+always pass a pricing context; consent before tracking; the store API is
+proxied same-origin via next.config rewrites.
+
+What you may change: **everything except payments.** Payments are the one
+thing that cannot be ejected. The cart and the checkout are yours to
+shape, and you should rarely need to eject them: both are built to be
+restyled through the theme tokens and their slots, which is the intended
+route and keeps you on our updates. Eject when tokens genuinely are not
+enough, and know what it means, because we say so at the moment you do
+it: that file leaves our support, stops receiving our fixes, and its
+safety is yours from then on.

package/template/app/CLAUDE.md

@@ -1,18 +1,35 @@
 # This is a Cartbase storefront
 
 A Next.js app wired to a Cartbase store through `@cartbase/storefront`
-(typed API client + UI components). Everything you need is local:
+(typed API client + UI components). It is the store's own starting point:
+the same files are already running on the store's permanent preview link,
+and the store's live address shows an "opening soon" page until the
+merchant publishes from their admin (Storefront in the sidebar).
+
+Everything you need is local:
 
 - **docs/** — the complete storefront reference (also at the store's docs
   site): endpoints, shapes, auth, checkout orchestration, components.
   Start with docs/BUILD-A-STOREFRONT.md.
-- **.env.local** — the three store inputs (API origin, client id,
-  publishable key). Missing values: ask the merchant to copy them from
-  their Cartbase admin under Settings.
-- Deploy with the Cartbase CLI: `cartbase login` then `cartbase deploy`
-  — you get a permanent preview URL; the merchant publishes from their
-  admin. Never commit .env.local.
+- **.env.local** — ONE input: the store's publishable key
+  (`NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY`). It names the store and scopes
+  the catalog; the merchant's Cartbase admin hands it out on the
+  Storefront page. The API origin is the platform's (a constant); the
+  store's id is not an input (`GET /api/store/store` answers it).
+- **Deploy** with the Cartbase CLI: `cartbase login` then
+  `cartbase deploy`. Every deploy lands on the same preview link; the
+  merchant publishes from their admin. `cartbase pull` fetches the
+  hosted source. Never commit .env.local.
 
 House rules: totals and prices are SERVER truth (render them verbatim);
 always pass a pricing context; consent before tracking; the store API is
 proxied same-origin via next.config rewrites.
+
+What you may change: **everything except payments.** Payments are the one
+thing that cannot be ejected. The cart and the checkout are yours to
+shape, and you should rarely need to eject them: both are built to be
+restyled through the theme tokens and their slots, which is the intended
+route and keeps you on our updates. Eject when tokens genuinely are not
+enough, and know what it means, because we say so at the moment you do
+it: that file leaves our support, stops receiving our fixes, and its
+safety is yours from then on.