​

🚀 Weaverse v5 is Here - Powered by React Router v7

​

What’s New in v5?

​

React Router v7 Foundation

• Modern Architecture: Complete migration from Remix to React Router v7
• Better Performance: Improved tree-shaking, faster builds, and better runtime performance
• Enhanced DX: Faster hot reloading and clearer error messages
• Future-Proof: Aligned with Shopify Hydrogen’s long-term roadmap

​

Key Benefits

• Faster build times with better tree-shaking
• Optimized bundle sizes for production
• Improved development server startup times

• Enhanced hot module reloading
• Better TypeScript integration
• Clearer error messages and debugging
• Modern React patterns and best practices

• Aligned with Shopify Hydrogen May 2025 release
• Compatible with the latest React ecosystem
• Foundation for upcoming Weaverse features

​

Before You Begin Migration

1. Backup your project and commit all changes
2. Test thoroughly in a development environment
3. Review dependencies that might be affected
4. Plan for downtime if upgrading production

​

Migration Options

​

Option 1: Start with a New Weaverse Theme (Recommended)

# Create a new React Router v7 project
npx @weaverse/cli@latest create --template=pilot --project-id="your-project-id" --project-name=my-hydrogen-storefront

# Copy your custom components and configurations
# from your old project to the new one

• Clean React Router v7 setup
• Latest best practices
• No migration complexity
• All new optimizations

• You have a relatively simple project
• Your customizations are primarily in components/sections
• You want the cleanest possible upgrade

​

Option 2: Upgrade Existing Project

• Preserve existing project structure
• Gradual migration possible
• Maintain current deployment setup

• You have extensive customizations
• Complex deployment configurations
• Want to maintain project history

​

Option 1: Creating a New Project (Fresh Start)

​

Step 1: Create New Project

# Create a new Weaverse project with React Router v7
npx @weaverse/cli@latest create my-upgraded-project --theme pilot

# Navigate to the new project
cd my-upgraded-project

​

Step 2: Migrate Your Customizations

1. Copy Custom Sections: Move your custom sections from app/sections/ in your old project to the new one
2. Update Components: Copy custom components and update any Remix-specific imports
3. Environment Variables: Copy your .env file and update any changed variable names
4. Styling: Migrate your custom styles and Tailwind configurations
5. Weaverse Configuration: Copy your weaverse/ directory configurations

​

Step 3: Update Weaverse Settings

1. Update the project preview URL to point to your new development server
2. Test all sections and components in the visual editor
3. Verify theme settings are working correctly

​

Step 4: Deploy and Test

1. Deploy your new project to your preferred hosting platform
2. Update your Weaverse project’s production URL
3. Test thoroughly before switching traffic

​

Option 2: Manual Migration (In-Place Upgrade)

​

Prerequisites

1. Shopify Hydrogen 2025.4.0 with all Remix Future Flags enabled
2. Node.js 20+ installed
3. All changes committed to version control

​

Step 1: Enable Remix Future Flags

// vite.config.ts
export default defineConfig({
  plugins: [
    // ... other plugins
    reactRouter({
      future: {
        v3_fetcherPersist: true,
        v3_relativeSplatPath: true,
        v3_throwAbortReason: true,
        v3_lazyRouteDiscovery: true,
        v3_routeConfig: true,
        v3_singleFetch: true,
      },
    }),
  ],
});

​

Step 2: Run React Router Migration Codemod

npx codemod remix/2/react-router/upgrade

• Import statements from Remix to React Router
• Component usage patterns
• Basic file structure changes

​

Step 3: Create React Router Configuration

// react-router.config.ts
import type {Config} from '@react-router/dev/config';

export default {
  appDirectory: 'app',
  buildDirectory: 'dist',
  ssr: true,
} satisfies Config;

​

Step 4: Update Vite Configuration

// vite.config.ts
export default defineConfig({
  plugins: [
    tailwindcss(),
    hydrogen(),
    oxygen(),
    reactRouter(),
    tsconfigPaths(),
  ],
  // ... rest of config
});

​

Step 5: Update Dependencies

npm install --force \
  @weaverse/hydrogen@5.0.0 \
  @shopify/hydrogen@2025.5.0 \
  @shopify/remix-oxygen@3.0.0 \
  @shopify/cli@3.80.4

​

Step 6: Update TypeScript Configuration

// env.d.ts
declare module 'react-router' {
  // TODO: remove this once we've migrated to `Route.LoaderArgs` for our loaders
  interface LoaderFunctionArgs {
    context: AppLoadContext;
  }

  // TODO: remove this once we've migrated to `Route.ActionArgs` for our actions
  interface ActionFunctionArgs {
    context: AppLoadContext;
  }
  // ... rest of your types
}

{
  "include": [
    "./**/*.d.ts",
    "./**/*.ts",
    "./**/*.tsx",
    ".react-router/types/**/*"
  ],
  "compilerOptions": {
    "rootDirs": [".", "./.react-router/types"],
    // ... rest of options
  }
}

​

Step 7: Update Git Ignore

# React Router
.react-router/

​

Step 8: Update Weaverse Components

// Before (Remix)
import { useLoaderData } from '@remix-run/react';
import type { LoaderFunctionArgs } from '@shopify/remix-oxygen';

// After (React Router v7)
import { useLoaderData } from 'react-router';
import type { LoaderFunctionArgs } from 'react-router';

​

Step 9: Test and Verify

# Generate types and run type checking
npm run codegen
npm run typecheck

# Start development server
npm run dev

​

Common Migration Issues

​

Import Errors

// Before
import { ... } from '@remix-run/react';
import { ... } from '@shopify/remix-oxygen';

// After
import { ... } from 'react-router';
import { ... } from '@shopify/hydrogen';

​

Type Errors

// Before
import type { LoaderFunctionArgs } from '@shopify/remix-oxygen';

// After  
import type { LoaderFunctionArgs } from 'react-router';

​

Build Errors

​

Testing Your Migration

​

Checklist

• Development server starts without errors
• All pages load correctly
• Weaverse visual editor functions properly
• Custom components render correctly
• Forms and interactions work as expected
• Build process completes successfully
• Production deployment works

​

Weaverse-Specific Testing

1. Visual Editor: Test all sections in the Weaverse studio
2. Theme Settings: Verify global theme settings work
3. Component Data: Ensure component loaders work correctly
4. Preview Mode: Test preview functionality
5. Section Management: Test adding/removing/reordering sections

​

What This Means for You (If Upgrading)

​

If You’re Just Getting Started with Weaverse

• No action needed for new projects - all new projects created with npx @weaverse/cli@latest create will use React Router v7.
• Enjoy better performance and developer experience out of the box.
• Access to the latest Weaverse features and improvements.

​

If You Have an Existing Weaverse Project (v4 or older)

• Plan your migration - this is a major version with breaking changes.
• Test thoroughly - use this guide and test in a development environment first.
• Take your time - v4 will continue to receive critical bug fixes, but we recommend upgrading for the best experience and future features.

​

Timeline & Backwards Compatibility

• v5.0.0: React Router v7 support released.
• v4.x: Continues to receive critical bug fixes for a limited time.
• Migration Period: We recommend migrating within 6 months for the best experience and continued support.
• Support: Full support and guidance available during the migration period.

​

Getting Help

1. Check the Console: Look for specific error messages.
2. Review Documentation: Refer to React Router v7 docs.
3. Community Support: Join our Slack Community.
4. Official Support: Contact support@weaverse.io.

​

What’s Next?

1. Update Documentation: Update your project’s README and internal docs.
2. Train Your Team: Familiarize your team with React Router v7 patterns.
3. Optimize Performance: Take advantage of new React Router v7 features.
4. Plan Updates: Schedule regular updates to stay current.

​

Thank You

​

Additional Resources

• Shopify Hydrogen May 2025 Release
• React Router v7 Documentation
• Weaverse Documentation
• Full Weaverse Changelog
• Questions about the migration? Join our Slack community or reach out to our support team at support@weaverse.io

​

Migration to v5

​

Breaking Changes

​

1. React Router v7 Migration

import { useLoaderData } from '@remix-run/react'
import type { LoaderFunction } from '@remix-run/node'

import { useLoaderData } from 'react-router'
import type { Route } from './+types/page'

​

2. Component Schema: Inspector → Settings

export const schema: HydrogenComponentSchema = {
  type: 'my-component',
  title: 'My Component',
  inspector: [
    {
      group: 'Content',
      inputs: [
        {
          type: 'text',
          name: 'heading',
          label: 'Heading',
          defaultValue: 'Welcome'
        }
      ]
    }
  ]
}

import { createSchema } from '@weaverse/hydrogen';

export let schema = createSchema({
  type: 'my-component',
  title: 'My Component',
  settings: [
    {
      group: 'Content',
      inputs: [
        {
          type: 'text',
          name: 'heading',
          label: 'Heading',
          defaultValue: 'Welcome'
        }
      ]
    }
  ]
});

• The system automatically handles both inspector and settings during the transition
• When both properties exist, settings takes priority
• Components using only inspector will show deprecation warnings but continue to work
• The structure of the inputs array remains exactly the same

​

3. Theme Schema Migration

export const themeSchema: HydrogenThemeSchema = {
  info: {
    name: 'My Theme',
    version: '1.0.0',
    author: 'Developer'
  },
  inspector: [
    {
      group: 'Colors',
      inputs: [
        {
          type: 'color',
          name: 'primaryColor',
          label: 'Primary Color',
          defaultValue: '#000000'
        }
      ]
    }
  ]
}

export const themeSchema: HydrogenThemeSchema = {
  info: {
    name: 'My Theme',
    version: '1.0.0',
    author: 'Developer'
  },
  settings: [
    {
      group: 'Colors',
      inputs: [
        {
          type: 'color',
          name: 'primaryColor',
          label: 'Primary Color',
          defaultValue: '#000000'
        }
      ]
    }
  ]
}

​

Migration Steps

​

Step 1: Update Dependencies

npm install @weaverse/hydrogen@latest

​

Step 2: Migrate Component Schemas

1. Rename inspector to settings in all component schemas:
   Copy

   Ask AI

   # You can use find and replace in your editor
   # Find: inspector: [
   # Replace: settings: [
   

2. Update TypeScript types if you have any custom type definitions referencing the inspector property.

​

Step 3: Update Theme Schema

​

Step 4: Test Your Components

1. Start your development server and verify that all components render correctly
2. Check the Weaverse Studio to ensure all settings panels work as expected
3. Look for deprecation warnings in the console and address any remaining inspector usage

​

Step 5: React Router Migration (if needed)

1. Update import statements throughout your codebase
2. Update route configurations to use React Router v7 patterns
3. Update type definitions to use React Router v7 types

​

Backward Compatibility

• Components with only inspector will continue to work but show deprecation warnings
• Components with both inspector and settings will use settings and ignore inspector
• The input structure and all input types remain unchanged

​

Common Issues and Solutions

​

Issue: Deprecation Warnings

​

Issue: Settings Not Appearing

1. Ensure you’ve renamed inspector to settings correctly
2. Restart your development server
3. Clear browser cache and refresh Weaverse Studio

​

Issue: Type Errors

​

Need Help?

1. Check the Component Schema Guide for detailed information
2. Review the API Types documentation for updated type definitions
3. Join our Discord community for support
4. Open an issue on GitHub if you find bugs

​

Benefits of v5

• Improved performance with React Router v7
• Better type safety with updated schema properties
• Enhanced developer experience with clearer naming conventions
• Future-proof architecture aligned with the latest Shopify Hydrogen standards