Skip to main content

Use doctor command to diagnose project configuration

When the project has problems such as styles not being generated, classes in JS not being escaped, CSS entries not being scanned, plug-ins not taking effect on the target, etc., you can first run the doctor command to collect the project configuration status.

npx weapp-tailwindcss doctor

If you are not in the project root directory, you can specify the business project directory through --cwd:

npx weapp-tailwindcss doctor --cwd ./packages/miniprogram

Check content​

The doctor command only reads the local project file and does not modify the project configuration. Currently the following is checked:

Check itemsDescription
package.jsonConfirm whether the command is running in the project root directory
Node.jsCheck whether the current Node.js meets the minimum version requirements
Package ManagerIdentify packageManager, pnpm-lock.yaml, package-lock.json or yarn.lock
weapp-tailwindcssCheck whether the current project has this plug-in installed
tailwindcssCheck whether Tailwind CSS can be parsed and try to read the actual installed version
Tailwind configurationCheck if tailwind.config.* exists
PostCSS configurationCheck if postcss.config.* exists
Build mode configurationCheck if v5 project should remove Tailwind official PostCSS / Vite build plugin
Framework dependenciesIdentify Taro, uni-app, MPX, Remax
Builder ConfigurationRecognize vite.config.* or webpack.config.*

Output description​

Ordinary output is suitable for manual troubleshooting:

npx weapp-tailwindcss doctor

JSON output is suitable for use in issues, CI or automation scripts:

npx weapp-tailwindcss doctor --json

Strict mode returns a non-zero exit code when warn or error is present, suitable for placement in project inspection scripts:

npx weapp-tailwindcss doctor --strict

Common diagnostic results​

package.json not detected​

It means that the command is most likely not running in the project root directory. Please switch to the business project root directory and try again, or use --cwd to specify the directory.

npx weapp-tailwindcss doctor --cwd ./demo/uni-app-vue3-vite

tailwindcss not detected​

It means that tailwindcss is not installed in the current project, or the dependency cannot be resolved from the current directory. Please confirm that the dependency installation is complete before running the diagnostic command again.

Build mode projects still register the Tailwind official build plug-in​

weapp-tailwindcss@5 By default, the WeappTailwindcss builder plugin takes over Tailwind CSS generation. Do not register @tailwindcss/postcss or @tailwindcss/vite at the same time when building the mini program.

If the project already has postcss.config.*, only keep the business's own non-Tailwind plug-ins. The entry CSS of Tailwind CSS 4.x uses @import "tailwindcss" and @source; it should be passed to cssEntries explicitly through WeappTailwindcss, and the absolute path resolved from the project root directory should be used. cssEntries is not a switch that replaces import. The entry CSS still needs to be included in the build graph by the framework.

tailwind.config.* not detected​

Tailwind CSS 4 supports CSS-first configuration, and tailwind.config.* not being detected is not necessarily a problem. If the class in the JS string is not recognized, you need to check the @source in the CSS entry.

The current documentation only maintains Tailwind CSS 4 access instructions.

issue feedback and suggestions​

When submitting an issue, it is recommended to attach the following information:

npx weapp-tailwindcss doctor --json

Also add:

InformationExamples
FrameworkTaro / uni-app / MPX / Native applet
BuildersVite/Webpack/Gulp
Tailwind CSS versionv4
TargetWeChat Mini Program / H5 / App / Hongmeng
Reproduction commandpnpm dev:mp-weixin

This allows you to more quickly determine whether the problem is related to dependency installation, Tailwind scan range, PostCSS registration, plug-in disabling conditions, or mini-program limitations.