miniprogram-compiler

0.2.3 verified Fri May 01 auth: no javascript

Node.js wrapper for WeChat Mini Program official compilers (wcc for WXML, wcsc for WXSS). Version 0.2.3 is the latest stable release. It enables compiling .wxml and .wxss files into JavaScript functions that can render virtual DOM or CSS strings. Compared to alternatives like @vant/weapp or raw CLI tools, this package provides a programmatic API suitable for server-side rendering or testing. Release cadence is low; limited to basic compilation use. Only for Node.js (CJS only).

Common errors

error TypeError: compilerString is not a function ↓

cause Calling wxmlToJs result directly instead of wrapping in new Function.

fix

Use new Function('global', compilerString) to create a function.

error TypeError: $gwx is not a function ↓

cause The compiler evaluation didn't return a valid $gwx function (wrong project root or missing wxml files).

fix

Ensure the project root contains the expected files and that you called compiler({}) correctly.

Warnings

gotcha Package is CJS-only; ES imports will fail. ↓

fix Use require() or configure bundler to handle CJS modules.

gotcha The first argument to wxmlToJs and wxssToJs must be an absolute path to the mini program project root directory. ↓

fix Use path.resolve() to provide an absolute path.

gotcha wxmlToJs and wxssToJs may throw if the project root does not exist or does not contain mini program files. ↓

fix Ensure the directory exists and contains valid project files.

gotcha The returned compiler string must be evaluated with a function constructor; not just required/imported. ↓

fix Use new Function('global', compilerString) and then invoke with an object.

gotcha The $gwx function expects file paths relative to the project root, not absolute paths. ↓

fix Pass relative paths like 'pages/index/index.wxml'.

Install

npm install miniprogram-compiler

yarn add miniprogram-compiler

pnpm add miniprogram-compiler

Imports

wxmlToJs

wrong

import { wxmlToJs } from 'miniprogram-compiler';

correct

const { wxmlToJs } = require('miniprogram-compiler');

Package is CJS-only; ES import will fail.

wxssToJs

const { wxssToJs } = require('miniprogram-compiler');

Also CJS-only. No default export.

Quickstart

Compiles a .wxml file into a virtual DOM generator using the provided project root.

const { wxmlToJs } = require('miniprogram-compiler');
const path = require('path');

const miniprogramProjectRoot = path.resolve('./test');
const compilerString = wxmlToJs(miniprogramProjectRoot);
const compiler = new Function('global', compilerString);
const $gwx = compiler({});
const generateFunc = $gwx('wxml/index.wxml');
const result = generateFunc({
  message: 'Hello',
  list: [1, 2, 3]
});
console.log(result);