aliexpress-product-scraper
Version:
Get Aliexpress product details as a json reponse including feedbacks, variants, description, images, etc.,
244 lines (200 loc) • 6.47 kB
Markdown
# AliExpress Product Scraper
[](https://github.com/sudheer-ranga/aliexpress-product-scraper/actions/workflows/npm-publish.yml)
Scrapes AliExpress product information and returns JSON data including:
- Product details (title, images, description)
- Reviews with photos
- Variants and prices
- Shipping info
- Store info and ratings
## Requirements
- **Node.js >= 24.0.0** (required)
- npm or pnpm
## Installation
```bash
npm install aliexpress-product-scraper
```
## Usage
```javascript
import scrape from 'aliexpress-product-scraper';
const data = await scrape('1005007429636284');
console.log(data.title, data.salePrice);
```
### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `reviewsCount` | number | 20 | Number of reviews to fetch |
| `filterReviewsBy` | 'all' \| 1-5 | 'all' | Filter reviews by star rating |
| `puppeteerOptions` | object | {} | Puppeteer launch options |
| `timeout` | number | 60000 | Page navigation timeout (ms) |
---
## Upgrading to v4.0.0
### Breaking Changes
| Change | v3.x | v4.0.0 |
|--------|------|--------|
| Node.js | **>= 22.0.0** | **>= 24.0.0** |
| Package version | `3.x` | `4.x` |
| AliExpress API | SSR (runParams) | CSR (API interception) |
| Bot detection | Basic | Stealth plugin |
| Runtime API | Current | No response shape changes |
### Upgrade Steps
```bash
# 1. Check Node.js version (must be >= 24)
node --version
# 2. If needed, upgrade Node.js
nvm install 24 && nvm use 24
# 3. Use pnpm through corepack (recommended for contributors)
corepack enable
# 4. Update the package
npm install aliexpress-product-scraper@latest
# 5. Verify it works
node -e "import('aliexpress-product-scraper').then(m => console.log('OK'))"
```
### Developer Setup (v4)
```bash
# Use Node 24
nvm install 24 && nvm use 24
# Install dependencies
pnpm install --frozen-lockfile
# Validate
pnpm run lint
pnpm run test
```
Key v4 updates:
- **Node.js 24+ required** - Uses modern ES features
- **New scraping method** - AliExpress switched to CSR; now intercepts API responses
- **Stealth mode** - Uses puppeteer-extra-plugin-stealth to avoid bot detection
- **Better reliability** - Handles dynamic page loading
- **ESLint + pre-commit hooks** - Code quality enforcement
- **Same API** - No code changes needed in your project
---
## Troubleshooting
| Issue | Solution |
|-------|----------|
| "Cannot find module" | Use Node.js >= 24.0.0 |
| Puppeteer Chrome not found | Run `npx puppeteer browsers install chrome` |
| Timeout errors | Increase timeout: `{ timeout: 90000 }` |
| Empty data | Product may be unavailable or blocked |
---
## Development
```bash
# Install dependencies
pnpm install
# Run linter
pnpm run lint
# Auto-fix lint errors
pnpm run lint:fix
# Run tests
pnpm run test
# Run smoke test (live scraping test)
ALIX_SMOKE=1 pnpm run smoke
# Debug test (verbose output + screenshot)
node scripts/debug-test.js
```
### Scripts
| Script | Description |
|--------|-------------|
| `pnpm run lint` | Check code quality |
| `pnpm run lint:fix` | Auto-fix lint errors |
| `pnpm run test` | Run unit + integration tests |
| `pnpm run smoke` | Live scraping test (requires `ALIX_SMOKE=1`) |
| `node scripts/debug-test.js` | Diagnostic tool with verbose output |
A pre-commit hook automatically runs ESLint on staged files.
---
## Sample Response
```json
{
"title": "Wireless Keyboard and Mouse Combo RGB Backlit...",
"categoryId": "70802",
"productId": "1005007429636284",
"quantity": { "total": 285, "available": 285 },
"description": "<div>...HTML description...</div>",
"orders": "0",
"storeInfo": {
"name": "JOMAA Computer Office Accessories Store",
"logo": "https://ae-pic-a1.aliexpress-media.com/kf/.../144x144.png",
"companyId": 2674539165,
"storeNumber": 1102703188,
"isTopRated": false,
"hasPayPalAccount": false,
"ratingCount": 0,
"rating": "0"
},
"ratings": {
"totalStar": 5,
"averageStar": "4.7",
"totalStartCount": 360,
"fiveStarCount": 0,
"fourStarCount": 0,
"threeStarCount": 0,
"twoStarCount": 0,
"oneStarCount": 0
},
"images": [
"https://ae01.alicdn.com/kf/S9e666c8476db43cb85756879ff330c04z.jpg",
"https://ae01.alicdn.com/kf/Sd3bdde0ad49c47e9a73748a0f371400e5.jpg"
],
"reviews": [
{
"anonymous": false,
"name": "g***i",
"displayName": "Mr. Corey Ullrich",
"gender": "male",
"country": "IL",
"rating": 2,
"info": "Color:Black Axis Body:Hebrew",
"date": "27 Aug 2025",
"content": "the item arrived fast but only the keyboard work...",
"photos": [],
"thumbnails": []
}
],
"variants": {
"options": [
{
"id": 14,
"name": "Color",
"values": [
{ "id": 29, "name": "WHITE", "displayName": "White", "image": "https://..." },
{ "id": 193, "name": "black", "displayName": "Black", "image": "https://..." }
]
},
{
"id": 200009450,
"name": "Axis Body",
"values": [
{ "id": 201450903, "name": "BLACK SWITCH", "displayName": "English", "image": "" }
]
}
],
"prices": [
{
"skuId": 12000040723791666,
"optionValueIds": "14:193;200009450:201450908",
"availableQuantity": 12,
"originalPrice": { "currency": "INR", "formatedAmount": "Rs.6,354.19", "value": 6354.19 },
"salePrice": { "currency": "INR", "formatedAmount": "Rs.3,367.66", "value": 3367.66 }
}
]
},
"specs": [
{ "attrName": "Brand Name", "attrValue": "JOMAA" },
{ "attrName": "Type", "attrValue": "2.4Ghz Wireless" }
],
"currencyInfo": { "currencyCode": "INR" },
"originalPrice": {
"min": { "currency": "INR", "formatedAmount": "Rs.6,077.63", "value": 6077.63 },
"max": { "currency": "INR", "formatedAmount": "Rs.6,077.63", "value": 6077.63 }
},
"salePrice": {
"min": { "currency": "INR", "formatedAmount": "Rs.3,221.14", "value": 3221.14 },
"max": { "currency": "INR", "formatedAmount": "Rs.3,221.14", "value": 3221.14 }
},
"shipping": [
{
"deliveryProviderName": "newGlobal",
"deliveryInfo": { "min": 75, "max": 75 },
"shippingInfo": { "from": "China", "to": "India", "fees": 0, "unreachable": true }
}
]
}
```