Awesome-omni-skill react-to-wx-miniprogram-migrator

Migrates a React + TailwindCSS H5 web application to a native WeChat Mini Program. Use when the user wants to convert their existing web project into a mini program, preserving structure, styling, and functionality.

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/development/react-to-wx-miniprogram-migrator" ~/.claude/skills/diegosouzapw-awesome-omni-skill-react-to-wx-miniprogram-migrator && rm -rf "$T"

manifest: skills/development/react-to-wx-miniprogram-migrator/SKILL.md

source content

React + TailwindCSS to WeChat Mini Program Migration Skill

This skill provides a systematic process for an AI agent to migrate a web application built with React and TailwindCSS into a native WeChat Mini Program. The goal is to achieve a functional and stylistically faithful conversion by mapping modern web development patterns to the specific architecture of WeChat Mini Programs.

When to Use This Skill

Use this skill when the user explicitly requests to convert a React-based H5 website, especially one using TailwindCSS for styling, into a native WeChat Mini Program. The source code of the React project should be available for analysis.

Migration Process Overview

The migration is a multi-step process that involves code transformation, style conversion, and API replacement. Follow these steps sequentially for a successful migration.

Analyze Source & Setup Project: Analyze the React project structure and set up a corresponding WeChat Mini Program project.
Component & JSX to WXML Conversion: Convert React components and JSX syntax into Mini Program components and WXML structure.
TailwindCSS to WXSS Conversion: Transform TailwindCSS utility classes into equivalent WXSS styles.
Logic & State Management Migration: Adapt React's state management (Hooks, Redux) and lifecycle to the Mini Program's
```
data
```
and
```
setData
```
system.
Routing & Navigation Replacement: Replace web-based routing (e.g., React Router) with the Mini Program's page navigation API.
API & SDK Replacement: Substitute browser/web APIs (e.g.,
```
fetch
```
,
```
localStorage
```
) with their WeChat Mini Program counterparts (
```
wx.request
```
,
```
wx.setStorageSync
```
).
Asset & Resource Handling: Migrate and correctly reference static assets like images and fonts.
Final Review & Debugging: Thoroughly test the migrated application in the WeChat DevTools and on a physical device.

Step-by-Step Migration Instructions

Step 1: Analyze Source & Setup Project

Analyze React Project: Use the
```
ls -R
```
or
```
tree
```
command to inspect the source React project's directory structure. Identify the main components, pages, utility functions, and static assets.
Create Mini Program Structure: Based on the analysis, create a standard WeChat Mini Program directory structure. Refer to
```
references/MIGRATION_MAP.md
```
for the standard structure.
- Create the
```
app.js
```
  ,
```
app.json
```
  , and
```
app.wxss
```
  root files.
- Create a
```
pages
```
  directory and subdirectories for each page identified in the React app.
- Create a
```
components
```
  directory for reusable components.
- Create a
```
utils
```
  directory for helper functions.
Configure
app.json
: Populate the
```
app.json
```
file. List all the pages in the
```
pages
```
field. If the H5 app has a tab bar, configure the
```
tabBar
```
field accordingly.

Step 2: Component & JSX to WXML Conversion

This is the core of the UI migration. Convert each React component into a Mini Program component folder containing

.js

.wxml

.wxss

, and

.json

files.

Map HTML Tags to WXML Components: For each JSX file, systematically replace HTML tags with their corresponding WXML component equivalents. A detailed mapping can be found in
```
references/MIGRATION_MAP.md
```
.
- ```
div
```
  ->
```
view
```
- ```
span
```
  ,
```
p
```
  ,
```
h1
```
  -
```
h6
```
  ->
```
text
```
- ```
img
```
  ->
```
image
```
- ```
a
```
  ->
```
navigator
```
- ```
button
```
  ->
```
button
```
Convert JSX Syntax: Transform JSX control flow and expressions into WXML directives.
- List Rendering: Convert
```
.map()
```
  calls to
```
wx:for
```
  loops.
- Conditional Rendering: Convert
```
&&
```
  ,
```
? :
```
  operators to
```
wx:if
```
  ,
```
wx:elif
```
  ,
```
wx:else
```
  directives.
- Data Binding: Convert
```
{variable}
```
  to
```
{{variable}}
```
  .
- Event Handling: Convert
```
onClick={handler}
```
  to
```
bindtap="handler"
```
  .

Step 3: TailwindCSS to WXSS Conversion

This is a critical and potentially complex step. The primary challenge is converting utility-first CSS into static WXSS stylesheets, as Mini Programs do not have a JIT compiler for styles.

Identify All Tailwind Classes: Scan all JSX files and extract every TailwindCSS class name used.
Convert Classes to CSS: Use an online tool or a script to convert the list of Tailwind classes into standard CSS. You can use this Tailwind to CSS Converter for this purpose.
Adapt CSS for WXSS: Manually adjust the generated CSS to be compatible with WXSS.
- Convert Units: Change
```
px
```
  or
```
rem
```
  units to
```
rpx
```
  . A common baseline is
```
1rem
```
  (16px) =
```
32rpx
```
  . Use this as a general rule but adjust for precision.
- Handle Unsupported Selectors: Replace unsupported selectors like the universal selector (
```
*
```
  ) or complex descendant selectors.
- Address
  gap
  Property: Since
```
gap
```
  is not supported, implement spacing between flex/grid items using
```
margin
```
  on the child elements.
Organize Styles: Paste the converted styles into the appropriate
```
.wxss
```
files. Global styles (from
```
index.css
```
or
```
App.css
```
) go into
```
app.wxss
```
, and component-specific styles go into the component's
```
.wxss
```
file.

Step 4: Logic & State Management Migration

Component Logic: Move the logic from the React component function body into the
```
Page({...})
```
or
```
Component({...})
```
object in the
```
.js
```
file.
State Management: Refactor React state to the Mini Program's
```
data
```
object.
- Convert
```
useState
```
  declarations to initial values in the
```
data
```
  object.
- Replace state update calls (e.g.,
```
setCount(1)
```
  ) with
```
this.setData({ count: 1 })
```
  .
Lifecycle Methods: Map React's lifecycle hooks to Mini Program lifecycle methods. See
```
references/MIGRATION_MAP.md
```
for a detailed mapping.
- ```
useEffect
```
  with an empty dependency array
```
[]
```
  maps to
```
onLoad
```
  .
- ```
useEffect
```
  with no dependency array maps roughly to
```
onShow
```
  .
- The return function from
```
useEffect
```
  maps to
```
onUnload
```
  .

Step 5: Routing & Navigation Replacement

Replace all instances of React Router or other routing libraries with the Mini Program's built-in navigation API.

<Link to="/path">

navigate('/path')

becomes

wx.navigateTo({ url: '/pages/path/index' })

Use
```
wx.switchTab
```
for navigating to tab bar pages.
Use
```
wx.redirectTo
```
for redirects.
Use
```
wx.navigateBack
```
for going back.

Step 6: API & SDK Replacement

Replace all browser-specific APIs with their

wx.

counterparts.

Network Requests: Replace
```
fetch
```
or
```
axios
```
with
```
wx.request
```
.

Local Storage: Replace

localStorage

with

wx.setStorageSync

and

wx.getStorageSync

DOM Manipulation: Remove all direct DOM manipulation code (e.g.,
```
document.getElementById
```
). Instead, use data binding to control the view.

Step 7: Asset & Resource Handling

Images: Move all image assets into a dedicated directory (e.g.,
```
/images
```
). Update all
```
<image>
```
```
src
```
paths to be absolute paths from the project root (e.g.,
```
/images/logo.png
```
).
Fonts: If custom fonts are used, they need to be loaded using
```
wx.loadFontFace
```
in
```
app.js
```
.

Step 8: Final Review & Debugging

Use WeChat DevTools: This is your primary environment for testing and debugging. Check the console for errors and use the WXML panel to inspect the UI structure.
Test on Device: Preview the Mini Program on a physical device to check for performance issues and styling inconsistencies that may not appear in the simulator.
Iterate and Refine: The migration process is iterative. Expect to go back and forth between steps to fix bugs and refine the user experience.

Bundled Resources

references/MIGRATION_MAP.md
: Contains detailed mapping tables for components, events, lifecycles, and APIs to assist in the conversion process.