{"id":13486838,"url":"https://github.com/codekcv/headless-commerce","last_synced_at":"2025-03-27T21:31:11.385Z","repository":{"id":49210183,"uuid":"378582597","full_name":"codekcv/headless-commerce","owner":"codekcv","description":"An open-source pluggable full-stack headless commerce solution made with TypeScript, React, Node.js, and GraphQL.","archived":false,"fork":false,"pushed_at":"2021-07-27T14:05:07.000Z","size":4388,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-30T21:37:59.442Z","etag":null,"topics":["admin","antd","cms","graphql","nextjs","panel","react","reactjs","redux"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codekcv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-20T07:14:57.000Z","updated_at":"2022-06-06T15:20:28.000Z","dependencies_parsed_at":"2022-08-31T08:00:29.208Z","dependency_job_id":null,"html_url":"https://github.com/codekcv/headless-commerce","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codekcv%2Fheadless-commerce","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codekcv%2Fheadless-commerce/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codekcv%2Fheadless-commerce/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codekcv%2Fheadless-commerce/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codekcv","download_url":"https://codeload.github.com/codekcv/headless-commerce/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245927196,"owners_count":20695186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["admin","antd","cms","graphql","nextjs","panel","react","reactjs","redux"],"created_at":"2024-07-31T18:00:51.890Z","updated_at":"2025-03-27T21:31:11.370Z","avatar_url":"https://github.com/codekcv.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# headless-commerce\n[![Server CI/CD](https://github.com/codekcv/headless-commerce/actions/workflows/server.yml/badge.svg)](https://github.com/codekcv/headless-commerce/actions/workflows/server.yml) [![Client CI/CD](https://github.com/codekcv/headless-commerce/actions/workflows/client.yml/badge.svg)](https://github.com/codekcv/headless-commerce/actions/workflows/client.yml)\n\n_(No official name yet. This is still work in progress.)_  \nA pluggable headless E-commerce focused CMS solution for storefront websites that you can install as a package to give you a backend client that can live inside a protected route in your front-end for the merchant to access and manage their commerce content and view analysis.\n\n\u003c!-- [![Netlify Status](https://api.netlify.com/api/v1/badges/1c25043f-9715-4b31-b377-bffcf4fdfa65/deploy-status)](https://app.netlify.com/sites/kcv-admin-panel/deploys)\n\nThis is more of a Proof of Concept that developers can look/learn into and can serve for demo purposes as well. A bootstrap material too perhaps. Depending on what happens after I finish this, I might build another one that has real application; turning the client side of this into a package, and giving it extensible and modular components that plugs in the admin panel and connect to your own API.\n\n\u003e #### Update: I have plan on pivoting this into a headless CMS for a specific market. But for now, I will build as is to settle myself and of what stacks to use and weaving the architecture. --\u003e\n\nI do not plan on hosting a server option like other CMS. I only have this demo server above for demo purposes.\n\nYou will host the server similar to Strapi though most likely you already have a running instance of it if you're building a commerce application. I will provide a configuration option if you want to use a running server or serverless functions architecture.\n\n## DEMO (DEAD AT THE MOMENT. HEROKU DYNO LIMIT.)\n**Back-End Client**: https://kcv-admin-panel.netlify.app  \n`Username: demo` `Password: demo`\n\n**Back-End Server**: https://kcv-server-test.herokuapp.com/graphql  \n`Add access token to header after login` `{ \"Authorization\": \"Bearer {token}\" }`\n\n**Sample Storefront**: {...}  \n`To do`\n\n## How To Install\n\u003e Note: _Not yet published_  \n\n`npm install {@pkg-name}`  \nor  \n`yarn add {@pkg-name}`  \n\n### Usage Guide\n{To do}\n\n## How To Run Locally:\n1. `npm install`\n2. `npm run prisma:init`\n3. `npm start`\n\n**Prerequisites:**  \n1. _Provide environment variables._  \n2. _Running database server that [Prisma](https://www.prisma.io/docs/reference/database-reference/supported-databases) supports._\n\n**Environment Variables:**  \nServer - _DATABASE_URL_ | _ACCESS_TOKEN_SECRET_ | _REFRESH_TOKEN_SECRET_\n\n\u003e **Default ports** @ **client**: 3000 | **server**: 4000  |  **database**: 5432(docker) | **adminer**: 8080(docker)  \n\u003e **Note**: You may use [docker](https://www.docker.com/)-compose for containerized development database.  \n\u003e **Note**: Tokens are for authentication and keeping session. Authorization depends on if Admin or Super Admin.  \n\n**Security**:\nAccess token storage is in-memory and short lived. Refresh token in cookies + httpOnly, attached to the account in DB. This is the current strategy. Storing in local/session storage is vulnerable to attacks (e.g. XSS). Protection access to server is middleware level so it does not need to hit GraphQL server or database if unauthorized.\n\n## Technology Stack\n\n**Front-End Technologies**:  \n[TypeScript](https://www.typescriptlang.org/), [React](https://nextjs.org/), [Redux](https://redux-toolkit.js.org/), [Recharts](https://recharts.org/), [Ant Design](https://ant.design/), [React Hook Form](https://react-hook-form.com/), [Apollo Client](https://www.apollographql.com/docs/react/), [react-i18next](https://react.i18next.com/), [Jest](https://jestjs.io/), [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)\n\n**Back-End Technologies**:  \n[TypeScript](https://www.typescriptlang.org/), [Koa](https://koajs.com/), [Apollo Server](https://www.apollographql.com/docs/apollo-server/), [GraphQL](https://graphql.org/), [Nexus](https://nexusjs.org/), [Prisma](https://www.prisma.io/),  [PostgreSQL](https://www.postgresql.org/), [Redis](https://github.com/luin/ioredis), [JWT](https://jwt.io/), [GraphQL Shield](https://graphql-shield.vercel.app/)\n\n\u003c!-- ## Development\n**[WIP]** Since this is a monorepo structure, I'm using [Lerna](https://github.com/lerna/lerna) to handle the packages. We also don't want the CI to build everything everytime. Using CircleCI and setting up workflows for client or server that triggers on who had updated(I'm yet to write a bash script for this). When client workflow passes, it will deploy to Netlify through webhook. This is also good, saves time in CI building the client and move to another workflow or job. For server, it will be containerized with Docker and send the image to Heroku's container registry. Going to try github Actions too.\n\nI might switch to using serverless. Considering that GraphQL requests are exact, no underfetch or overfetching compared to RESTful, I think it's pretty sweet to call serverless functions with them. And not having to worry with scaling and provisioning server at start and focus first on the actual GraphQL API server and client interactions.\n\nI also use code-first approach in writing my GraphQL API using Nexus. Because it's type safe, predictable, and awesome.\n\n### Auth Strategy\nAuthentication with JWT. Try access -\u003e https://kcv-admin-panel.netlify.app/dashboard\n\nAuthorization -\u003e Middleware layer using GraphQL Shield. I'm yet to create Admin and Super Admin roles though.\n\nSession Maintain -\u003e Using access token + refresh token technique.  \n(_Access token is in-memory and short lived. Refresh token in cookies+httponly and longer expire date._) --\u003e\n\n## Project Tracker\n* **Front-End Tasks** - https://github.com/codekcv/admin-panel/projects/1  \n* **Back-End Tasks** - https://github.com/codekcv/admin-panel/projects/2  \n* **DevOps Tasks** - https://github.com/codekcv/admin-panel/projects/3\n\nDemo back-end client deployed on Netlify.  \nDemo back-end server deployed on Heroku.\n\n## QA\n**Q. Why not use CSS-in-JS or utility classes?**  \n**A**. I'm using Ant Design and some CSS Modules are enough to override style properties if needed. I will transition to using my own UI components using emotion and theme UI, but not soon.\n\n**Q. Why Redux and Apollo Client together?**  \n**A**. Apollo Client will handle network data states, but states for UI, session, settings, etc. goes to Redux. It's very robust and performant for managing global states.\n\n**Q. Why not use NestJS?**  \n**A**. NestJS was initially in the stack, but I removed. I want to use GraphQL Nexus as my code-first approach but it doesn't work well with NextJS' pattern.\n\n\u003c!-- **Q. Why PostgreSQL over MongoDB(noSQL)?**  \n**A**. --\u003e\n\n**Q. Why Prisma over TypeORM?**  \n**A**. Just my preference. I believe Prisma is the next-gen ORM for Node.js and TypeScript.\n\n**Q. Why Nexus over Type-GraphQL?**  \n**A**. Types are stronger and works well with Prisma. I also do not like the decorator syntax.\n\n\u003c!-- Q. Why not just use serverless functions?\nA. ... --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodekcv%2Fheadless-commerce","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodekcv%2Fheadless-commerce","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodekcv%2Fheadless-commerce/lists"}