Migration Guide to v2.0

Learn how to upgrade your Webui project from v1.x to v2.0. This guide covers breaking changes, new features, and the automated migration tool to help you transition smoothly.

📅 Updated Nov 12, 2024 ⏱️ 15 min read 🔧 Breaking Changes

⚠️

Before You Begin

We strongly recommend creating a backup or a git branch before running the migration. While our tool is tested, complex custom configurations may require manual review.

Prerequisites

Ensure your environment meets the following requirements before migrating:

Node.js 18.17+ or 20.x
npm 9+ or pnpm 8+
Clean working directory (commit or stash changes)
Webui CLI 1.8+ installed globally

                        Terminal
                        
# Check versions
node --version
npm --version

# Update CLI if needed
npm i -g @webui/cli@latest

Automated Migration

Webui v2.0 includes an automated codemod that handles the majority of breaking changes. Run the migration command in your project root:

                        Terminal
                        
# Run the migration
npx @webui/cli migrate v1-to-v2

# Dry run first (recommended)
npx @webui/cli migrate v1-to-v2 --dry-run

ℹ️

What the Migrator Does

The automated tool will update package.json, rewrite import paths, transform component props, update webui.config.js, and generate a CHANGELOG.md report of changes.

Key Breaking Changes

Below is a summary of the major changes in v2.0. The migration tool handles most of these automatically.

Change	Severity	Description
`Button` props	Breaking	`variant` replaced `color`. Values changed from `primary/dark` to `solid/outline/ghost`.
`useTheme` hook	Breaking	Removed. Use `useDesignTokens` instead for accessing design system values.
Config structure	Breaking	`theme.colors` moved to `designSystem.palette`. `theme.typography` moved to `designSystem.fonts`.
Node version	Breaking	Minimum Node.js version is now 18.17.
SSR API	New	Introducing `renderToStaticMarkup` for better hydration performance.

Manual Migration Steps

After running the automated tool, review the following areas manually.

Update Component Imports

The migrator handles most imports, but verify any custom barrel exports. Components are now organized by category.

                            JavaScript
                            
// Before (v1.x)
import { Button, Modal, Card } from '@webui/components';

// After (v2.0)
import { Button } from '@webui/components/actions';
import { Modal } from '@webui/components/overlays';
import { Card } from '@webui/components/surfaces';

Refactor Design Tokens

Access to design tokens has changed. Use the useDesignTokens hook or the designTokens object.

                            React
                            
// Before (v1.x)
const { colors } = useTheme();
const primary = colors.primary;

// After (v2.0)
const { palette } = useDesignTokens();
const primary = palette.primary.DEFAULT;

Update Configuration File

Your webui.config.js structure has been updated. The migrator renames keys, but review custom plugins.

                            JavaScript
                            
                        

// webui.config.js (v2.0)
export default {
  designSystem: {
    palette: {
      primary: '#6C3CE1',
      accent: '#00D4AA',
    },
    fonts: {
      sans: 'Inter, sans-serif',
      mono: 'JetBrains Mono, monospace',
    },
    spacing: 4,
  },
  plugins: [
    // Custom plugins may need updates
  ],
};
                        

Troubleshooting

Migration Fails on Node 16

If you see an error about unsupported Node version, you must upgrade Node.js first. Webui v2.0 uses features that require Node 18+.

🚫

Error: EACCES or Node Version Mismatch

Ensure you have Node 18.17+ and try running the migration with sudo or after fixing permissions.

Styles Not Loading

v2.0 switched to CSS-in-JS runtime. Ensure you've added the WebuiProvider at the root of your app.

                        React
                        
                    

import { WebuiProvider } from '@webui/core';

function App() {
  return (
    <WebuiProvider>
      <YourApp />
    </WebuiProvider>
  );
}
                    

Hydration Mismatches

If you see hydration warnings, check for dynamic class names or client-only logic in your root components. Wrap them in useEffect or use the suppressHydrationWarning prop on affected elements.

FAQ

Can I downgrade back to v1.x?

Yes, but the migration tool is one-way. You'll need to manually revert changes or restore from a backup branch. We recommend keeping v1.x in a separate branch until you're confident in v2.0.

Will v1.x still be supported?

v1.x will receive security patches until March 2025. No new features will be added. We encourage all users to migrate to v2.0 for the best experience.

Does the migration work with Next.js?

Yes. The migration tool detects Next.js projects and applies framework-specific transforms. Ensure you're using Next.js 13+ with the App Router for full compatibility.

✅

Migration Complete?

Once you've completed the steps above, run npm run build and test your application. If everything looks good, commit your changes and celebrate! 🎉

← Previous Installation Guide Next → Breaking Changes Detail