Claude-code-plugins-plus-skills webflow-upgrade-migration

install

source · Clone the upstream repo

git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jeremylongshore/claude-code-plugins-plus-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/saas-packs/webflow-pack/skills/webflow-upgrade-migration" ~/.claude/skills/jeremylongshore-claude-code-plugins-plus-skills-webflow-upgrade-migration && rm -rf "$T"

manifest: plugins/saas-packs/webflow-pack/skills/webflow-upgrade-migration/SKILL.md

Webflow Upgrade & Migration

Overview

Guide for upgrading the

webflow-api

SDK and migrating from Webflow Data API v1 to v2. Covers breaking changes, endpoint mapping, import updates, and rollback.

Prerequisites

Current
```
webflow-api
```
SDK installed
Git for version control (create upgrade branch)
Test suite available
Staging environment for validation

Instructions

Step 1: Assess Current Version

# Check installed version
npm list webflow-api

# Check latest available
npm view webflow-api version

# View changelog
npm view webflow-api --json | jq '.versions[-5:]'

Step 2: SDK Version History

SDK Version	API Version	Node.js	Key Changes
3.x	Data API v2	18+	Current. `WebflowClient` , auto-retry, bulk ops
2.x	Data API v1/v2	16+	Transitional. Mixed v1/v2 endpoints
1.x	Data API v1	14+	Legacy. `Webflow` class, no types

v1 endpoints deprecation: late 2026. Migrate before then.

Step 3: API v1 to v2 Migration Map

Base URL Change

v1: https://api.webflow.com
v2: https://api.webflow.com/v2

Authentication Change

// v1 (old) — API key
import Webflow from "webflow-api";
const webflow = new Webflow({ token: "your-api-key" });

// v2 (current) — Access token
import { WebflowClient } from "webflow-api";
const webflow = new WebflowClient({ accessToken: "your-access-token" });

Endpoint Migration Map

Operation	v1 Endpoint	v2 Endpoint
List sites	`GET /sites`	`GET /v2/sites`
Get site	`GET /sites/{site_id}`	`GET /v2/sites/{site_id}`
Publish site	`POST /sites/{site_id}/publish`	`POST /v2/sites/{site_id}/publish`
List collections	`GET /sites/{site_id}/collections`	`GET /v2/sites/{site_id}/collections`
List items	`GET /collections/{id}/items`	`GET /v2/collections/{id}/items`
Create item	`POST /collections/{id}/items`	`POST /v2/collections/{id}/items`
Update item	`PUT /collections/{id}/items/{item_id}`	`PATCH /v2/collections/{id}/items/{item_id}`
List products	`GET /sites/{site_id}/products`	`GET /v2/sites/{site_id}/products`
List orders	`GET /sites/{site_id}/orders`	`GET /v2/sites/{site_id}/orders`

Key v2 differences:

Update uses
```
PATCH
```
(not
```
PUT
```
) — partial updates only
Items created as drafts by default (
```
isDraft: true
```
)
Bulk endpoints added (create/update/delete up to 100 items)
Live (published) items have separate endpoints (
```
/items/live
```
)
Scopes required (e.g.,
```
cms:read
```
,
```
cms:write
```
)

Step 4: SDK Method Migration

// ===== v1 SDK (old) =====
const webflow = new Webflow({ token: "xxx" });

// List sites
const sites = await webflow.sites();

// List collections
const collections = await webflow.collections({ siteId: "site-123" });

// Get items
const items = await webflow.items({ collectionId: "col-456" });

// Create item
const item = await webflow.createItem({
  collectionId: "col-456",
  fields: { name: "Test", slug: "test", _archived: false, _draft: false },
});

// Update item (full replace)
await webflow.updateItem({
  collectionId: "col-456",
  itemId: "item-789",
  fields: { name: "Updated", slug: "test" },
});

// ===== v2 SDK (current) =====
const webflow = new WebflowClient({ accessToken: "xxx" });

// List sites
const { sites } = await webflow.sites.list();

// List collections
const { collections } = await webflow.collections.list("site-123");

// Get items (staged)
const { items } = await webflow.collections.items.listItems("col-456");

// Get items (live/published)
const { items: live } = await webflow.collections.items.listItemsLive("col-456");

// Create item (draft by default)
const item = await webflow.collections.items.createItem("col-456", {
  fieldData: { name: "Test", slug: "test" },
  isDraft: false,
});

// Update item (partial update via PATCH)
await webflow.collections.items.updateItem("col-456", "item-789", {
  fieldData: { name: "Updated" }, // Only changed fields
});

// NEW: Bulk create (up to 100)
await webflow.collections.items.createItemsBulk("col-456", {
  items: [{ fieldData: { name: "Item 1", slug: "item-1" } }],
});

// NEW: Publish items
await webflow.collections.items.publishItem("col-456", {
  itemIds: ["item-789"],
});

Step 5: Execute Upgrade

# Create upgrade branch
git checkout -b upgrade/webflow-api-v3

# Install latest
npm install webflow-api@latest

# Run tests to find breaking changes
npm test 2>&1 | tee upgrade-test-results.txt

# Fix breaking changes (common patterns above)
# ...

# Verify in staging
npm run test:integration

# Commit and PR
git add -A
git commit -m "upgrade: webflow-api to v3 (Data API v2)"

Step 6: Rollback if Needed

# Rollback to previous version
npm install webflow-api@2.x.x --save-exact

# Or revert the upgrade branch
git revert HEAD

Breaking Change Checklist

Import changed:
```
Webflow
```
class to
```
WebflowClient
```
named export
Auth changed:
```
token
```
to
```
accessToken
```
Method calls changed:
```
webflow.sites()
```
to
```
webflow.sites.list()
```
Field data wrapped in
```
fieldData
```
object
Update method changed from
```
PUT
```
to
```
PATCH
```
(partial)
Item status:
```
_draft
```
/
```
_archived
```
to
```
isDraft
```
/
```
isArchived
```
Response shape: items now under
```
.items
```
property with
```
.pagination
```
Scopes required for all operations

Output

Updated SDK to latest version
All v1 endpoints migrated to v2
Breaking changes fixed
Tests passing on staging
Rollback procedure documented

Error Handling

Issue	Cause	Solution
`TypeError: Webflow is not a constructor`	Using v1 import with v3 SDK	Change to `import { WebflowClient }`
`400 Bad Request` on create	Fields not in `fieldData` wrapper	Wrap fields: `{ fieldData: { ... } }`
`405 Method Not Allowed`	Using `PUT` instead of `PATCH`	Update to `PATCH` for item updates
Missing items in response	Not checking `.items` property	Destructure: `const { items } = await ...`

Resources

Next Steps

For CI integration during upgrades, see

webflow-ci-integration