docs: Axios to @data-client/rest migration guide, codemod, and skill

[ntucker]

Fixes # .

Motivation

Users migrating from axios to @data-client/rest need guidance on how to translate axios patterns (instances, interceptors, error handling, cancellation, etc.) into RestEndpoint lifecycle methods. This PR provides documentation, automated tooling, and AI-assisted migration support.

Solution

1. Documentation guide (docs/rest/guides/axios-migration.md)

• AI skill install (SkillTabs) at the top for easy access — preferred migration path
• Leads with type-safe path parameters as the primary migration benefit
• Quick reference table mapping every axios config option to its RestEndpoint equivalent
• Interactive EndpointPlayground examples for GET, POST, and instance creation
• Before/after tabs for interceptors, error handling, and cancellation
• Codemod section references the skill as preferred approach for AI users
• Added to REST sidebar after Django Integration

2. jscodeshift codemod (website/static/codemods/axios-to-rest.js)

• Replaces import axios from 'axios' with import { RestEndpoint } from '@data-client/rest'
• Converts axios.create({ baseURL, headers }) into RestEndpoint subclasses with urlPrefix + getHeaders()
• Transforms axios.get() / .post() / .put() / .patch() / .delete() calls into new RestEndpoint({ path, method })
• Handles aliased imports, multiple create calls, type import removal
• Preserves unknown named imports from axios (e.g. isAxiosError, spread) while removing known type-only imports
• Keeps axios imported whenever unresolved usages remain (e.g. dynamic URL calls), while still injecting RestEndpoint when partial conversion occurred
• Handles TypeScript: import type, inline type specifiers, generic type parameters on calls
• Handles template literal URLs: axios.get(`/users/${id}`)
• Skips calls with config objects as second arg (not deterministically transformable)
• Follow-up fix: preserves CancelToken and AxiosError named imports when used as runtime values (CancelToken.source(), instanceof AxiosError) even if default axios import is removed
• Follow-up fix: resolves instance call targets by lexical binding scope, preventing shadowed variables (e.g. nested const api = createOtherClient()) from being incorrectly rewritten to generated endpoint classes

3. Codemod tests (website/static/codemods/__tests__/axios-to-rest.test.js) — expanded coverage for:

• Import rewriting (default, aliased, type-only, mixed named/type, unknown named)
• Runtime value import preservation (CancelToken and AxiosError)
• axios.create() (baseURL, headers, spreads, aliased, multiple, empty, exported)
• Direct calls (all HTTP methods, template literals, non-literal URLs, config objects)
• Instance method calls after create transform
• Shadowed-scope regression: nested identifiers with the same name are no longer rewritten
• TypeScript edge cases (import type, inline type specifiers, generics, typeof axios)
• Real-world patterns (chained .then(), await destructuring, axios() direct call, axios.all, conditionals)

4. Migration skill (.cursor/skills/axios-to-rest-migration/SKILL.md)

• Referenced from the doc guide via SkillTabs and skills.sh link
• Runs the codemod as Step 1
• Documents all non-deterministic migration patterns the codemod cannot handle:
  • Interceptors → getHeaders() / getRequestInit() / parseResponse() / process()
  • Error handling → NetworkError
  • timeout, cancelToken, responseType, paramsSerializer, auth, validateStatus, XSRF, upload progress
• Includes search patterns for finding axios usage in a codebase

Open questions

• Should the codemod also handle require('axios') (CJS) in addition to ESM imports?
• Should the doc guide include a HooksPlayground example showing the full flow from axios call to useSuspense hook?

  

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5a52953

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs-site	Ignored	Preview	Apr 4, 2026 8:20pm

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.08%. Comparing base (53c7091) to head (5a52953).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3867   +/-   ##
=======================================
  Coverage   98.08%   98.08%           
=======================================
  Files         152      152           
  Lines        2876     2876           
  Branches      564      564           
=======================================
  Hits         2821     2821           
  Misses         11       11           
  Partials       44       44           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vercel]

Deployment failed with the following error:

The `vercel.json` schema validation failed with the following message: `ignoreCommand` should NOT be longer than 256 characters

Learn More: https://vercel.com/docs/concepts/projects/project-configuration

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6906b2e. Configure here.}