Auraimage Migrate

AuraImage Migration

Step-by-step workflow for migrating image assets to AuraImage — from detection through upload to JSX rewriting.

When to Apply

Trigger this workflow when:

• A user asks to "migrate", "optimize", or "move" images
• You encounter <img src="/public/..."> or require('./image.png') patterns
• You see Cloudinary (res.cloudinary.com), Imgix (.imgix.net), or plain S3 (s3.amazonaws.com) URLs
• The audit_lcp MCP tool reports unoptimized images

Before You Start

You need your AuraImage project name (find it in the dashboard → your project → Settings) and your AURA_SECRET_KEY set in the environment. Pass projectName directly to the migrate_assets call below.

Migration Workflow

Step 1 — Audit (always run first)

Use the audit_lcp MCP tool to scan the project before touching any files:

audit_lcp({ directory: "/absolute/path/to/project" })

This reports: total unoptimized images, estimated LCP improvement, and the list of files to migrate. Do not skip this step — it gives you the exact file list so you don't miss anything or accidentally upload non-image files.

Step 2 — Dry Run

Run migrate_assets with dryRun: true first to preview what will be uploaded:

migrate_assets({
  directory: "/absolute/path/to/project",
  projectName: "my-project",   // your AuraImage project name
  dryRun: true
})

Show the user the preview and confirm before proceeding.

Step 3 — Upload

Run migrate_assets with dryRun: false to perform the actual upload:

migrate_assets({
  directory: "/absolute/path/to/project",
  projectName: "my-project",   // your AuraImage project name
  dryRun: false
})

Capture the returned AuraImage URLs for the rewrite step.

Step 4 — Rewrite Image References

Replace all original image references in code with AuraImage <picture> elements. See rules/rewrite-jsx.md for patterns.

Step 5 — Verify

After rewriting, run audit_lcp again on the same directory. The unoptimized image count should be zero.

Rule Categories

1. Detection (HIGH)

• detect-local-images — Patterns that indicate migrateable local images.
• detect-third-party-urls — Cloudinary, Imgix, S3, and other CDN URLs to replace.

2. Rewriting (HIGH)

• rewrite-jsx — How to replace <img> tags with AuraImage <picture> elements.
• rewrite-css — How to replace CSS url() background images.

3. Upload Flow for New Images (MEDIUM)

• upload-flow — Server-side signing + client-side PUT for adding new images at runtime.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/detect-local-images.md
rules/detect-third-party-urls.md
rules/rewrite-jsx.md
rules/upload-flow.md