EverShop platform help — open-source (GPL-3.0) Node.js/TypeScript/React/GraphQL eCommerce platform on PostgreSQL for developers and makers: products, variants, categories, carts, orders, customers, promotions, and checkout in one self-hosted project (storefront + admin + API together, not headless-only). Use when installing EverShop with create-evershop-app, building a REST or GraphQL integration, authenticating with JWT (admin /api/user/tokens, customer /api/customer/tokens, 15-minute token expiry, Bearer header), creating/updating products via REST while reading via GraphQL, wiring an order event to a CRM or warehouse since there are no native webhooks, fixing a failed npm build or Node-version error, fixing the server going unresponsive, or comparing EverShop to Medusa/Saleor/Vendure/Bagisto/Shopify. Do NOT use for cross-cart checkout-conversion strategy (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
EverShop platform help — open-source (GPL-3.0) Node.js/TypeScript/React/GraphQL eCommerce platform on PostgreSQL for developers and makers: products, variants, categories, carts, orders, customers, promotions, and checkout in one self-hosted project (storefront + admin + API together, not headless-only). Use when installing EverShop with create-evershop-app, building a REST or GraphQL integration, authenticating with JWT (admin /api/user/tokens, customer /api/customer/tokens, 15-minute token expiry, Bearer header), creating/updating products via REST while reading via GraphQL, wiring an order event to a CRM or warehouse since there are no native webhooks, fixing a failed npm build or Node-version error, fixing the server going unresponsive, or comparing EverShop to Medusa/Saleor/Vendure/Bagisto/Shopify. Do NOT use for cross-cart checkout-conversion strategy (use /sales-checkout) or picking a Merchant of Record for global tax (use /sales-merchant-of-record).
argument-hint
[describe what you need help with in EverShop — e.g. 'sync products in via the REST API' or 'notify my CRM on a new order without webhooks']
license
MIT
version
1.0.0
tags
["sales","checkout","ecommerce","platform"]
github
https://github.com/evershopcommerce
EverShop Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Figure out what the user actually needs before diving in:
Goal — installing/standing up a store, building/debugging an API integration, syncing products/orders to a CRM or warehouse, reacting to an order event, an install/build/ops problem, or a platform-selection decision?
Surface — REST API (writes: /api/products, /api/carts/..., /api/orders), GraphQL (reads), the event/subscriber system (instead of webhooks), the admin panel UI, or a custom extension/theme?
Auth — admin JWT (POST /api/user/tokens), customer JWT (POST /api/customer/tokens), or a token-refresh issue (the 15-minute default expiry)?
Hosting — self-hosted (you run Node 20+ + PostgreSQL 13+); there is no managed cloud yet.
Version — EverShop 2.x line (v2.1.2 as of mid-2026)? Node < 20 is unsupported.
Skip-ahead rule: if the prompt already says what they need, go straight to Step 2.
Step 2 — Route or answer directly
If the question is really a cross-platform strategy, hand off with the exact command:
If the user wants…
Route to
Checkout conversion / order bumps / cart-abandonment tactics across carts
/sales-checkout {question}
Whether to use a Merchant of Record for global VAT/sales tax
/sales-merchant-of-record {question}
Post-purchase / abandoned-cart email sequences
/sales-email-marketing {question}
Comparing EverShop against another commerce backend
/sales-checkout {question} (platform selection)
Otherwise it's an EverShop-specific question — answer it here.
Step 3 — EverShop platform reference
Read references/platform-guide.md for the full reference — modules and what's REST-write vs GraphQL-read vs event-only, pricing/infra posture, data model with JSON shapes, and quick-start recipes. For raw auth/endpoint/event detail, read .
references/evershop-api-reference.md
Answer using only the relevant section — don't dump the whole guide.
Step 4 — Actionable guidance
REST writes, GraphQL reads. Create/update/delete go through REST (POST /api/products, PATCH /api/products/{uuid}, /api/orders, /api/carts/...); reading data (list products, fetch an order) is GraphQL — there's no broad REST list/get surface. Address mutations by the resource uuid, not the integer id.
Auth is JWT and the admin token expires in 15 minutes. Get it from POST /api/user/tokens → {accessToken, refreshToken}, send Authorization: Bearer <token>. For long-running jobs, store the refresh token and call POST /api/user/token/refresh on 401, or raise JWT_ADMIN_TOKEN_EXPIRY. Endpoints are private by default (no access property = auth required).
There are no outbound webhooks. To notify a CRM/warehouse/Slack on an order, write an event subscriber (subscribers/order_placed/handler.ts, default-exported async fn) in an extension that fetch()es out — subscribers run async in-process, so you own retries/idempotency. Polling orders via GraphQL is the fallback when you can't deploy code.
It's self-host, and infra matters. Node 20+, PostgreSQL 13+, run under pm2/systemd with auto-restart; large catalogs want 8 GB+ RAM. Software is free (GPL-3.0), no per-sale fee; it is not a Merchant of Record (you own tax).
If you discover a gotcha or fix not in references/learnings.md, append it there with today's date.
Gotchas
Best-effort from research (2026-06) — re-verify Node/Postgres versions, token-expiry defaults, the event list, and that managed cloud is still unreleased against live docs.
No webhooks — events are in-process only. There is no UI to register a webhook URL. React to order_placed/product_created/inventory_updated/etc. with a code subscriber in an extension that makes the outbound call itself. Don't expect a Shopify-style webhooks page.
Reads are GraphQL, not REST. Integrators expecting GET /api/products get surprised — the REST surface is for writes; querying is GraphQL (URQL on the frontend).
Admin token expires in 15 minutes. Scripts that run longer must refresh the token (/api/user/token/refresh) or bump JWT_ADMIN_TOKEN_EXPIRY, or every call starts 401-ing mid-run.
Node < 20 breaks the build.npm run build failures (e.g. missing @babel/core, a TailwindLoader "use process(css).then(cb)" async-plugin error) are usually an unsupported Node version or a dirty install — use Node 20+ LTS and reinstall.
The server can go unresponsive over time. Reports of the process stopping responding every few minutes — run it under a process manager (pm2/systemd) with auto-restart, and watch memory on small boxes.
url_key/sku must be a clean slug. Product-create "must match pattern" errors come from spaces/uppercase/invalid characters — use lowercase hyphenated slugs.
Docker quick-start has no admin/data by default. After docker compose up, seed demo data (npm run seed) and create an admin (npm run user:create -- ...) or admin login won't work.
Related skills
/sales-checkout — Checkout-conversion strategy across carts (order bumps, upsells, cart-abandonment recovery) and platform selection.
/sales-medusa — Another open-source, self-hostable Node/TypeScript commerce engine (MIT) — but headless-only; compare if you want the engine separate from the storefront.
/sales-saleor — Open-source GraphQL-first headless commerce (Python/Django) with native outbound webhooks — compare against EverShop's no-webhook, in-process event model.
/sales-bagisto — Open-source Laravel/PHP commerce framework — the PHP-stack alternative to EverShop's Node stack.
/sales-shopify — The leading hosted commerce backend; compare against EverShop's self-hosted/open-source model.
/sales-merchant-of-record — Whether to use a MoR (Paddle, Lemon Squeezy) for global tax instead of self-managing (EverShop is not a MoR).
/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: Sync a product catalog in via the API (developer/automation)
User: "I'm writing a nightly script to push my product catalog into EverShop. Which API do I use and how do I handle auth?"
Approach: Use the REST API for writes. Get an admin token from POST /api/user/tokens ({email,password} → {accessToken, refreshToken}) and send Authorization: Bearer <token>. For each SKU, POST /api/products (new) or PATCH /api/products/{uuid} (update) — persist the returned uuid keyed by your SKU so updates address the right record, and keep url_key/sku as clean lowercase slugs to avoid "must match pattern" errors. Because the admin access token expires in 15 minutes, store the refresh token and call POST /api/user/token/refresh on a 401, or raise JWT_ADMIN_TOKEN_EXPIRY for the job. To read back the catalog (verify/export), query GraphQL, not REST.
Example 2: Notify a CRM when an order is placed without webhooks (developer/automation)
User: "Where do I add a webhook URL in EverShop so my CRM gets pinged on each new order?"
Approach: Explain EverShop has no outbound-webhook settings page — it has an in-process event system. Create an extension with subscribers/order_placed/notifyCRM.ts exporting a default async function that receives the order data and fetch()es your CRM endpoint; enable the extension, rebuild, restart. Subscribers run async in-process, so the call won't block checkout, but you own retries/idempotency/logging — for reliability, enqueue to Redis/BullMQ and process there. If you can't deploy code into the store, fall back to polling orders via GraphQL on a schedule, tracking the last-seen order_id.
Example 3: Choose EverShop vs other open-source commerce engines
User: "I'm a solo founder. Should I use EverShop, Medusa, or Bagisto for a small self-hosted store?"
Approach: All are free/no-per-sale-fee and self-hosted. EverShop ships storefront + admin + API in one Node/TypeScript project — fastest to stand up and run if you just want a working store and are fine on Node + Postgres; its trade-offs are thinner docs for multi-currency/large-scale B2B and no deep customization framework. Medusa (Node/TS, MIT) is a headless engine — more flexible (Workflows SDK, modules) but you build/deploy the storefront separately. Bagisto (Laravel/PHP) fits a PHP team and adds marketplace/POS/B2B extensions. Match to the user's stack and how much they want bundled vs composable; for cross-platform checkout-conversion or MoR-tax decisions, route to /sales-checkout or /sales-merchant-of-record. Re-verify current versions/pricing before committing.
Troubleshooting
"npm run build fails (missing @babel/core / TailwindLoader async-plugin error)"
Almost always an unsupported Node version or a dirty install. EverShop needs Node 20.x+ and NPM 9+. Check node --version, switch to a Node 20 LTS (e.g. via nvm), delete node_modules + lockfile, reinstall, then npm run build. The "Use process(css).then(cb) to work with async plugins" TailwindLoader error is the classic symptom of the wrong Node/toolchain.
"The store stops responding every few minutes"
Run EverShop under a process manager (pm2/systemd) with auto-restart so a hung process recovers, and watch memory — small boxes (2 GB) can starve, especially with larger catalogs (8 GB+ RAM recommended at 10k+ products). Reproduce with npm run start:debug to capture the error, ensure a single instance owns port 3000, and make sure PostgreSQL is reachable and on SSD.
"Product create returns 'must match pattern' / my API calls 401 mid-run"
Two common causes. (1) Validation:url_key and sku must be clean slugs — lowercase, hyphenated, no spaces or special characters; fix the value and retry. (2) Auth expiry: the admin access token expires in 15 minutes by default, so a long batch starts returning 401 — store the refreshToken from POST /api/user/tokens, call POST /api/user/token/refresh on 401 and retry once, or raise JWT_ADMIN_TOKEN_EXPIRY for server-to-server jobs. Remember endpoints are private by default, so a missing/expired Bearer token always 401s.
