INSTUI-5173: Document the new codemods in the upgrade guide; allow both Prettier 2 and 3 to run in the codemods by matyasf · Pull Request #2705 · instructure/instructure-ui

matyasf · 2026-09-02T13:09:36Z

Summary

Make Prettier a peer dependency; allow users to use both v2 and v3
Move the codemod section to the top of the v11.7 upgrade guide and add migrateToNewIcons and multiVersionThemeVariablesCodemod docs
Add the missing Billboard iconHoverColorInverse / messageColorInverse removals and a DataPermissionLevels entry to the theme variable mappings

Test Plan

Check the v11.7 upgrade guide in the docs app
Run multiVersionThemeVariablesCodemod against a file using Billboard iconHoverColorInverse / messageColorInverse and DataPermissionLevels overrides to confirm they're removed.

Fixes INSTUI-5173

🤖 Generated with Claude Code

github-actions · 2026-09-02T13:14:40Z

PR Preview Action v1.8.1
🚀 View preview at https://instructure.design/pr-preview/pr-2705/
Built to branch `gh-pages` at 2026-09-03 13:01 UTC. Preview will be ready when the GitHub Pages deployment is complete.

github-actions · 2026-09-02T13:18:25Z

Visual regression report

Cypress suite: ✅ Passing

Visual diff: ⚠️ Changes detected.

Status	Count
Unchanged	95
Changed	1
New	0
Removed	0

Accessibility (axe): ✅ No violations.

📊 View full report — click a screenshot's ⚠ badge to see each violation boxed on the image, with the offending element named and contrast failures shown as color swatches.

Diff images (1)

badge-canvas.png — 1573 pixels differ

_{Baselines come from the visual-baselines branch. They refresh on every merge to master. The Cypress suite line covers the a11y and console-error assertions — a ❌ there means the suite found real issues even if the visual diff is clean.}

matyasf · 2026-09-02T14:40:16Z

-
-## Codemods
-
-### updateInstUIImportVersions


this section was just moved up

matyasf · 2026-09-02T14:40:58Z

+ * @returns a promise resolving to the modified file as `string` or to `null`
 */
-const myCodemod: Transform = (file, api,
+const myCodemod: Transform = async (file, api,


async is needed because Prettier 3 as async, thus everything needs to be async

matyasf · 2026-09-02T14:41:18Z

+- `fileName`: write parse errors and transform failures to this file.
+- `usePrettier`: run output through Prettier (default `true`).
+
+### migrateToNewIcons


new part from here

matyasf · 2026-09-02T14:42:27Z

    removed: {
      iconColor: {},
-      iconHoverColor: {}
+      iconHoverColor: {},


changes in this file are because these were late additiong and were missing from the codemod

matyasf · 2026-09-02T14:44:01Z

+const importModule = new Function('specifier', 'return import(specifier)') as (
+  specifier: string
+) => Promise<Record<string, unknown>>
+
+async function importPrettier(): Promise<Record<string, unknown>> {
+  try {
+    return await importModule(PRETTIER)
+  } catch {
+    // Test runners that evaluate modules in their own context (Vitest) give
+    // `new Function` no dynamic import callback, but do handle a plain import.
+    return await import(PRETTIER)
+  }
+}
+
+/**
+ * Prettier is an optional peer dependency, so it is resolved from the
+ * consumer's `node_modules` and its version is whatever they installed.
+ */
+function loadPrettier() {
+  if (!prettierPromise) {
+    prettierPromise = importPrettier()
+      .then((namespace) => {
+        const asDefault = namespace.default as PrettierModule | undefined
+        return typeof asDefault?.format === 'function'
+          ? asDefault
+          : (namespace as unknown as PrettierModule)
+      })
+      .catch(() => undefined)
+  }
+  return prettierPromise
+}


this whole thing is super ugly, but needed while ppl are using Prettier v2..

matyasf · 2026-09-03T10:29:33Z

@@ -1,10 +1,10 @@
 ---
-title: Upgrade guide for v11.7
+title: Upgrade guide for new theming


I was really debating the best title for this (cannot be much longer than now), still not 100% sure that this is the best

joyenjoyer · 2026-09-03T11:22:02Z

 ---

-# Upgrade guide for v10 -> v11
+# Upgrade guide for v10 -> 11


Why did you remove v from v11 here?

Wanted to keep the title as short at possible

joyenjoyer · 2026-09-03T12:27:25Z

+npx jscodeshift@latest -t node_modules/@instructure/ui-codemods/lib/[codemod name].ts <path>  \
+  --extensions=ts,tsx \
+  --ignore-pattern="**/node_modules/**" \
+  --ignore-pattern="**/*.d.ts" \


Remove the trailing slash after the last line

joyenjoyer · 2026-09-03T12:28:08Z

I tried loading the upgrade-guide in a local environment and it loads extremely slowly for me. Please check it

Thats because this page is huge and because you are using a debug build. Even in the prod build its 2 secs on my M3 Max. I guess if we'd optimize V12ChangelogTable to e.g. use native HTML instead of InstUI it would be much faster. maybe worth a shot in a different PR.

Is it a bad UX in your machine here too? https://instructure.design/pr-preview/pr-2705/upgrade-guide

I see this upon opening the link:

Move the codemod docs to the top of the v11.7 upgrade guide and add migrateToNewIcons and multiVersionThemeVariablesCodemod sections. Note which InstUI version introduced each change in the codemod JSDoc, and group the exports by target version. Also add the missing Billboard iconHoverColorInverse and messageColorInverse removals and a DataPermissionLevels entry to the theme variable mappings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

…ettier 3 Prettier is now an optional peer dependency instead of a bundled Prettier 2. The codemods import it lazily from the consumer's node_modules, accept both the v2 sync and v3 async API, and fall back to unformatted output with a warning when it is not installed. This makes instUICodemodExecutor and every transform async, so the tests await them and the codemod fixtures are excluded from the repo's own Prettier run. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

joyenjoyer · 2026-09-03T14:07:17Z

+let warnedAboutMissingPrettier = false
+
+/**
+ * jscodeshift registers `@babel/register` for `.mjs` and `.cjs` files too and


A bit too verbose comment here

matyasf self-assigned this Sep 2, 2026

github-actions Bot pushed a commit that referenced this pull request Sep 2, 2026

visual-regression: PR #2705 (8384e9a) 8384e9a

3b2acf4

github-actions Bot pushed a commit that referenced this pull request Sep 2, 2026

visual-regression: PR #2705 (2c56200) 2c56200

6f2e544

matyasf changed the title ~~docs(ui-codemods): document the new codemods in the upgrade guide~~ INSTUI-5173: Document the new codemods in the upgrade guide; allow both Prettier 2 and 3 to run in the codemods Sep 2, 2026

matyasf commented Sep 2, 2026

View reviewed changes

matyasf requested a review from joyenjoyer September 2, 2026 15:14

matyasf force-pushed the codemod_fixes branch from a0d79de to c598399 Compare September 3, 2026 09:00

github-actions Bot pushed a commit that referenced this pull request Sep 3, 2026

visual-regression: PR #2705 (8c01190) 8c01190

9aa9e7e

matyasf commented Sep 3, 2026

View reviewed changes

joyenjoyer requested changes Sep 3, 2026

View reviewed changes

matyasf force-pushed the codemod_fixes branch from c598399 to 95d5acd Compare September 3, 2026 12:52

matyasf requested a review from joyenjoyer September 3, 2026 12:52

matyasf and others added 2 commits September 3, 2026 14:54

matyasf force-pushed the codemod_fixes branch from 95d5acd to e480a2a Compare September 3, 2026 12:54

github-actions Bot pushed a commit that referenced this pull request Sep 3, 2026

visual-regression: PR #2705 (02fa230) 02fa230

3bf7baa

joyenjoyer approved these changes Sep 3, 2026

View reviewed changes

matyasf requested a review from git-nandor September 3, 2026 14:34

Uh oh!

Conversation

matyasf commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

github-actions Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-09-03 13:01 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

github-actions Bot commented Sep 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Visual regression report

badge-canvas.png — 1573 pixels differ

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joyenjoyer Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matyasf commented Sep 2, 2026 •

edited

Loading

github-actions Bot commented Sep 2, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-09-03 13:01 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

github-actions Bot commented Sep 2, 2026 •

edited

Loading

joyenjoyer Sep 3, 2026 •

edited

Loading