nextjs-commerce — Next.js 电商模板

SHA-256: 292f2246a7a634662539d7052d722e33740be9d8e053a6bfa0d2347e847d98b4

2026-10-14T19:44:41.848Z

## Shopify headless storefront template (Next.js App Router)

This repo is a **Shopify headless storefront template** built with Next.js App Router and the Shopify Storefront API.

Use it as a **GitHub Template Repository** to quickly spin up new storefronts (digital books, templates, apps, etc.) without copying code manually.

### What’s included

- **Core storefront**: products, collections, cart, checkout redirect
- **Shopify Pages**: pages are served at `/<handle>` (e.g. `/about`, `/contact`)
- **Contact page form**: `/contact` shows a simple “mailto” form (see `CONTACT_EMAIL`)
- **Blog**: `/blogs/<blogHandle>` and `/blogs/<blogHandle>/<articleHandle>`
- **Book preview**: for book products, show a “Preview sample pages” modal
- **Footer defaults**: appends common links (About, Contact, Privacy, Blog) when missing from the Shopify footer menu
- **Landing variants**: 3 home page variants switchable via `LANDING_VARIANT`

### Use this repo as a template (recommended)

1. On GitHub, go to **Settings → General → Template repository** and enable it.
2. Click **Use this template → Create a new repository**.
3. In the new repo, set environment variables and point it to the new Shopify store.

### Requirements

- **Node.js**: recent LTS
- **pnpm**
- **Shopify Storefront API access token** with content scope (blogs/articles) enabled

### Environment variables

Copy `.env.example` to `.env` and fill in at least:

- **`SHOPIFY_STORE_DOMAIN`**
- **`SHOPIFY_STOREFRONT_ACCESS_TOKEN`**

Optional:

- **`SITE_NAME`**, **`COMPANY_NAME`**
- **`SHOPIFY_REVALIDATION_SECRET`**: used by `POST /api/revalidate` (Shopify webhooks)
- **`CONTACT_EMAIL`**: recipient for the `/contact` mailto form
- **`LANDING_VARIANT`**: `professional` | `traditional` | `surprise` (default: `professional`)
- **`NEXT_PUBLIC_BLOG_PATH`**: blog link target used in the footer + landing CTAs (default: `/blogs/adpa`)

> Do not commit `.env`.

### Run locally

```bash
pnpm install
pnpm dev
```

Open `http://localhost:3000`.

### Setup / Health check page (developer-only)

This template includes a simple health check page at:

- `GET /health`

It is **not** linked in the storefront UI. Use it to verify env vars, menus, homepage collections, and blog access.

### New store checklist (Shopify admin)

#### 1) Collections used by the homepage

Create these Shopify collections (the template expects them):

- `hidden-homepage-featured-items` (at least 3 products)
- `hidden-homepage-carousel` (several products)

#### 2) Menus used by the theme

The template reads these menu handles from Shopify:

- Header: `next-js-frontend-header-menu`
- Footer: `next-js-frontend-footer-menu`

The footer will also append these paths if they’re missing:

- `/about`
- `/contact`
- `/data-sharing-opt-out`
- `NEXT_PUBLIC_BLOG_PATH` (defaults to `/blogs/adpa`)

#### 3) Pages

Create Shopify Pages with handles like:

- `about` → `/about`
- `contact` → `/contact`

#### 4) Blog

Create a Shopify blog (e.g. handle `adpa`) and publish posts:

- Blog index: `/blogs/<blogHandle>`
- Blog post: `/blogs/<blogHandle>/<postHandle>`

#### 5) Book preview pages (optional)

To show the preview button:

- Mark a product as a book with **Product type** `Book`/`Books` or tag `book`.
- Add sample-page images to product media and put **`[preview]`** in the image **alt text** to make them preview-only (excluded from the main gallery).

### Production

Deploy to your hosting (e.g. Vercel) and set the same environment variables there.