An e-commerce starter kit by TakeShape.
The easiest way to know if a tool is right for you is to see it in action. Check out the store now at https://penny-ecommerce.vercel.app/.
You can clone this repo with git to run the Next.js frontend locally (git clone https://github.com/takeshape/penny
).
To connect it to a GraphQL backend that TakeShape provides, just deploy the pattern in the .takeshape/pattern
directory. The instructions section of this README will teach you how to do that.
Category | Score |
---|---|
Path: / | Report |
🟢 Performance | 100 |
🟢 Accessibility | 100 |
🟢 Best practices | 100 |
🟢 SEO | 100 |
🟢 PWA | 100 |
Path: /product/__lighthouse | Report |
🟢 Performance | 100 |
🟢 Accessibility | 100 |
🟢 Best practices | 100 |
🟢 SEO | 100 |
🟢 PWA | 100 |
Path: /collection/__lighthouse | Report |
🟢 Performance | 100 |
🟢 Accessibility | 100 |
🟢 Best practices | 100 |
🟢 SEO | 100 |
🟢 PWA | 100 |
This starter project composes the following services into a unified GraphQL API:
- Shopify Admin and Storefront for customer data, product info and payment processing
- OpenID for identity management
- ReCAPTCHA for security
- Gorgias for customer support
- Klaviyo for newsletter subscriptions
- REVIEWS.io for product reviews
- Voucherify for customer loyalty rewards
- Ship Engine for shipping management
TakeShape is also providing performance and data services for the storefront:
- TakeShape's API Indexing speeds up product queries by 10x and enables lighting fast product search on the frontend
- TakeShape's ShapeDB hosts some of the custom content used in this build.
graph TD
A[Frontend Next.js Client] --> |Unified GraphQL API| Mesh{TakeShape's API Mesh}
Mesh --> |User Authentication| OpenID
Mesh --> |DDoS prevention| reCAPTCHA
Mesh --> P{Products}
P --> Shopify[Shopify Admin and Storefront]
Mesh --> UP{User Profile}
UP --> |Orders, Subscriptions, and Customer Data| Shopify
UP --> |Newsletter| Klaviyo
P --> |Product Reviews| REVIEWS.io
UP --> |Reviews Written| REVIEWS.io
UP --> |Shipping info| ShipEngine
UP --> |Loyalty Points| Voucherify
UP --> |Customer Support| Gorgias
The frontend codebase was built with many features that are important for modern composable e-commerce storefronts, including:
Here are the frameworks, language and styling options we went with for this build:
- Next.js to build the pages and bundle the frontend application
- NextAuth for user authentication against TakeShape and Shopify
- Tailwind UI for attractive components that are easy to customize
- TypeScript for type safety and documentation
- Apollo Client for efficient GraphQL queries against TakeShape
- Jotai for optimized component state management
- Storybook for rapid UI prototyping and review
Numerous CI tools have been configured with GitHub Actions. You'll have a starting point that is easy to test, and easy to keep error-free and performant.
- Jest for React component testing.
- ESLint for code style and quality.
- TypeScript ensures a type-safe codebase.
- GraphQL Codegen extend type-safety to all your GraphQL queries.
- Cypress for frontend end-to-end testing and API service mocking
- Lighthouse for SEO and browser performance metrics
IMPORTANT
If you have branch protections in place on your main
branch you will need to include a repo secret
PROTECTED_PUSH_TOKEN
that is a personal access token with the repo
scopes and which is an admin on the project repo.
If you are not using branch protection rules you can replace ${{ secrets.PROTECTED_PUSH_TOKEN }}
with
${{ secrest.GITHUB_TOKEN }}
in the lighthouse.yml
workflow file.
- Chromatic hosts Storybook stories and provides visual snapshot comparisons
- Sentry for error reporting and health monitoring with their Next.js-specific SDK.
We also used a few tools from TakeShape's ecosystem to simplify our workflow and improve the development process:
- Next-Auth-All-Access — A NextAuth wrapper that provides JWKS-verifiable access tokens for third-party APIs.
- @takeshape/graphql-validate — GraphQL query validation against your TakeShape API.
In the next section, you'll find a screenshot of the finished store's homepage.
Here are the steps for getting started with this project:
- Create a TakeShape project using the pattern in this repo. This button will deploy the project for you:
- Generate an
anonymous
and awebhook
TakeShape API key. You need these two API keys, and they must have different permissions scopes. Here's how to create them:
-
Navigate to the Settings tab in your TakeShape project's dashboard.
-
Select the API Keys option in the left sidebar.
-
Select the New API Key button at the top-right of the page.
-
Name the first API Key anything you want; just be sure to grant it
anonymous
permissions. -
Save the key somewhere. Later, you must either set it as the value of the
NEXT_PUBLIC_TAKESHAPE_ANONYMOUS_API_KEY
environment variable in your frontend project's.env.local
file, or set it as an environment variable in your hosting provider's UI. -
Do the same process, but this time create a key with
webhook
permissions. The environment variable for this key will beTAKESHAPE_WEBHOOK_API_KEY
.
- Get your TakeShape project's API Endpoint. Here's how:
-
Navigate to the Home tab of your TakeShape project's dashboard in the web client. Scroll down to the Useful Snippets section, and copy the API Endpoint there.
-
Save the endpoint somewhere. Later, you must either set it as the value of the
NEXT_PUBLIC_TAKESHAPE_API_URL
environment variable in your frontend project's.env.local
file, or set it as an environment variable in your hosting provider.
- Clone this repo:
git clone https://github.com/takeshape/penny
- Navigate to the project directory in your local terminal and run the
npm install
command to install all dependencies.
If you want to run this project locally, follow the instructions in the .env.test
file.
The following instructions will help you configure all of the services this project uses.
This project uses NextAuth in combination with the @takeshape/next-auth-all-access
package for user authentication. It
also uses OpenID for identity management. The following instructions will walk you through setting up OpenID as a
service provider in your TakeShape project, and configuring NextAuth with @takeshape/next-auth-all-access
.
-
In the Home tab of your TakeShape project, select OpenID from the list of services. You will be taken to the OpenID service configuration page.
-
Add your store's URL to the Issuer URL field, and enter the same URL with
/api/auth/all-access/.well-known/openid-configuration
appended to the end of it in the OpenID Configuration URL.Note: Your store URL should be the public-facing URL of your website, not necessarily your myshopify.com URL.
-
Copy the generated url in the Audience field and save it somewhere secure. You'll need it for your one of your project's environment variables.
-
Select the Save button at the top-right of the OpenID service page.
-
Now set up your environment variables. You can either do this in the
.env
file in your Next.js project's directory, or in your hosting provider's UI.
- Add a
NEXT_PUBLIC_TAKESHAPE_AUTH_AUDIENCE
variable with the generated Audience URL from your OpenID provider. - Add a
NEXT_PUBLIC_TAKESHAPE_AUTH_ISSUER
variable with the same URL you provided for the Issuer URL field on your OpenID provider. This should be your store's URL.
Use our @takeshape/next-auth-all-access
package to create and sign an access token for your logged-in users.
To generate your keypair, use the following command from the root of your project repo and follow the printed instructions.
npx @takeshape/next-auth-all-access generate-keys
You will then need to follow these steps:
-
Add the variable
ALLACCESS_PRIVATE_KEY
with your private key to your.env.local
file and to your hosting provider's environment. -
Commit the
./keys/jwks.json
file to your repo, push, and build. Your key will need to be web accessible at the URL you configured in TakeShape before authentication will work.
Warning! Connecting this project to a live Shopify store WILL enable real purchases. If you just want to play around without risking real charges, set your store's payments to Test Mode and use appropriately scoped Shopify API keys. When testing purchases, always use Shopify's accepted fake credit card information.
This project uses Shopify for e-commerce functionality. These instructions assume you've already created a Shopify store. You don't need to have Shopify Plus to use any of the features described here.
Follow these instructions to connect your Shopify store's Admin and Storefront APIs to both your TakeShape project and the frontend Next.js project.
-
Navigate to your store's admin site by visiting
https://your-store.myshopify.com/admin
, substituting "your-store" with the name of your store. -
Configure your Shopify checkout experience.
This project uses Shopify's checkout experience. That means when a customer is ready to purchase, they are redirected to a checkout flow that Shopify generates. The only downside is, shopify's checkout flow will send users to your shopify store, not your headless store, when they're done. To force Shopify's checkout experience to redirect to your headless storefront, you must use their Liquid templating language. These instructions show you how:
-
In your store's admin UI, select the ⚙ Settings button. A settings menu will appear. Select Checkout on the left.
-
Scroll down to the Order status page settings. In the Additional Scripts text area, add the following script. There are two URLs the order can possibly be redirected to. Be sure to add your store's root URL to the second one, under the
{% else %}
:{% if checkout.attributes.redirect_origin %} <script> window.location = "{{ checkout.attributes.redirect_origin }}/?shopify_checkout_action=success"; </script> {% else %} <script> window.location = "https://your-shopify-store.com/?shopify_checkout_action=success"; </script> {% endif %}
-
Save your changes.
The following instructions will show you how to configure your checkout process to work with this headless store. To configure these settings, stay in the Checkout section of the Settings menu in your store's admin UI.
-
Under Customer Accounts, select Accounts are optional. This allows customers to create checkouts as guests.
-
Under Customer Contact Method, select Phone number or email.
-
The Customer information settings can be changed to suit your needs. This is how we have it configured in our build:
- Full name: Only require last name
- Company name: Don't Include
- Address line 2 (apartment, unit, etc.): Optional
- Shipping address phone number: Don't include
-
Save your changes.
If you want to test this app without enabling real payments, it's best to set up test payments while you're in Shopify's admin UI. Follow Shopify's instructions for setting up test payments in your store.
- Get your Storefront API keys.
- In the navigation on the left side of your store's admin page, select Apps. A dropdown window should appear. Select ⚙ App and Sales Channel Settings as shown in the image below.
-
Select the Develop apps for your store button. On the next page, titled "App Development," select Create an app and name the app whatever you'd like.
-
You'll be taken to your app's settings page. Under the Overview tab, you'll see "Select your scopes to get started." Select Configure Storefront API scopes.
-
Enable the following scopes:
unauthenticated_write_checkouts
unauthenticated_read_checkouts
unauthenticated_write_customers
unauthenticated_read_customers
unauthenticated_read_product_listings
unauthenticated_read_selling_plans
unauthenticated_read_product_inventory
unauthenticated_read_product_tags
Then select Save at the top right of the page.
- Now select the API credentials tab. You'll see a section titled Access tokens. Select the Install app button within this section (not the button at the top-right).
- You'll be returned to your app's settings page, where you can select the "API Credentials" tab again. You will now see a Storefront API access token. Copy it and save it. You'll need it to configure Shopify Storefront in your TakeShape project.
To use Shopify with this project, you'll need to connect your Shopify Admin API and Shopify Storefront API as two separate services. The following instructions will help you connect your Shopify APIs to the Penny pattern, but you can connect Shopify to any TakeShape project by following the Shopify guide in our docs.
-
Navigate to your TakeShape project's dashboard and select the Home tab. Select the Shopify service.
-
Add your store's myshopify.com URL to the myshopify.com URL field. The format of the URL is your store's name + myshopify.com.
https://your-shop.myshopify.com
-
Select Save and complete the setup flow in the Shopify browser tab that opens up. If you've already connected TakeShape to this shop before, you may not have to do anything on Shopify.
-
After you complete the Shopify setup flow, you'll be taken to the API Indexing setup flow in TakeShape. Skip it. No further configuration is needed for Shopify Admin.
- Navigate to the Home tab of your TakeShape project.
- Select the Shopify Storefront service. It will be a generic GraphQL service, with the GraphQL logo.
- In the Endpoint field, enter your store's Shopify Storefront endpoint. It will be of this format:
https://[STORE_NAME].myshopify.com/api/2022-04/graphql.json
Here's what ours looked like when we set up this project in June of 2022:
https://deluxe-store.myshopify.com/api/2022-04/graphql.json
- For Authentication Type, select Bearer Token.
- In the Header field, enter
X-Shopify-Storefront-Access-Token
. - In the Token field, enter the Storefront API access token you copied from your store's myshopify.com/admin page.
You will also need to add your Shopify Storefront information to your .env
. This is all public information, and can be
included in the .env
file that is checked into the repo.
Add or update the lines NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN
and NEXT_PUBLIC_SHOPIFY_STOREFRONT_URL
in your .env
file.
Now your Shopify store is configured for this project.
The following section describes how to connect REVIEWS.io to your Penny pattern in TakeShape. To learn how to connect REVIEWS.io to any TakeShape project, check out our docs.
- First, you'll need your Store ID and API Key from REVIEWS.io
- Navigate to API integrations by clicking here, or follow the below instructions.
- On your REVIEWS.io dashboard, select Integrations in the navigation on the left. Select API in the list of integrations.
- Under API Credentials, copy and save the
Store ID
andAPI Key
-
Navigate to your TakeShape project's dashboard and select REVIEWS.io under the Services list in the Home tab.
-
Under Store ID, paste your Store ID, and under API Key, paste your API Key. Save your service.
You'll need the Trustpilot Connect add-on module to proceed. To check if you have it, check if "APIs" is available under Integrations > Developers in the Trustpilot business site.
- First, you'll need your business profile name. Go to your business settings and make note of the name next to the text "Profile settings:"
- Second, you'll need an API Key. Either create an application or select an existing application, then copy the API key for the application.
- Now use the API key to find your business unit ID. The easiest way is to run this command in your terminal after replacing YOUR_API_KEY with your API Key and PROFILE_NAME with your business profile name from the previous steps.
curl --request GET \
--url 'https://api.trustpilot.com/v1/business-units/find?apikey=YOUR_API_KEY&name=PROFILE_NAME'
- In the JSON response the business unit ID is the value for the
id
property.
- Edit your
.env
file and set your business unit ID as the value forNEXT_PUBLIC_TRUSTPILOT_BUSINESS_UNIT
. - Edit
src/config/ecommerce.ts
and setenableTrustpilot
totrue
. - On your TakeShape project's dashboard, navigate to the Home tab and select Trustpilot from the list of services. You'll be taken to the Generic REST service page for Trustpilot.
-
In the Authentication Type field, ensure Query Parameter is selected.
-
Under Authentication, add
apikey
in the Query Param field, and your API Key in the Token field. -
Select the Save button at the top-right of the page.
- After completing these steps, Trustpilot reviews for the matching SKU are shown on the product page.
The client frontend project supports the shipping information added to the Shopify graph by the ShipEngine Shopify Application. All you need to do is connect ShipEngine to your Shopify store in the Shopify admin and you're set!
The following section describes how to connect Voucherify to your Penny pattern in TakeShape. To learn how to connect Voucherify to any TakeShape project, check out our REST provider docs. Using our generic REST provider, you can connect most arbitrary REST APIs, including Voucherify.
- Get your
Application ID
from Voucherify.
- From your Voucherify dashboard, select Project Settings → Application Keys. Create your keys. You will be given an
Application ID
and aSecret Key
.
-
Navigate to your TakeShape project's dashboard and select Voucherify under your services list.
-
Under Authentication, set the Header to
X-App-Id
and the Token to your App ID. Save your service. -
Connect Vourcherify to your Shopify store in the Shopify admin and your purchases will be applied to your customer accounts, and will be available via the
getMyLoyaltyCard
query.
The following section describes how to connect Klaviyo to your Penny pattern in TakeShape. To learn how to connect Klaviyo to any TakeShape project, check out our docs.
- First, get your api key for Klaviyo.
- Log into your Klaviyo account and navigate to Account → Settings → API Keys.
-
On your TakeShape project's dashboard, navigate to the Home tab and select Klaviyo from the list of services.
-
In the Authentication field, add your Klaviyo API key, and select the Save button at the top-right of the page.
-
Be sure to set the
NEXT_PUBLIC_DEFAULT_KLAVIYO_LIST_ID
to the ID of your preferred Klaviyo newsletter, either in a.env
file or in your hosting provider.
The following section describes how to connect reCAPTCHA to your Penny pattern in TakeShape using a generic REST provider. To learn how to connect ReCAPTCHA to any TakeShape project, check out our docs on using a generic REST service.
Don't want to use captcha? Captcha can be disabled in the client by removing
NEXT_PUBLIC_RECAPTCHA_SITE_KEY
from the env. The Takeshape API will still require Captcha unless the Captcha compose step and"if": "$resolvers.recaptcha.success == true"
is removed from the relevant mutations in the project schema. Check out our docs on editing a TakeShape project schema.
Because reCAPTCHA is tied to a specific host in the Google settings you will either need to use a custom domain and allow a wildcard subdomain for your preview builds, e.g.,
*.mysite.com
allowspreview-acbiou43891239.mysite.com
or use an environment that disables recaptcha for your preview builds and remove the step above from your TakeShape project schema.
- First, get your Site Secret from reCAPTCHA. If you need to create an account, you can visit Google's ReCAPTCHA site registration page here.
- Log into Google's reCAPTCHA admin and select your site. Select the Settings gear icon at the top-right of the page ⚙.
- On the Settings page, select the reCAPTCHA keys dropdown to reveal your Site Key and Secret Key. Copy them somewhere secure, or leave this tab open. You'll need them to connect reCAPTCHA to your TakeShape project.
-
Create a
NEXT_PUBLIC_RECAPTCHA_SITE_KEY
environment variable in your hosting provider or in your.env
, and set the value to your Site Key from the reCAPTCHA settings. -
Navigate to your TakeShape project's dashboard, select the Home tab and select ReCAPTCHA from the list of services. You'll be taken to the ReCAPTCHA service page.
-
In the Endpoint field, enter
https://www.google.com/recaptcha/api
. -
In the Authentication Type field, ensure Query Parameter is selected.
-
Under Authentication, enter
secret
as the value for the Query Param field. Enter your Site Secret as the value for the Token field. -
Select the Save button at the top-right of the page.
The following section describes how to connect Gorgias to your Penny pattern in TakeShape. To learn how to connect Gorgias to any TakeShape project, check out our REST provider docs. Using our generic REST provider, you can connect most arbitrary REST APIs, including Gorgias.
- You'll need your Gorgias API Endpoint, email address, and a Password API Key. Gorgias uses Basic Auth, which takes a username and password. Your username will be your Gorgias account email address, and your password will be a generated key from Gorgias.
-
Navigate to your Gorgias dashboard and select the three dots at the top-left. The button will be labeled Ticket if you're in the Ticket view of the dashboard, but will change its label based on which view you're in. In the drop-down menu that appears, select Settings. You should be taken to the Settings view.
-
In the Settings view, select the REST API option in the menu on the left. You'll see the REST API panel. Note the Base API URL. You'll need that to connect Gorgias to TakeShape.
-
Select the Create API Key button under the Password (API Key) heading.
-
Leave this tab open, or copy your Base API URL, Username, and Password over to a secure location. It's time to set up Gorgias in TakeShape.
- On your TakeShape project's dashboard, navigate to the Home tab and select Gorgias from the list of services. You'll be taken to the Generic REST service page for Gorgias.
-
In the Endpoint field, add your Base API URL.
-
In the Authentication Type field, ensure Basic Auth is selected.
-
Under Authentication, add your email address in the Username field, and your API Key in the Password field.
-
Select the Save button at the top-right of the page.
The following section describes how to connect Zendesk to your Penny pattern in TakeShape. To learn how to connect Zendesk to any TakeShape project, check out our REST provider docs. Using our generic REST provider, you can connect most arbitrary REST APIs, including Zendesk.
- On your TakeShape project's dashboard, navigate to the Home tab and select Zendesk from the list of services. You'll be taken to the Generic REST service page for Zendesk.
- In the Endpoint field, add your Zendesk domain. This is the domain you use to access the Zendesk Admin Center
(e.g.,
https://your-store.zendesk.com
). - Select the Save button at the top-right of the page.
Zendesk allows for the creation of up to 5 requests per hour without the need for authentication. If you need to handle a larger volume of requests, options include authenticating end users with Zendesk and using the same Requests endpoint or using the Tickets endpoint as an authenticated Zendesk agent.
To use Sentry with this project, you need your project's Data Source Name, as well as your sentry org slug and project name.
If you don't want to use Sentry do not set the
NEXT_PUBLIC_SENTRY_DSN
environment variable and it will not be loaded.
- Find your Sentry DSN.
-
Log into Sentry, and select your project. If you don't have a sentry project ready, create a Next.js project.
-
Select Settings in the sidebar on the left, and scroll down to select Client Keys (DSN). You will see the Client Keys panel.
- Save your DSN. You can set it in your
.env.local
or your hosting provider's UI as theNEXT_PUBLIC_SENTRY_DSN
variable.
- Find your sentry org slug.
-
Head to Settings, then General Settings. At the top of the page you should see Organization Slug. Copy the value there.
-
Set this value in your
.env.local
or your hosting provider's UI as theSENTRY_ORG
variable.
- Find your sentry project name.
-
Head to Settings, then Projects. You'll see a list of projects. Select the Next.js project you want to use.
-
Under the Project Details section on the next page, you'll see a Name field. Copy that value.
-
Set the value from the Name field to the
SENTRY_PROJECT
variable in your.env.local
or your hosting provider's UI.
For Shopify Plus users, this project supports sign in with Google, in addition to the regular Shopify sign in. To set it
up you need to provide the secret env vars SHOPIFY_MULTIPASS_SECRET
, GOOGLE_CLIENT_ID
, GOOGLE_CLIENT_SECRET
, and
set the public env var NEXT_PUBLIC_SHOPIFY_USE_MULTIPASS='true'
. Because we're using
NextAuth.js it's very easy to support almost any identity provider via a simple import in
pages/api/[...nextauth].ts
and following the configuration instructions from Next Auth for that provider.
Because of how the Google OAuth2 service works, you cannot use wildcard callback urls. This precludes the easy use of
Google auth in Vercel preview environments, which use dynamic URLs. It is recommended you unset
NEXT_PUBLIC_SHOPIFY_USE_MULTIPASS
for preview environments and configure it on a case-by-case basis.
- Copy the
.env.local-example
file to.env.local
and follow the instructions. - Copy the
.env-example
file, overwriting the.env
file, and follow the instructions.
Your project is configured to generate types for the GraphQL APIs in use. Run npm run graphql:typegen
before running
the site locally to generate query-specific types. This is a big advantage of the TakeShape GraphQL mesh — you will have
your queries and responses fully typed, and can develop efficiently and safely.
When deploying this project to production, be sure to replace all public placeholder assets.
When building this project, we chose Vercel to host the frontend.
Vercel is the company that created Next.js, and they have useful github workflow tools for projects like this. We integrated their deploy preview functionality into our workflow, which allowed Vercel to generate a preview build of the site for every pull request we created. That allowed us to see what the PR's changes would look like in production before we merged them to our main branch.
To learn more about deploying with Vercel, check out their comprehensive guide.
Netlify is a popular alternative that you can also check out. They offer a similar deploy preview tool.
To learn more about deploying with Netlify, check out their comprehensive guide.
If you are using the included workflows you will get a great CI process, that includes:
- Unit tests on every PR
- Cypress E2E Testing on every PR
- Storybook deploys and testing with Chromatic
- Automated Lighthouse scores on every PR and on production deploys
If you use the automated Lighthouse (Production) workflow, you must add the following to your Vercel
Ignored Build Step
settings, otherwise you'll end up with an infinite prod deploy loop:
In Project Settings > Git
add to Ignored Build Strp
this command:
bash scripts/ignore-build.sh
-
Components with state coming from localstorage via Jotai's
atomWithStorage
should be wrapped in the<ClientOnly />
component. This prevents rendering mismatches and stale / incorrect info. -
The Shopify store is configured to redirect after checkout via the "Additional scripts" field (see the docs) for the order status page and uses the
redirect_origin
attribute set at cart creation: -
Shopify must use the
2022-07
endpoint, like this:
Admin API:https://shopify-shop-name.myshopify.com/admin/api/2022-07/graphql.json
Storefront API:https://deluxe-sample-project.myshopify.com/api/2022-07/graphql.json
{% if checkout.attributes.redirect_origin %}
<script> window.location = "{{ checkout.attributes.redirect_origin }}/?shopify_checkout_action=success"; </script>
{% else %}
<script> window.location = "https://your-shopify-store.com?shopify_checkout_action=success"; </script>
{% endif %}
- Captcha can be disabled in the client by removing
NEXT_PUBLIC_RECAPTCHA_SITE_KEY
from the env. The Takeshape API will still require Captcha unless the Captcha compose step and"if": "$resolvers.recaptcha.success == true"
is removed from the relevant mutations in the project schema.
- This project uses credit card icons from svg-credit-card-payment-icons