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 supports SDK/package-targeted codemods so only relevant transforms run.
Tests
- Added fixtures, unit tests for the ClerkProvider transform, and integration tests for codemod runner filtering and behavior.
Documentation
- Added an upgrade guide with before/after examples and usage notes for ClerkProvider placement.
Chores
- Added a changeset announcing the codemod and minor version bump.

_{✏️ 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: de2f6f8

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 16, 2026 7:55pm

- 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 new codemod transform-clerk-provider-inside-body (parser = 'tsx') that moves ClerkProvider from wrapping <html> into the <body>. Adds unit test fixtures and a Vitest test for the transform, integration tests for codemod selection/execution, and documentation describing the change for Next.js 16 cache components. Registers the codemod in the Core 3 upgrade config, updates the runner to accept string/object codemod entries and filter codemods by package/SDK, and includes a changeset.

🚥 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 accurately describes the main change: adding a codemod that moves ClerkProvider from wrapping html to inside body, which is the core objective of this changeset.

_{✏️ Tip: You can configure your own custom pre-merge checks in the 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: de2f6f8

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.

panteliselef · 2026-01-14T13:11:05Z

🥇

…ider codemod - Support aliased imports like `import { ClerkProvider as CP }` - Handle multiple ClerkProviders by only transforming those wrapping <html> - Simplify whitespace handling (rely on user's formatter) - Add test fixtures for new edge cases

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

Merge branch 'main' into feat/codemod-clerk-provider-inside-body

025899e

vercel bot deployed to Preview January 14, 2026 17:55 View deployment

jacekradko requested review from a team and brkalow January 15, 2026 17:55

Merge branch 'main' into feat/codemod-clerk-provider-inside-body

3d7b0b4

vercel bot deployed to Preview January 16, 2026 17:04 View deployment

alexcarpenter approved these changes Jan 16, 2026

View reviewed changes

vercel bot temporarily deployed to Preview January 16, 2026 19:36 Inactive

format

de2f6f8

vercel bot temporarily deployed to Preview January 16, 2026 19:55 Inactive

jacekradko merged commit 145b8bc into main Jan 16, 2026
40 checks passed

jacekradko deleted the feat/codemod-clerk-provider-inside-body branch January 16, 2026 20:09

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!

panteliselef commented Jan 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

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

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!

panteliselef commented Jan 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 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