Quick start
Requires Node 22.22+. No Docker, no clone, no database to install.
npx create-shopnex@latest my-shop
Open http://localhost:3000, follow the setup wizard, and your storefront is on http://localhost:4321.
- Add optional apps:
--with stripe,cj,shippo.
- Everything lives in the
my-shop folder (.env, embedded database in .pglite/). Delete it to start over.
- It's a trial setup. For production, set
DATABASE_URL to PostgreSQL or see the self-hosting guide.
What you get
- Admin: products, collections, orders, discounts, shipping, taxes, staff and settings in the browser
- Storefront: a bundled Astro storefront with Liquid themes, or bring your own through the typed REST Storefront API
- Hosted checkout: shipping rates, payment methods, discount codes, order confirmation
- Extensible: scoped API tokens, signed webhooks, embedded apps and an app marketplace. No third-party code in the core
- Multi-tenant: one shop by default, many with
TENANCY_MODE
- Yours: MIT licensed, no platform fees, all data in your own PostgreSQL
ShopNex is pre-1.0 and releases often. See the roadmap and releases.
Why I built this
I worked for two years at YUM Brands and learned how easy it is to build a system that's hard to manage, and how complex
e-commerce can get. We integrated with systems like DoorDash, and without a clear contract it was hard to make changes
without affecting the core.
In ShopNex I set a clear contract between the core and applications. Apps talk to it through an SDK and a bridge, with
scoped API tokens and signed webhooks.
Development
Requires Node (see .node-version), pnpm and PostgreSQL.
pnpm install
cp .env.example .env # set the database URL and app secret
pnpm db:migrate
pnpm dev # admin on :3000, storefront on :4321
Documentation
Guides live in apps/docs (pnpm dev:docs, http://localhost:3400). Developer reference is in docs/:
| Doc | Covers |
|---|
| Development | Env setup, pnpm dev options, local ports, OAuth sign-in, end-to-end tests |
| Architecture | Repository layout, API layout, admin routes, tenancy |
| Storefront API | Building an external storefront with @shopnex/storefront-sdk |
| Apps and marketplace | API tokens, building apps with @shopnex/app, embedded apps, marketplace |
| Webhooks | Topics, signatures, delivery and retries |
| Roadmap | What's done and what's next |
| Releasing | How to cut a release |
Community
Chat with the team and other users on Discord, or post questions and ideas in
GitHub Discussions.
Contributing
Issues and pull requests are welcome: see CONTRIBUTING.md. Report security issues privately,
as described in SECURITY.md.
See @shopnex/app for building apps with no database or OAuth code: authenticate,
Admin API, per-shop data, signed requests (@shopnex/app/store), and admin-styled UI (@shopnex/app/ui).
License
MIT
