Skip to content

Commit 411d370

Browse files
emwpemwp
authored
feature: Next.js Shopify e-commerce template (#293)
1 parent 5d0afe2 commit 411d370

File tree

116 files changed

+15953
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

116 files changed

+15953
-0
lines changed

Diff for: ‎starters/nextjs/shopify-ecommerce/.eslintrc.json

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"extends": ["next/core-web-vitals", "next/typescript", "prettier"],
3+
"rules": {
4+
"@next/next/no-img-element": "off"
5+
}
6+
}

Diff for: ‎starters/nextjs/shopify-ecommerce/.gitignore

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2+
3+
# dependencies
4+
/node_modules
5+
/.pnp
6+
.pnp.js
7+
.yarn/install-state.gz
8+
9+
# testing
10+
/coverage
11+
12+
# next.js
13+
/.next/
14+
/out/
15+
16+
# production
17+
/build
18+
19+
# misc
20+
.DS_Store
21+
*.pem
22+
23+
# debug
24+
npm-debug.log*
25+
yarn-debug.log*
26+
yarn-error.log*
27+
28+
# local env files
29+
.env*.local
30+
31+
# vercel
32+
.vercel
33+
34+
# typescript
35+
*.tsbuildinfo
36+
next-env.d.ts
37+
38+
vsce-debug.log*
39+
40+
# Firebase
41+
firebase-debug.log*
42+
firebase-debug.*
43+
.firebase

Diff for: ‎starters/nextjs/shopify-ecommerce/README.md

+223
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Project Documentation: Next.js/Shopify Ecommerce Template
2+
3+
## Project Overview
4+
5+
This project is a headless Shopify ecommerce template built with **Next.js**, the **Shopify Storefront API**, and **Firebase Data Connect**. It provides a seamless front-end experience, optimized performance, and integration with Shopify's backend services.
6+
7+
---
8+
9+
## Pages Documentation
10+
11+
### 1. **Authentication Page (`/auth`)**
12+
13+
- **Purpose**: User authentication and account creation.
14+
- **Features**:
15+
- Login and registration forms.
16+
- Integration with Shopify customer accounts via Shopify Storefront API.
17+
- **Technical Details**:
18+
- Uses GraphQL mutations for `customerAccessTokenCreate` and `customerCreate`.
19+
20+
### 2. **Home Page (`/`)**
21+
22+
- **Purpose**: Landing page displaying featured products and collections.
23+
- **Features**:
24+
- Dynamic product and collection rendering.
25+
- **Technical Details**:
26+
- Queries: `collections` and `products` from Shopify Storefront API.
27+
28+
### 3. **Product Page (`/product/[handle]`)**
29+
30+
- **Purpose**: Displays detailed information for a single product.
31+
- **Features**:
32+
- User reviews and ratings.
33+
- Review summaries generated using Google's Gemini AI
34+
- Semantic analysis of customer feedback
35+
- Real-time review aggregation
36+
- Product images, descriptions, variants, pricing, and inventory status.
37+
- Add-to-cart functionality.
38+
- Save variant selection to the URL search params for SEO and sharing purposes.
39+
- **Technical Details**:
40+
- Query: `productByHandle` from Shopify Storefront API.
41+
- Mutation: `cartLinesAdd`.
42+
- Mutation: `cartCreate`.
43+
44+
### 4. **Cart Page (`/cart`)**
45+
46+
- **Purpose**: Shows the user’s shopping cart.
47+
- **Features**:
48+
- List of added products, quantities, and prices.
49+
- Update and remove items from the cart.
50+
- **Technical Details**:
51+
- Query: `cart` by cart ID.
52+
- Mutations: `cartLinesUpdate` and `cartLinesRemove`.
53+
54+
### 5. **Checkout Page (`/checkout`)**
55+
56+
- **Purpose**: Finalizes the purchase process.
57+
- **Features**:
58+
- Displays cart summary and shipping details.
59+
- Redirects to Shopify's secure checkout.
60+
- **Technical Details**:
61+
- Uses the checkout URL generated for the cart.
62+
63+
### 6. **Orders Overview Page (`/orders`)**
64+
65+
- **Purpose**: Displays a list of past orders for the authenticated user.
66+
- **Features**:
67+
- Order summaries with statuses and total amounts.
68+
- **Technical Details**:
69+
- Query: `customerOrders`.
70+
71+
### 7. **Order Detail Page (`/order/[id]`)**
72+
73+
- **Purpose**: Detailed view of a single order.
74+
- **Features**:
75+
- Order items, shipping address, payment method, and status.
76+
- **Technical Details**:
77+
- Query: `order` by ID.
78+
79+
### 8. **Category Page (`/category/[handle]`)**
80+
81+
- **Purpose**: Displays products under a specific category or collection.
82+
- **Features**:
83+
- Paginated product listings.
84+
- Sorting and filtering options.
85+
- **Technical Details**:
86+
- Query: `collectionByHandle`.
87+
88+
---
89+
90+
## Shopify Admin Documentation
91+
92+
### **Products**
93+
94+
- Manage product listings including descriptions, images, pricing, and inventory.
95+
- Products added in the Shopify Admin will reflect dynamically on the front end.
96+
- We can provide a CSV import of products to the Shopify Admin to help with the onboarding process.
97+
98+
### **Collections**
99+
100+
- Organize products into categories or groups for better navigation and display.
101+
102+
### **Orders**
103+
104+
- Manage customer orders, including fulfillment, cancellations, and refunds.
105+
106+
### **Users**
107+
108+
- Handle customer accounts and permissions for staff members.
109+
110+
---
111+
112+
## Shopify Storefront API Documentation
113+
114+
- **Authentication**:
115+
- Secure API calls using access tokens.
116+
- **GraphQL Queries**:
117+
- `products`: Retrieves product data.
118+
- `collections`: Retrieves collection data.
119+
- `cart`: Fetches details about the shopping cart.
120+
- **GraphQL Mutations**:
121+
- `cartLinesAdd`: Adds items to the cart.
122+
- `checkoutCreate`: Initializes the checkout process.
123+
- `customerCreate`: Creates a new customer account.
124+
125+
---
126+
127+
## Data Connect Documentation
128+
129+
### **Overview**
130+
131+
- Data Connect is integrated to enhance search capabilities using **vector search** and **AI**-powered data querying.
132+
133+
### **Vector Search**
134+
135+
- Improves search relevance and precision by using product embeddings.
136+
- Examples:
137+
- Searching for "summer shoes" retrieves similar products based on semantic similarity.
138+
139+
### **AI Query Generation**
140+
141+
- The Firebase Data-Connect console includes an AI assistant to generate and optimize GraphQL queries and mutations.
142+
- Examples:
143+
- Auto-generated queries for frequently searched terms or product categories.
144+
- AI-optimized mutations for dynamic user interactions.
145+
146+
### **GraphQL Queries and Mutations Used**
147+
148+
- **Queries**:
149+
- `searchProducts`: Retrieves products based on user input.
150+
- `searchCollections`: Fetches collections matching keywords.
151+
- **Mutations**:
152+
- `cartLinesUpdate`: Updates cart item quantities.
153+
- `cartLinesRemove`: Removes items from the cart.
154+
155+
### Vector Search Capabilities
156+
157+
#### Product Search
158+
159+
- Name-based similarity search
160+
- Description-based semantic search
161+
- Review content similarity search
162+
163+
#### Implementation
164+
165+
---
166+
167+
## Technical Architecture
168+
169+
### Frontend
170+
171+
- Next.js 15.0.3
172+
- React 18
173+
- Tailwind CSS
174+
- Headless UI Components
175+
176+
### Backend Services
177+
178+
- Shopify Storefront API
179+
- Firebase Data Connect
180+
- Google Generative AI (Gemini)
181+
182+
### Authentication Flow
183+
184+
- Customer token-based authentication
185+
- Secure session management using cookies
186+
- Activation process for new accounts
187+
188+
---
189+
190+
## Development Setup
191+
192+
### Prerequisites
193+
194+
- Node.js 20+
195+
- Firebase CLI
196+
- Shopify Partner Account
197+
198+
### Environment Variables
199+
200+
Required environment variables:
201+
202+
- SHOPIFY_STORE_DOMAIN
203+
- SHOPIFY_STOREFRONT_ACCESS_TOKEN
204+
- FIREBASE_API_KEY
205+
- GOOGLE_API_KEY (for Gemini AI)
206+
207+
---
208+
209+
## Error Handling
210+
211+
### Authentication Errors
212+
213+
- Invalid credentials
214+
- Account activation failures
215+
- Session expiration
216+
217+
### API Errors
218+
219+
- Shopify API rate limits
220+
- Data Connect timeout handling
221+
- Vector search limitations
222+
223+
---

Diff for: ‎starters/nextjs/shopify-ecommerce/apphosting.yaml

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Settings for Backend (on Cloud Run).
2+
# See https://firebase.google.com/docs/app-hosting/configure#cloud-run
3+
runConfig:
4+
minInstances: 0
5+
# maxInstances: 100
6+
# concurrency: 80
7+
# cpu: 1
8+
# memoryMiB: 512
9+
# Environment variables and secrets.
10+
# env:
11+
# Configure environment variables.
12+
# See https://firebase.google.com/docs/app-hosting/configure#user-defined-environment
13+
# - variable: MESSAGE
14+
# value: Hello world!
15+
# availability:
16+
# - BUILD
17+
# - RUNTIME
18+
19+
# Grant access to secrets in Cloud Secret Manager.
20+
# See https://firebase.google.com/docs/app-hosting/configure#secret-parameters
21+
# - variable: MY_SECRET
22+
# secret: mySecretRef

0 commit comments

Comments
 (0)