astro-medusa-starter - GitLite

KO | EN

gitlite — search

#react #typescript #golang #android #rust #deep-learning #linux #nodejs #java #vue #awesome-list #pytorch #security #open-source

astro-medusa-starter

(★ 99)

Astro + Medusa starter for e-commerce. Optimized to the core.

파일 탐색기

최종 버전 다운로드 (.zip)

- - architecture.md
  - astro-conventions.md
- - project-rules.mdc
- - deploy-to-cloudflare-workers.yml
- extensions.json
- launch.json
- settings.json
- .assetsignore
- _headers
- favicon.ico
- favicon.svg
- - hero.png
- - Layout.astro
- - sdk.ts
- - global.css
- - global.ts
- middleware.ts
.env.example
.gitignore
.prettierrc
.yarnrc.yml
astro.config.mjs
CLAUDE.md
eslint.config.js
LICENSE
package.json
README.md
tsconfig.json
wrangler.jsonc
yarn.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/Bystrol/astro-medusa-starter

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd astro-medusa-starter

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

yarn

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

yarn dev # Start dev server on localhost:8000

개발/실행 서버를 켭니다.

yarn build # Build for Cloudflare Workers

배포용으로 코드를 최적화해서 빌드 파일을 생성합니다.

yarn preview # Preview the production build locally

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Astro Medusa Storefront

A blazing-fast, open-source ecommerce storefront built with **Astro**, **React**, and **Medusa v2** — deployed to the edge on **Cloudflare Workers**.

Static-first architecture. Interactive where it matters. Zero compromise on performance.

## Tech Stack

| Layer      | Technology                                                                               |
| ---------- | ---------------------------------------------------------------------------------------- |
| Framework  | [Astro 6](https://astro.build) — static HTML, islands of interactivity                   |
| UI         | [React 19](https://react.dev) — only where you need it                                   |
| Styling    | [Tailwind CSS v4](https://tailwindcss.com) — zero-config Vite plugin                     |
| Backend    | [Medusa v2](https://medusajs.com) — headless commerce engine                             |
| Payments   | [Stripe](https://stripe.com) — secure checkout                                           |
| State      | [Nanostores](https://github.com/nanostores/nanostores) — tiny, framework-agnostic stores |
| Forms      | [React Hook Form](https://react-hook-form.com) + [Zod](https://zod.dev) validation       |
| Deployment | [Cloudflare Workers](https://workers.cloudflare.com) — edge-first                        |

## Architecture

```
┌─────────────────────────────────────────────────┐
│                Cloudflare Workers                │
│                                                 │
│   ┌──────────┐  ┌──────────┐  ┌──────────────┐  │
│   │  Static  │  │  Astro   │  │    React     │  │
│   │   HTML   │──│Middleware│──│   Islands    │  │
│   │  (SSG)   │  │ (Region) │  │ (Cart, Nav)  │  │
│   └──────────┘  └──────────┘  └──────┬───────┘  │
│                                       │         │
└───────────────────────────────────────┼─────────┘
                                        │
                              ┌─────────▼─────────┐
                              │   Medusa v2 API   │
                              │  (Your backend)   │
                              └─────────┬─────────┘
                                        │
                              ┌─────────▼─────────┐
                              │      Stripe       │
                              └───────────────────┘
```

**Static where possible, dynamic where necessary:**

- Product pages, store listing, and landing page are statically generated at build time
- Medusa webhooks trigger a re-deploy when products are created, updated, or deleted — keeping static pages in sync
- Product variant availability is refreshed client-side to prevent stale inventory data
- Cart, checkout, and navigation hydrate as interactive React islands
- Middleware handles region detection and country-based routing
- Cart state persists client-side via Nanostores + `localStorage`

## Pages

| Route                        | Description                                      |
| ---------------------------- | ------------------------------------------------ |
| `/:country/`                 | Landing page                                     |
| `/:country/store`            | Product catalog                                  |
| `/:country/store/:productId` | Product detail with image carousel               |
| `/:country/cart`             | Shopping cart                                    |
| `/:country/checkout`         | Multi-step checkout (address, shipping, payment) |
| `/:country/order/confirmed`  | Order confirmation                               |

All routes are prefixed with an ISO-2 country code for region-based pricing and shipping.

## Getting Started

### Prerequisites

- [Node.js](https://nodejs.org) 18+
- [Yarn](https://yarnpkg.com) 4.x
- A running [Medusa v2](https://docs.medusajs.com) backend
- [Stripe](https://stripe.com) account (for payments)

### Setup

```bash
# Clone the repo
git clone https://github.com/bystrol/astro-medusa-starter.git
cd astro-medusa-starter/

# Install dependencies
yarn

# Configure environment
cp .env.example .env
```

Fill in your `.env`:

```env
PUBLIC_MEDUSA_BACKEND_URL=http://localhost:9000
PUBLIC_MEDUSA_PUBLISHABLE_KEY=pk_...
DEFAULT_REGION=us
PUBLIC_STRIPE_KEY=pk_test_...
S3_DOMAIN=your-bucket.s3.us-east-1.amazonaws.com
PUBLIC_INPOST_GEOWIDGET_TOKEN=your-token
PUBLIC_INPOST_SANDBOX=true
```

> Make sure your Medusa backend has [CORS configured](https://docs.medusajs.com/learn/configurations/medusa-config#httpstorecors) to allow requests from your storefront origin.

### Development

```bash
yarn dev        # Start dev server on localhost:8000
```

### Production

```bash
yarn build      # Build for Cloudflare Workers
yarn preview    # Preview the production build locally
```

## Project Structure

```
src/
├── assets/              # Static assets (images, fonts)
├── components/          # Shared UI components
├── layouts/             # Page layouts
├── lib/
│   ├── sdk.ts           # Medusa SDK singleton
│   ├── stores/          # Nanostores (cart state)
│   ├── params/          # Static path generation
│   └── utils/           # Helpers (pricing, stock, etc.)
├── loaders/             # Astro content loaders
├── middleware.ts         # Region detection & routing
├── modules/
│   ├── cart/            # Cart page & sidebar
│   ├── checkout/        # Multi-step checkout flow
│   ├── layout/          # Nav, footer
│   ├── order/           # Order confirmation
│   └── products/        # Product cards, detail, carousel
├── pages/
│   └── [countryCode]/   # All routes, region-prefixed
├── styles/              # Global styles & Tailwind theme
└── types/               # TypeScript type definitions
```

## Key Design Decisions

- **Islands architecture** — React only loads for interactive components (cart, nav, checkout). Everything else ships as zero-JS static HTML.
- **Real-time inventory checks** — Product variant stock data is fetched client-side on page load, ensuring accurate availability even though pages are statically generated.
- **Edge deployment** — Cloudflare Workers adapter means your storefront runs close to your customers, everywhere.
- **Tailwind v4** — No config file. Theme customization lives in CSS with `@theme`. Powered by the Vite plugin.
- **Region-aware routing** — Country code in the URL drives pricing, currency, and available shipping options — all resolved via Medusa regions.

## License

[MIT](LICENSE)

## Author

**Michal Bystryk** — [LinkedIn](https://www.linkedin.com/in/michal-bystryk/)