feat(upgrade): Add codemod to move ClerkProvider inside body #7596

jacekradko · 2026-01-14T03:23:07Z

Summary

Adds a jscodeshift codemod that transforms ClerkProvider from wrapping <html> to being inside <body>
This is needed for Next.js 16 cache components support - when cacheComponents is enabled, ClerkProvider must be positioned inside <body> to avoid "Uncached data was accessed outside of <Suspense>" errors
Includes 7 test cases covering various layout patterns

What it does

Transforms layouts from:

<ClerkProvider>
  <html>
    <body>{children}</body>
  </html>
</ClerkProvider>

To:

<html>
  <body>
    <ClerkProvider>
      {children}
    </ClerkProvider>
  </body>
</html>

Test plan

All 7 codemod tests pass
All 167 upgrade package tests pass
Manual testing with npx @clerk/upgrade on a sample Next.js project

Summary by CodeRabbit

New Features
- Added an automated codemod to move ClerkProvider into the .
- Upgrade tool now accepts codemod entries as strings or objects and supports SDK/package targeting so only relevant transforms run.
Tests
- Added fixtures, unit tests for the ClerkProvider transform, and integration tests for the codemod runner and SDK/package filtering.
Documentation
- Added an upgrade guide with before/after examples and usage notes for ClerkProvider placement.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Add jscodeshift codemod that transforms ClerkProvider from wrapping <html> to being inside <body> for Next.js 16 cache components support. This codemod handles: - Moving ClerkProvider inside body element - Preserving all ClerkProvider props - Handling layouts with multiple body children - Handling layouts with head elements

changeset-bot · 2026-01-14T03:23:11Z

🦋 Changeset detected

Latest commit: 90ee456

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@clerk/upgrade	Minor

Not sure what this means? Click here to learn what changesets are.

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

vercel · 2026-01-14T03:23:11Z

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

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
clerk-js-sandbox	Skipped		Jan 14, 2026 3:47am

- Add transform-clerk-provider-inside-body to core-3 codemods list - Add change document explaining the ClerkProvider positioning for Next.js 16 cache components support

coderabbitai · 2026-01-14T03:25:52Z

📝 Walkthrough

Walkthrough

Adds a jscodeshift codemod transform-clerk-provider-inside-body (parser = 'tsx') that moves ClerkProvider from wrapping html to inside body. Adds unit test fixtures and a Vitest test, integration tests for codemod selection/execution, and a documentation file describing the upgrade for Next.js 16 cache components. Registers the codemod in the Core 3 upgrade config and a changeset. Updates the runner to accept codemod entries as strings or objects, filter codemods by package list (supporting *) and SDK, and exposes runCodemods for testing.

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat(upgrade): Add codemod to move ClerkProvider inside body' directly and clearly describes the main change—adding a new codemod that relocates ClerkProvider from wrapping the html element to being placed inside the body element.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

📜 Recent review details

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 59fc59e and 90ee456.

📒 Files selected for processing (1)

packages/upgrade/src/runner.js

🚧 Files skipped from review as they are similar to previous changes (1)

packages/upgrade/src/runner.js

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (27)

GitHub Check: Integration Tests (handshake, chrome)
GitHub Check: Integration Tests (handshake:staging, chrome)
GitHub Check: Integration Tests (billing, chrome)
GitHub Check: Integration Tests (vue, chrome)
GitHub Check: Integration Tests (billing, chrome, RQ)
GitHub Check: Integration Tests (custom, chrome)
GitHub Check: Integration Tests (machine, chrome, RQ)
GitHub Check: Integration Tests (quickstart, chrome, 16)
GitHub Check: Integration Tests (nextjs, chrome, 15)
GitHub Check: Integration Tests (quickstart, chrome, 15)
GitHub Check: Integration Tests (astro, chrome)
GitHub Check: Integration Tests (nextjs, chrome, 16)
GitHub Check: Integration Tests (nextjs, chrome, 16, RQ)
GitHub Check: Integration Tests (tanstack-react-start, chrome)
GitHub Check: Integration Tests (react-router, chrome)
GitHub Check: Integration Tests (sessions, chrome)
GitHub Check: Integration Tests (localhost, chrome)
GitHub Check: Integration Tests (nuxt, chrome)
GitHub Check: Integration Tests (machine, chrome)
GitHub Check: Integration Tests (ap-flows, chrome)
GitHub Check: Integration Tests (express, chrome)
GitHub Check: Integration Tests (generic, chrome)
GitHub Check: Integration Tests (sessions:staging, chrome)
GitHub Check: Formatting | Dedupe | Changeset
GitHub Check: Build Packages
GitHub Check: Analyze (javascript-typescript)
GitHub Check: semgrep-cloud-platform/scan

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-01-14T03:28:56Z

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7596

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@7596

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@7596

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@7596

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@7596

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7596

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@7596

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@7596

@clerk/express

npm i https://pkg.pr.new/@clerk/express@7596

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@7596

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@7596

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@7596

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@7596

@clerk/react

npm i https://pkg.pr.new/@clerk/react@7596

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@7596

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@7596

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@7596

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@7596

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@7596

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@7596

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@7596

commit: 90ee456

Codemods can now specify which SDKs they apply to using the packages property. This matches the existing pattern used for change documents. Example: codemods: [ 'transform-all', // runs for all SDKs { name: 'transform-nextjs-only', packages: ['nextjs'] }, ] The ClerkProvider codemod now only runs for nextjs upgrades.

github-actions bot added the core-3 label Jan 14, 2026

feat(upgrade): Include ClerkProvider codemod in core-3 upgrade

bc7faff

- Add transform-clerk-provider-inside-body to core-3 codemods list - Add change document explaining the ClerkProvider positioning for Next.js 16 cache components support

vercel bot temporarily deployed to Preview January 14, 2026 03:25 Inactive

vercel bot temporarily deployed to Preview January 14, 2026 03:32 Inactive

chore: add changeset

4833f5f

vercel bot deployed to Preview January 14, 2026 03:35 View deployment

chore: format

0c8f6aa

vercel bot temporarily deployed to Preview January 14, 2026 03:40 Inactive

test(upgrade): Add edge case tests for codemod SDK filtering

b257def

vercel bot temporarily deployed to Preview January 14, 2026 03:43 Inactive

chore: simplify changeset

59fc59e

vercel bot deployed to Preview January 14, 2026 03:45 View deployment

chore: remove unnecessary comments

90ee456

vercel bot temporarily deployed to Preview January 14, 2026 03:47 Inactive

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(upgrade): Add codemod to move ClerkProvider inside body #7596

feat(upgrade): Add codemod to move ClerkProvider inside body #7596

Uh oh!

jacekradko commented Jan 14, 2026 •

edited by coderabbitai bot

Loading

Uh oh!

changeset-bot bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

vercel bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

coderabbitai bot commented Jan 14, 2026 •

edited

Loading

Walkthrough

Uh oh!

pkg-pr-new bot commented Jan 14, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(upgrade): Add codemod to move ClerkProvider inside body #7596

Are you sure you want to change the base?

feat(upgrade): Add codemod to move ClerkProvider inside body #7596

Uh oh!

Conversation

jacekradko commented Jan 14, 2026 • edited by coderabbitai bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What it does

Test plan

Related

Summary by CodeRabbit

Uh oh!

changeset-bot bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

vercel bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Uh oh!

pkg-pr-new bot commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jacekradko commented Jan 14, 2026 •

edited by coderabbitai bot

Loading

changeset-bot bot commented Jan 14, 2026 •

edited

Loading

vercel bot commented Jan 14, 2026 •

edited

Loading

coderabbitai bot commented Jan 14, 2026 •

edited

Loading

pkg-pr-new bot commented Jan 14, 2026 •

edited

Loading