{"id":16039972,"url":"https://github.com/sonofmagic/weapp-pandacss","last_synced_at":"2025-07-13T12:32:59.782Z","repository":{"id":184260359,"uuid":"671565798","full_name":"sonofmagic/weapp-pandacss","owner":"sonofmagic","description":"To use pandacss in weapp! ","archived":false,"fork":false,"pushed_at":"2025-02-08T10:27:32.000Z","size":2415,"stargazers_count":16,"open_issues_count":13,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-06T21:46:09.057Z","etag":null,"topics":["css-in-js","panda","pandacss","react","tarojs"],"latest_commit_sha":null,"homepage":"https://sonofmagic.github.io/weapp-pandacss/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sonofmagic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["sonofmagic"],"custom":["https://github.com/sonofmagic/sponsors"]}},"created_at":"2023-07-27T15:57:26.000Z","updated_at":"2025-04-09T10:26:11.000Z","dependencies_parsed_at":"2023-07-27T18:07:04.783Z","dependency_job_id":"3a4c21a1-dabf-448f-8e54-9cfdcb03e834","html_url":"https://github.com/sonofmagic/weapp-pandacss","commit_stats":{"total_commits":112,"total_committers":4,"mean_commits":28.0,"dds":0.4910714285714286,"last_synced_commit":"96a0f9341af562761167767e3eabf3730972cfb8"},"previous_names":["sonofmagic/weapp-pandacss"],"tags_count":24,"template":false,"template_full_name":"sonofmagic/npm-lib-template","purl":"pkg:github/sonofmagic/weapp-pandacss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fweapp-pandacss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fweapp-pandacss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fweapp-pandacss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fweapp-pandacss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sonofmagic","download_url":"https://codeload.github.com/sonofmagic/weapp-pandacss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sonofmagic%2Fweapp-pandacss/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265139271,"owners_count":23717283,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["css-in-js","panda","pandacss","react","tarojs"],"created_at":"2024-10-08T23:09:17.747Z","updated_at":"2025-07-13T12:32:59.734Z","avatar_url":"https://github.com/sonofmagic.png","language":"TypeScript","funding_links":["https://github.com/sponsors/sonofmagic","https://github.com/sonofmagic/sponsors"],"categories":[],"sub_categories":[],"readme":"# weapp-pandacss\n\n[![codecov](https://codecov.io/gh/sonofmagic/weapp-pandacss/branch/main/graph/badge.svg?token=vnU71Pxj3P)](https://codecov.io/gh/sonofmagic/weapp-pandacss)\n![star](https://badgen.net/github/stars/sonofmagic/weapp-pandacss)\n![dm0](https://badgen.net/npm/dm/weapp-pandacss)\n![license](https://badgen.net/npm/license/weapp-pandacss)\n\n- [weapp-pandacss](#weapp-pandacss)\n  - [介绍](#介绍)\n  - [快速开始](#快速开始)\n    - [pandacss 安装和配置](#pandacss-安装和配置)\n      - [0. 安装和初始化 pandacss](#0-安装和初始化-pandacss)\n      - [1. 配置 postcss](#1-配置-postcss)\n      - [2. 检查你的 panda.config.ts](#2-检查你的-pandaconfigts)\n      - [3. 修改 package.json 脚本](#3-修改-packagejson-脚本)\n      - [4. 全局 css 注册 pandacss](#4-全局-css-注册-pandacss)\n      - [5. 配置的优化与别名](#5-配置的优化与别名)\n    - [weapp-pandacss 配置](#weapp-pandacss-配置)\n      - [0. 回到 postcss 进行注册](#0-回到-postcss-进行注册)\n      - [1. 回到 package.json 添加生成脚本](#1-回到-packagejson-添加生成脚本)\n  - [跨平台注意事项](#跨平台注意事项)\n  - [小程序预览事项](#小程序预览事项)\n  - [高级配置文件](#高级配置文件)\n  - [配置项列表](#配置项列表)\n  - [参考示例](#参考示例)\n  - [Bugs \\\u0026 Issues](#bugs--issues)\n\n## 介绍\n\n[`pandacss`](https://panda-css.com/) 是个优秀的 `CSS-in-JS` 编译时框架，原子化和 `[jt]sx?` 文件相结合的写法灵活而又令人印象深刻，而 `weapp-pandacss` 就是让你在小程序开发中使用它。\n\n## 快速开始\n\n### pandacss 安装和配置\n\n#### 0. 安装和初始化 pandacss\n\n首先我们需要把 `@pandacss/dev` 这些都安装和配置好，这里我们以 `tarojs` 项目为例：\n\n```bash\nnpm install -D @pandacss/dev weapp-pandacss postcss # 或者 yarn / pnpm\nnpx panda init\n```\n\n此时会在当前目录生成一个 `panda.config.ts` 和一个包含大量文件的 `styled-system`。\n\n\u003e `panda.config.ts` 是 `pandacss` 的配置文件，`styled-system` 文件夹里的是 `pandacss` 的运行时 `js`。\n\n把 `styled-system` 加入我们的 `.gitignore` 中去。\n\n```diff\n# .gitignore\n+ styled-system\n```\n\n#### 1. 配置 postcss\n\n接着在根目录里，添加一个 `postcss.config.cjs` 文件，写入以下代码注册 `pandacss`:\n\n```js\nmodule.exports = {\n  plugins: {\n    '@pandacss/dev/postcss': {}\n  }\n}\n```\n\n#### 2. 检查你的 panda.config.ts\n\n生成的配置文件大概长下面这样，尤其注意 `include` 是用来告诉 `pandacss` 从哪些文件中提取原子类的，所以这个配置一定要准确\n\n```ts\nimport { defineConfig } from \"@pandacss/dev\"\n\nexport default defineConfig({\n  // 小程序不需要\n  preflight: process.env.TARO_ENV === 'h5',\n  // ⚠️这里，假如你使用 vue，记得把 vue 文件格式包括进来！！！\n  include: [\"./src/**/*.{js,jsx,ts,tsx}\"],\n  exclude: [],\n  theme: {\n    extend: {}\n  },\n  outdir: \"styled-system\",\n})\n```\n\n#### 3. 修改 package.json 脚本\n\n然后，我们添加下方 `prepare` 脚本在我们的 `package.json` 的 `scripts` 块中:\n\n```diff\n{\n  \"scripts\": {\n+    \"prepare\": \"panda codegen\",\n  }\n}\n```\n\n这样我们每次重新 `npm i/yarn/pnpm i` 的时候，都会执行这个方法，重新生成 `styled-system`，当然你也可以直接通过 `npm run prepare` 直接执行这个脚本。\n\n#### 4. 全局 css 注册 pandacss\n\n然后在我们的全局样式文件 `src/app.scss` 中注册 `pandacss`:\n\n```css\n@layer reset, base, tokens, recipes, utilities;\n```\n\n配置好了之后，此时 `pandacss` 在 `h5` 平台已经生效了，你可以 `npm run dev:h5` 在 `h5` 平台初步使用了，但是为了开发体验，我们还有一些优化项要做。\n\n#### 5. 配置的优化与别名\n\n来到根目录的 `tsconfig.json` 添加:\n\n```diff\n{\n  \"compilerOptions\": {\n    \"paths\": {\n      \"@/*\": [\n        \"src/*\"\n      ],\n+      \"styled-system/*\": [\n+        \"styled-system/*\"\n+      ]\n    }\n  },\n  \"include\": [\n    \"./src\",\n    \"./types\",\n    \"./config\",\n+    \"styled-system\"\n  ],\n}\n```\n\n接着来到 `config/index.ts` 添加 `alias`([参考链接](https://taro-docs.jd.com/docs/config-detail#alias)):\n\n```ts\nimport path from 'path'\n\n{\n  alias: {\n    'styled-system': path.resolve(__dirname, '..', 'styled-system')\n  },\n}\n```\n\n这样我们就不需要使用相对路径来使用 `pandacss` 了，同时 `ts` 智能提示也有了，你可以这样使用它:\n\n```ts\nimport { View, Text } from \"@tarojs/components\";\nimport { css } from \"styled-system/css\";\n\nconst styles = css({\n  bg: \"yellow.200\",\n  rounded: \"9999px\",\n  fontSize: \"90px\",\n  p: \"10px 15px\",\n  color: \"pink.500\",\n});\n\nexport default function Index() {\n  return (\n    \u003cView className={styles}\u003e\n      \u003cText\u003eHello world!\u003c/Text\u003e\n    \u003c/View\u003e\n  );\n}\n```\n\n\u003e 此部分参考的官方链接 \u003chttps://panda-css.com/docs/installation/postcss\u003e\n\n接下来进入 `weapp-pandacss` 的插件配置，不用担心，相比前面那些繁琐的步骤，这个可简单多了。\n\n### weapp-pandacss 配置\n\n\u003e 记得安装好 `weapp-pandacss` !\n\n#### 0. 回到 postcss 进行注册\n\n回到项目根目录的 `postcss.config.cjs` 注册 `weapp-pandacss`，添加以下配置:\n\n```diff\nmodule.exports = {\n  plugins: {\n    '@pandacss/dev/postcss': {},\n+   'weapp-pandacss/postcss': {}\n  }\n}\n```\n\n#### 1. 回到 package.json 添加生成脚本\n\n然后去 `package.json` 你添加 `prepare` 脚本的地方，加点代码\n\n```diff\n{\n  \"scripts\": {\n-    \"prepare\": \"panda codegen\",\n+    \"prepare\": \"panda codegen \u0026\u0026 weapp-panda codegen\",\n  }\n}\n```\n\n\u003e 注意这里必须用 `\u0026\u0026` 而不能用 `\u0026`，`\u0026` 任务执行会并行不会等待，而 `\u0026\u0026` 会等待前一个执行完成再执行后一条命令\n\n然后，你再手动执行一下\n\n```bash\nnpm run prepare\n```\n\n来重新生成 `styled-system`, 此时你会发现 `pandacss` 的命令行输出中多了 `2` 行:\n\n```diff\n✔️ `src/styled-system/css`: the css function to author styles\n✔️ `src/styled-system/tokens`: the css variables and js function to query your tokens\n✔️ `src/styled-system/patterns`: functions to implement apply common layout patterns\n✔️ `src/styled-system/jsx`: styled jsx elements for react\n+ ✔️ `src/styled-system/weapp-panda`: the core escape function for weapp\n+ ✔️ `src/styled-system/helpers.mjs`: inject escape function into helpers\n```\n\n这代表着小程序相关的转义逻辑已经被注入进去，此时 `panda css` 生成的类就兼容小程序平台啦，是不是很简单?\n\n当然为了防止你配置失败，我也给出了参考项目: [taro-react-pandacss-template](https://github.com/sonofmagic/taro-react-pandacss-template) 方便进行排查纠错。\n\n## 跨平台注意事项\n\n你可能同时开发 `小程序` 和 `h5` 平台，但是你发现使用 `weapp-pandacss` 之后，`h5` 平台似乎就不行了？\n\n这时候你可以这样配置：\n\n`process.env.TARO_ENV === 'h5'` 的时候，不去加载 `weapp-pandacss/postcss` (根据环境变量动态加载 `postcss` 插件)\n\n同时你也可以执行 `weapp-panda rollback` 把 `css` 方法进行回滚到最原始适配 `h5` 平台的状态。\n\n当然你恢复到小程序版本也只需要执行 `weapp-panda codegen` 就会重新注入了。\n\n## 小程序预览事项\n\n当小程序预览时会出现 `Error: 非法的文件，错误信息：invalid file: pages/index/index.js, 565:24, SyntaxError: Unexpected token . if (variants[key]?.[value])` 错误。\n\n这是因为 `panda` 生成的文件 `cva.mjs` 使用了 [`Optional chaining (?.)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining)语法，这个语法小程序原生不支持导致的，这种情况可以参考以下的配置：\n\n```ts\n// taro 应用中，默认只会处理 [jt]sx? 这类的文件，所以要添加 cjs/mjs 再交给 babel 处理一下\n// 假如你使用 pnpm 的话，你还要执行一下 `pnpm add -D babel-loader`, 把 `babel-loader` 提到最外面一层，不然会出现 require.resolve 找不到的问题\n// config/index.ts 文件中的 webpackChain 方法，你可以把 mini 和 h5 都加上\nchain.merge({\n  module: {\n    rule: [\n      {\n        test: /\\.[cm]js$/i,\n        loader: 'babel-loader'\n      }\n    ]\n  },\n})\n```\n\n或者你可以开启开发者工具中的 `将JS编译成ES5` 功能再进行预览。\n\n## 高级配置文件\n\n你可以通过 `npx weapp-panda init` 命令在当前目录下创建一个 `weapp-pandacss.config.ts` 配置文件。\n\n这个配置文件可以用来控制转义代码的生成和一部分 `postcss` 插件的行为。\n\n```ts\nimport { defineConfig } from 'weapp-pandacss'\n\nexport default defineConfig({\n  postcss: {\n    // 转义插件是否生效，这只能控制核心插件的生效情况,而核心插件只是一部分\n    // 假如你想让整个插件真正不生效，请在 `postcss.config.cjs` 里进行动态加载判断\n    disabled: false,\n    // 数组merge默认行为是直接concat 合并，所以传一个空数组是使用的默认数组\n    // 转义替换对象\n    selectorReplacement: {\n      root: [],\n      universal: [],\n      cascadeLayers: 'a'\n    },\n    removeNegationPseudoClass: true\n  },\n  // 生成上下文\n  context: {\n    // 转义注入判断条件，更改后需要重新生成代码\n    escapePredicate: `process.env.TARO_ENV !== 'h5' \u0026\u0026 process.env.TARO_ENV !== 'rn'`,\n    // 插件的 pandaConfig 寻找配置\n    pandaConfig: {\n      cwd: process.cwd(),\n      file: 'path/to/your-panda-config-file'\n    }\n  }\n})\n```\n\n当然，你更改相关的配置项之后，要重新执行一下 `npm run prepare` 来生成新的注入转义代码。\n\n## 配置项列表\n\n详见 \u003chttps://sonofmagic.github.io/weapp-pandacss/\u003e\n\n## 参考示例\n\n[taro-react-pandacss-template](https://github.com/sonofmagic/taro-react-pandacss-template)\n\n[Taro-app react](./examples/taro-app)\n\n[Taro-app vue3](./examples/taro-app-vue3)\n\n[Uni-app vue3 vite](./examples/uni-app-vue3)\n\n## Bugs \u0026 Issues\n\n目前这个插件正在快速的开发中，如果遇到 `Bug` 或者想提出 `Issue`\n\n[欢迎提交到此处](https://github.com/sonofmagic/weapp-pandacss/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonofmagic%2Fweapp-pandacss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsonofmagic%2Fweapp-pandacss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsonofmagic%2Fweapp-pandacss/lists"}