{"id":20839635,"url":"https://github.com/chec/sanity-template-commercejs","last_synced_at":"2025-05-12T01:30:25.030Z","repository":{"id":43783240,"uuid":"421158298","full_name":"chec/sanity-template-commercejs","owner":"chec","description":null,"archived":true,"fork":false,"pushed_at":"2022-09-07T22:01:00.000Z","size":228037,"stargazers_count":6,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-23T14:42:47.057Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"sanity-template-commercejs.vercel.app","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"ko_fi":"ndimatteo"}},"created_at":"2021-10-25T19:28:32.000Z","updated_at":"2024-10-09T14:32:06.000Z","dependencies_parsed_at":"2023-01-17T23:15:24.093Z","dependency_job_id":null,"html_url":"https://github.com/chec/sanity-template-commercejs","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/chec%2Fsanity-template-commercejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chec%2Fsanity-template-commercejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chec%2Fsanity-template-commercejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chec%2Fsanity-template-commercejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chec","download_url":"https://codeload.github.com/chec/sanity-template-commercejs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253659137,"owners_count":21943605,"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":[],"created_at":"2024-11-18T01:14:04.265Z","updated_at":"2025-05-12T01:30:24.615Z","avatar_url":"https://github.com/chec.png","language":"JavaScript","funding_links":["https://ko-fi.com/ndimatteo"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"public/stralar-logo.svg\" align=\"center\" height=\"100\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eStarter built on \u003ca href=\"https://nextjs.org\" target=\"_blank\"\u003eNext.js\u003c/a\u003e\u003c/strong\u003e 🤘\u003cbr /\u003e\n  \u003cstrong\u003eCommerce backend powered by \u003ca href=\"https://commercejs.com/\" target=\"_blank\"\u003eCommerce.js\u003c/a\u003e\u003c/strong\u003e 🛍️\u003cbr /\u003e\n  \u003cstrong\u003eHeadless CMS powered by \u003ca href=\"https://sanity.io\" target=\"_blank\"\u003eSanity.io\u003c/a\u003e\u003c/strong\u003e ⚡\u003cbr /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"#-features\"\u003eFeatures\u003c/a\u003e •\n    \u003ca href=\"#-set-up\"\u003eSet up\u003c/a\u003e •\n    \u003ca href=\"#-spin-up\"\u003eSpin up\u003c/a\u003e •\n    \u003ca href=\"#-deployment\"\u003eDeployment\u003c/a\u003e •\n    \u003ca href=\"#-extrastips\"\u003eExtras\u003c/a\u003e\n\u003c/p\u003e\n\u003cbr /\u003e\n\n## What is Commerce.js?\n\nCommerce.js is a headless API-first commerce infrastructure for ultimate eCommerce control giving developers and businesses the freedom to innovate and grow. Built for modern commerce development, you can create custom product, cart, and checkout models with our lightweight, flexible, and extensible APIs.\n\n# ✨ Features\n\n- Utility-first CSS with [Tailwind CSS](https://tailwindcss.com)\n- Animations powered by [Framer Motion](https://www.framer.com/motion/)\n- Dynamic Page Routes for custom page creation\n- Live preview content directly from Sanity\n- Modern image component using Sanity's Hotspot, Crop, and automatic WEBP format\n- Modular page content for all pages, including dynamic grid layouts\n- SEO features:\n   - Page-level SEO/Share settings with previews\n   - Fallback global SEO/Share settings\n\n## Commerce.js features\n\n- Products and categories sync into Sanity studio using Chec webhooks\n- Product display pages with product information\n- Dynamic `/shop` category page with product grid\n\n\u003cbr /\u003e\n\n# 🏁 Getting started\n\n## Prerequisites\n\n- A [Sanity account](https://www.sanity.io/)\n- A Sanity project created using the [Sanity CLI](https://www.sanity.io/docs/getting-started-with-sanity-cli)\n- [Chec webhooks](https://dashboard.chec.io/settings/webhooks/add) for syncing products and categories\n- [Products](https://dashboard.chec.io/products/add) and [categories](https://dashboard.chec.io/categories/add) uploaded into the Chec dashboard\n\n## ⚙️ Manual set-up\n\nClone this repository from your GitHub account with the [Use this\ntemplate](https://github.com/chec/sanity-template-commercejs/generate) button.\n\n### 1) Sanity\n1. If you don't have the [Sanity CLI](https://www.sanity.io/docs/getting-started-with-sanity-cli) installed, first run\n   `npm install -g @sanity/cli` to install it globally\n2. `npm install \u0026\u0026 sanity init` in the `/studio` folder\n3. During Sanity's initalization it will warn you, type `Y` and hit `enter`:\n```\n? The current folder contains a configured Sanity studio. Would you like to reconfigure it? (Y/n)\n```\n4. When it asks you what dataset configuration to use, go with the `default`\n5. Add CORS Origins to your newly created Sanity project (visit: [manage.sanity.io](https://manage.sanity.io) and go to\n   Settings \u003e API):\n  - Add your Studio URLs **_with_** credentials: `http://localhost:3333` and `[subdomain].sanity.studio`\n  - Add your front-end URLs **_without_** credentials: `http://localhost:3000` and `https://[subdomain].vercel.app`\n\n\u003e ⚠️ **Important!** \u003cbr /\u003eFor \"singleton\" documents, like settings sections, the schema uses a combination of\n\u003e `__experimental_actions` and the new [actions resolver](https://www.sanity.io/docs/document-actions). If you are using\n\u003e this outside of the official Sanity Starter, you will need to comment out the `__experimental_actions` line in\n\u003e \"singleton\" schemas to publish settings for the first time. This is because a singleton is still a document type, and\n\u003e one needs to exist first before it can be edited. Additionally, if you want to create additional \"singleton\" schemas,\n\u003e be sure to edit the `singletons` array in the following file: `/studio/parts/resolve-actions.js`.\n\n### 2) Chec webhooks\n\nIn order for the products and categories to sync into Sanity, you will need to set up the neccessary webhooks for the\nproducts and categories endpoints in your Chec merchant account.\n\nGo to the [developer webhooks page and add the following webhooks](https://dashboard.chec.io/settings/webhooks/add):\n\n1. **Products**:\n  - Add the events `products.create`, `products.update`, `products.delete`\n  - Enter in the your Vercel URL (see note below) - `https://[subdomain].vercel.app/api/commerce/product-update`\n  - Make note of the signing key as you will need this into the environment variables in the below [Next.js set up steps](#3-nextjs)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://i.ibb.co/HqR7ZTr/products-webhooks.png\" alt=\"Products add webhook details\" align=\"center\" /\u003e\n\u003c/p\u003e\n\n1. **Categories**:\n  - Add the events `categories.create`, `categories.update`, `categories.delete`\n  - Enter in the your Vercel URL (see note below) - `https://[subdomain].vercel.app/api/commerce/category-update`\n  - Make note of the signing key as you will need this into the environment variables in the below [Next.js set up steps](#3-nextjs)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://i.ibb.co/1ZTsZJk/categories-webhooks.png\" alt=\"Categories add webhook details\" align=\"center\" /\u003e\n\u003c/p\u003e\n\nOnce you have added the webhooks for both products and categories and save them, you should see the following in your\n[webhooks list view](https://dashboard.chec.io/settings/webhooks).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://i.ibb.co/wwWv9Jr/webhooks-list.png\" alt=\"Webhooks list view\" align=\"center\" /\u003e\n\u003c/p\u003e\n\n\u003e ⚠️ **Note** \u003cbr /\u003eYou have to use a real domain name (no localhost). Be sure to use your Vercel project URL during\n\u003e development, and then switch to the production domain once live. You may not know your Vercel project URL until you\n\u003e deploy, feel free to enter something temporary, but make sure to update this once deployed!\n\n### 2) Chec products and categories\n\nThis starter template relies on the syncing of products and categories from Chec in order for the products and\ncategories data to be populated in Sanity studio (read-only) and for the products and categories to be displayed on the\nstorefront.\n\n1. Start adding categories with the minimum required category fields:\n  - Name\n  - Permalink\n\n2. Start adding products with the minimum required product fields:\n  - Name\n  - SKU\n  - Description\n  - Price\n  - Variants - at least one group with one option\n  - Custom permalink (in the SEO section at the bottom of the product page)\n  - Categories - assign the product to one or more categories\n\n### 3) NextJS\n1. `npm install` in the project root folder on local\n2. Create an `.env.local` file in the project folder, and add the following variables:\n```\n# Sanity project environment variables\nSANITY_PROJECT_DATASET=production\nSANITY_PROJECT_ID=XXXXXX\nSANITY_API_TOKEN=XXXXXX\n\n# Chec/Commerce.js environment variables\nNEXT_PUBLIC_CHEC_PUBLIC_KEY=XXXXXX\nCHEC_API_URL=api.chec.io\nCHEC_WEBHOOK_SIGNING_KEY=XXXXXX\n\n# Needed for Klaviyo forms):\nKLAVIYO_API_KEY=XXXXXX\n\n# Needed for Mailchimp forms:\nMAILCHIMP_API_KEY=XXXXXX-usX\nMAILCHIMP_SERVER=usX\n\n# Needed for SendGrid forms:\nSENDGRID_API_KEY=XXXXXX\n```\n3. Update all the `XXXXXX` values, here's where to find each:\n  - `SANITY_PROJECT_ID` - You can grab this after you've initalized Sanity, either from the `studio/sanity.json` file,\n    or from your Sanity Manage dashboard\n  - `SANITY_API_TOKEN` - Generate an API token for your Sanity project. Access your project from the Sanity Manage\n    dashboard, and navigate to: \"Settings\" -\u003e \"API\" -\u003e \"Add New Token\" button. Make sure you give `read + write` access!\n  - `NEXT_PUBLIC_CHEC_PUBLIC_KEY` - You can grab this from your Chec merchant account, under \"Developer\" -\u003e \"API keys \u0026\n    CORS\". _(Note: Use the public sandbox key for testing and when you're ready to go live, switch to the public live\n    key)_\n  - `KLAVIYO_API_KEY` - Create a Private API Key from your Klaviyo Account \"Settings\" -\u003e \"API Keys\"\n  - `MAILCHIMP_API_KEY` - Create an API key from \"Account -\u003e \"Extras\" -\u003e API Keys\n  - `MAILCHIMP_SERVER` - This is the server your account is from. It's in the URL when logged in and at the end of your\n    API Key\n  - `SENDGRID_API_KEY` - Create an API key from \"Settings\" -\u003e \"API Keys\" with \"Restricted Access\" to only \"Mail Send\"\n\n\u003cbr /\u003e\n\n# ⚡ Spin Up\n### Sanity (Back End)\n`sanity start` in the `/studio` folder to start the studio locally\n   - Your Sanity Studio should be running on [http://localhost:3333](http://localhost:3333)\n\nOnce you have added your products and categories in the Chec Dashboard and save them, you should expect to see all your products and categories listed under the shop tab and the data populated in the Sanity Studio fields.\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://cdn.chec.io/chec-assets/integrations/sanity/screenshot.png\" alt=\"Products listed in Sanity Studio\" align=\"center\" /\u003e\n\u003c/p\u003e\n\n### Next (Front End)\n`npm run dev` in the project folder to start the front end locally\n   - Your front end should be running on [http://localhost:3000](http://localhost:3000)\n\nYou will need to [build out the rest of the product modules](#-extrastips) to see the displayed data in the front-end. Once you’ve done that, you should be able to see your product display pages rendered like so:\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://cdn.chec.io/chec-assets/integrations/sanity/screenshot-2.png\"\n    alt=\"Products display page in Next.js front-end\" align=\"center\" /\u003e\n\u003c/p\u003e\n\n\u003cbr /\u003e\n\n# 🚀 Deployment\n\n### Vercel\nThis is setup to work seamlessly with Vercel, which I highly recommend as your hosting provider of choice. Simply follow\nthe on-screen instructions to setup your new project, and be sure to **add the same `.env.local` variables to your\nVercel Project**\n\n### Sanity\nThis is an easy one, you can simply run `sanity deploy` from the `/studio` folder in your project. Select a subdomain\nyou want; your Studio is now accessible from the web. This is where I'll invite the client to manage the project so they\ncan both add billing info and begin editing content.\n\n### Client Updates\nOnce you hand off to the client you'll want to give them the ability to generate builds when they make updates within\nthe Sanity Studio. The easiest way to do this is through this [Vercel Deploy\nplugin](https://github.com/ndimatteo/sanity-plugin-vercel-deploy).\n\n\u003cbr /\u003e\n\n# 🤘 Extras/Tips\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow are my Commerce products synced to Sanity?\u003c/strong\u003e\u003c/summary\u003e\n\nProducts get synced into Sanity through the following sequence:\n1. The products and categories webhooks are triggered in your Chec merchant from a product or category being created or updated.\n2. If the [webhooks are setup correctly](#2-chec-webhooks), it will send the product and category payloads to the API endpoints\n   `/api/commerce/product-update` and `/api/commerce/category-update` respectively.\n3. The sync function at your API endpoint will then update the product and category in Sanity.\n\n**Note**: You must have the webhook notifications setup to a live URL and not localhost. All Chec ENV variables must\nalso be added to the live hosting environment (e.g. Vercel).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eIs this a starter template?\u003c/strong\u003e\u003c/summary\u003e\n\nThis template is a starter that was bootstrapped off of the [HULL template](https://github.com/ndimatteo/HULL), injected with Commerce.js products and categories data. While this version of the project only contains the pre-checkout data from Commerce.js, it is a great starting point for you to include the already integrated cart actions and build out a checkout form.\n\nThe rest of the front end is rather opinionated and includes all the components you would need to flesh out additional pages, modules, and features. The decision that went into making this template (referenced from HULL author) was to achieve these goals:\n\n1. Use high-quality packages that don't get in the way\n2. Solve common UX problems and complex logic so you can focus on the fun stuff\n3. Create a more approachable starter for anyone looking to build headless experiences with a CMS and commerce backend\n\nExtracted component classes have been created not only for cleaner file structure, but also so you can easily work\nin your own styles exclusively within the styles folder. Feel free to extend or outright remove the applied styles for\nall of the components.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do I build out my front end using the Sanity studio?\u003c/strong\u003e\u003c/summary\u003e\n\nThis starter template is injected with a lot of features for front end display, you will just need to add the modules you\nneed in your Sanity studio. Once you have your studio spun up, you can start by going under:\n  - The Pages tab to create the 'Home Page', 'Shop All Page', 'Error Page', and 'Other Pages'.\n  - The Shop tab to fill in the Sanity content fields such as Gallery, Product Card, and other additional page modules.\n    The same goes for the Categories tab.\n\n  **Note**: Naturally, nothing will show up on the storefront until you add modules, grid, and input fields to the page.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWhat are extracted component classes and why should I use them?\u003c/strong\u003e\u003c/summary\u003e\n\nWhile utility-first CSS definitely speeds up your dev time, it can become overwhelming and untenable. This can make it\ndifficult to understand what a component is doing when shrouded in dozens of utility classes, especially for developers\ngetting familiar with a new codebase. Luckily, Tailwind offers the ability to [extract a\ncomponent](https://tailwindcss.com/docs/extracting-components), allowing you to compose custom utility patterns.\n\nThe nice thing about this is we can get all the benefits of writing in utility class shorthand, but without having to\nsift through all your javascript logic to adjust styles. This means writing our CSS is business as usual. You create\nstylesheets, but use Tailwind's `@apply` to create nice and succinct classes to push to your components.\n\nYou still get all the tree-shaking benefits of Tailwind, _and_ you can still use utility classes in your components when\nneeded; the best of both worlds!\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eError: Failed to communicate with the Sanity API\u003c/strong\u003e\u003c/summary\u003e\n\nIf you get this error in your CLI, you need to logout and log back in again. Simply do `sanity logout` and then `sanity\nlogin` to fix.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow do I properly hand-off a Vercel project to the client?\u003c/strong\u003e\u003c/summary\u003e\n\n1. Have the client create their own [Vercel account](https://vercel.com/signup)\n2. At the time of writing, Github connections can only be connected to one Vercel account at a time, so have the client\n   [create a Github account](https://github.com/join) if they don't already have one, and transfer the project repo to\n   them\n3. Delete the dev project from your own Vercel account (this is so the client can utilize the project name and domain\n   you were using during dev)\n4. You or the client can now connect their newly transferred Github repo to their own Vercel account!\n   \u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHow can I see the bundle size of my website?\u003c/strong\u003e\u003c/summary\u003e\n\nSimply run `npm run analyze` from the project folder. This will run a build of your site and automatically open the\n[Webpack Bundle Analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) visuals for your site's build\nfiles.\n\u003c/details\u003e\n\n\u003cbr /\u003e\n\n# 💯 Credits\nThis template was bootstrapped from the HULL project built by [@ndimatteo](https://github.com/ndimatteo)\n\n\u003cbr /\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchec%2Fsanity-template-commercejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchec%2Fsanity-template-commercejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchec%2Fsanity-template-commercejs/lists"}