迁移指南 #

1. 安装 Preact
2. 配置别名
3. 修改导入
4. 处理差异
5. 测试验证

npm install preact

# 如果需要 React 兼容
npm install preact

npm uninstall react react-dom

import { defineConfig } from 'vite';
import preact from '@preact/preset-vite';

export default defineConfig({
  plugins: [preact()],
  resolve: {
    alias: {
      'react': 'preact/compat',
      'react-dom': 'preact/compat',
      'react-dom/test-utils': 'preact/test-utils',
      'react/jsx-runtime': 'preact/jsx-runtime'
    }
  }
});

module.exports = {
  resolve: {
    alias: {
      'react': 'preact/compat',
      'react-dom': 'preact/compat',
      'react-dom/test-utils': 'preact/test-utils'
    }
  }
};

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact",
    "paths": {
      "react": ["./node_modules/preact/compat"],
      "react-dom": ["./node_modules/preact/compat"]
    }
  }
}

// React
import React from 'react';
import ReactDOM from 'react-dom';
import { useState, useEffect } from 'react';

// Preact（使用别名后无需修改）
import React from 'react';
import ReactDOM from 'react-dom';
import { useState, useEffect } from 'react';

// Preact（直接导入）
import { render } from 'preact';
import { useState, useEffect } from 'preact/hooks';
import { Component } from 'preact';

// React
import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

// Preact
import { render } from 'preact';

render(<App />, document.getElementById('root'));

// Preact（使用 compat）
import { createRoot } from 'react-dom/client';

const root = createRoot(document.getElementById('root'));
root.render(<App />);

// React
import React from 'react';

class MyComponent extends React.Component {
  render() {
    return <div>Hello</div>;
  }
}

// Preact
import { Component } from 'preact';

class MyComponent extends Component {
  render() {
    return <div>Hello</div>;
  }
}

// React 合成事件
function handleClick(e) {
  e.persist(); // 如果需要异步访问
  setTimeout(() => {
    console.log(e.target.value);
  }, 1000);
}

// Preact 原生事件
function handleClick(e) {
  // 无需 persist
  setTimeout(() => {
    console.log(e.target.value);
  }, 1000);
}

// React
<div className="container">
  <label htmlFor="input">Label</label>
</div>

// Preact（两种都支持）
<div className="container">
  <label htmlFor="input">Label</label>
</div>

// Preact（推荐）
<div class="container">
  <label for="input">Label</label>
</div>

// React 合成事件特性
function ReactComponent() {
  const handleClick = (e) => {
    // 合成事件
    console.log(e.nativeEvent); // 原生事件
    e.isPropagationStopped();   // 方法
    e.isDefaultPrevented();     // 方法
  };
}

// Preact 原生事件
function PreactComponent() {
  const handleClick = (e) => {
    // 原生事件
    console.log(e); // 直接是原生事件
    // 无 isPropagationStopped 等方法
  };
}

// React
class Component extends React.Component {
  getSnapshotBeforeUpdate(prevProps, prevState) {
    return { scrollTop: this.listRef.current.scrollTop };
  }

  componentDidUpdate(prevProps, prevState, snapshot) {
    if (snapshot !== null) {
      this.listRef.current.scrollTop = snapshot.scrollTop;
    }
  }
}

// Preact（不支持 getSnapshotBeforeUpdate）
// 使用 useLayoutEffect 替代
function Component() {
  const listRef = useRef(null);
  const prevScrollTop = useRef(0);

  useLayoutEffect(() => {
    prevScrollTop.current = listRef.current.scrollTop;
  });

  useEffect(() => {
    // 更新后操作
  });
}

// React
class ErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    console.log(errorInfo.componentStack); // 组件堆栈
  }
}

// Preact
class ErrorBoundary extends Component {
  componentDidCatch(error) {
    // 无 errorInfo 参数
    console.log(error);
  }
}

// Preact Hook 方式
function ErrorBoundary({ children }) {
  const [error, resetError] = useErrorBoundary();
  
  if (error) {
    return <button onClick={resetError}>Retry</button>;
  }
  
  return children;
}

// 使用 preact/compat 别名后可直接使用
import { BrowserRouter, Routes, Route } from 'react-router-dom';

function App() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route path="/about" element={<About />} />
      </Routes>
    </BrowserRouter>
  );
}

// 使用 preact/compat 别名后可直接使用
import { Provider, useSelector, useDispatch } from 'react-redux';
import { configureStore } from '@reduxjs/toolkit';

const store = configureStore({ reducer: rootReducer });

function App() {
  return (
    <Provider store={store}>
      <Main />
    </Provider>
  );
}

// 某些依赖 React 内部 API 的库可能不兼容
// 解决方案：
// 1. 寻找 Preact 替代品
// 2. 使用 preact/compat 并测试
// 3. 联系库作者

// vitest.config.js
import { defineConfig } from 'vitest/config';
import preact from '@preact/preset-vite';

export default defineConfig({
  plugins: [preact()],
  test: {
    environment: 'jsdom',
    setupFiles: ['./test/setup.ts']
  }
});

// React Testing Library
import { render, screen } from '@testing-library/react';

// Preact Testing Library
import { render, screen } from '@testing-library/preact';

// 测试代码相同
test('renders button', () => {
  render(<Button>Click me</Button>);
  expect(screen.getByRole('button')).toBeInTheDocument();
});

// 添加类型声明
declare module 'preact' {
  namespace JSX {
    interface IntrinsicElements {
      // 自定义元素
    }
  }
}

// 检查 CSS 模块导入
import styles from './Button.module.css';

// 确保 class 正确应用
<button class={styles.button}>Click</button>

// 使用 memo 优化
import { memo } from 'preact/compat';

const MemoComponent = memo(function Component({ data }) {
  return <div>{data}</div>;
});

□ 安装 Preact 依赖
□ 配置构建工具别名
□ 修改入口文件渲染方式
□ 检查事件处理代码
□ 更新属性名称（可选）
□ 测试第三方库兼容性
□ 更新测试配置
□ 运行完整测试
□ 检查性能表现
□ 更新文档