orange-opensource/orange-boosted-bootstrap/migrate-to-ouds-web

Migrate to OUDS Web

Step-by-step workflow for migrating a project to OUDS Web using the @ouds/web-migrate CLI tool.

Step 1 — Detect source library

Read the project's package.json (dependencies and devDependencies) and map to the correct --from flag:

If ouds-web or @ouds/web-orange is already present, the project is either fully migrated or partially migrated — confirm with the user before proceeding. If the user confirms, update the dependencies to the latest OUDS Web version. Detect the installed OUDS Web version from the project's lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock/bun.lockb) or package.json, then use the matching using-ouds-web-version-<major>-<minor> skill afterward.

Step 2 — Choose file glob

Inspect the project file types and pick a safe glob. Never use `"/."`** — it modifies binary and unrelated files.

Advise running in a version-controlled folder so changes can be reviewed with git diff.

Step 3 — Run the migration tool

# Migrate from Boosted
npx @ouds/web-migrate --from=boosted "**/*.{css,scss,html}"
 
# Migrate from OB1 (Vue project)
npx @ouds/web-migrate --from=ob1 "**/*.{css,scss,html,vue}"
 
# Update to latest OUDS Web version (from older OUDS)
npx @ouds/web-migrate "**/*.{css,scss,html}"

The tool:

• Automatically replaces known class names using regex
• Emits warnings for deprecated/removed classes that require manual follow-up (one line per change needed)

Step 4 — Resolve warnings (manual steps)

For each warning line in the output:

1. Identify the component or class name mentioned in the warning
2. Invoke the using-ouds-web-version-<major>-<minor> skill to find the correct OUDS Web HTML structure for that component
3. Apply the replacement manually in the affected files

Example: if the warning mentions .alert-success, look up alerts in using-ouds-web-version-<major>-<minor> references to find the correct .alert-positive / .alert-neutral structure.

Step 5 — Post-migration checklist

• [ ] Review git diff to verify all automated replacements are correct
• [ ] Update package.json: replace boosted/@ob1/web with @ouds/web-common plus exactly one theme package (for example, @ouds/web-orange)
• [ ] Update Sass/CSS imports (e.g. @import "boosted" → @import "ouds-web")
• [ ] Update CDN links in HTML files (boosted.min.css → ouds-web.min.css)
• [ ] Search for leftover class=" " artifacts — the tool does not remove empty class attributes
• [ ] Verify responsive breakpoints: OUDS Web uses 8 breakpoints with prefix syntax {bp}:{utility}-{value} (e.g. lg:col-6), not Bootstrap infix format (col-lg-6)

Known tool limitations

• Empty class=" " attributes are left in place after class removal — clean up manually
• Custom responsive classes with infixes (e.g. something-2xl-left) get renamed to 2xl:something-left — review these carefully
• Always inspect the diff before committing

Anti-patterns

• ❌ Don't guess source library from class names — always check package.json first
• ❌ Don't use "**/*.*" glob — modifies binary and irrelevant files
• ❌ Don't stop after automated replacements — warnings require manual action
• ❌ Don't skip the git diff review — automated replacements may need adjustment

References

• Use the using-ouds-web-version-<major>-<minor> skill for target component markup and class lookup during manual warning resolution
• packages/migrate/README.md — full @ouds/web-migrate options and examples
• using-ouds-web-version-<major>-<minor>/references/getting-started/migration-from-boosted.md — component-by-component Boosted→OUDS Web changes
• using-ouds-web-version-<major>-<minor>/references/getting-started/update-guide.md — OUDS Web version-to-version changes