WeApp workflow with Gulp


null

Intro

WeApp-Workflow is a workflow that utilizes common web frontend build tools to build WeChat mini Programs. Based on Gulp 4, this workflow uses a build system to resolve some of the pain points faced by developers when writing Mini Programs.

Repo:https://github.com/Jeff2Ma/WeApp-Workflow

Article (Chinese):https://devework.com/weapp-workflow.html

Features

Transpile SCSS to WXSS

Utilize the Sass pre-processor to make writing CSS a smoother experience. Files with the .scss extension will automatically be watched and transpiled to the appropriate .wxss format for your MP.

Convert PX to RPX units

PX units in CSS get transpiled to RPX, referencing the size of iPhone 6 PX as a standard, as per Tencent's official documentation.

// Input: src/pages/index/index.scss
.index__header {
    font-size: 14px;
    margin-top: 20PX; /* If you write PX in all caps, it won't get converted*/
}

// Output: dist/pages/index/index.wxss
.index__header {
    font-size: 28rpx; /* converted 14px -> 28rpx*/
    margin-top: 20PX; /* PX all caps, not converted */
}

Image compression

The build system automatically compresses images to save space in your mini program.

Automatically upload images to CDN, replace with HTTPS URL

WeChat Mini Programs don't support relative paths for image imports, only absolute paths beginning with https protocol are supported. This feature of the workflow can take relative image paths from your WXML and WXSS files, upload them to your CDN or FTP/STP onto your server, and replace the file in your code. Currently only supports Tencent Cloud and QiNiu.

// Input: src/pages/index/index.wxml
<image src="%ASSETS_IMG%/t.png"></image>

// Output: dist/pages/index/index.wxml
<image src="https://cdn.devework.com/weapp/devework/t.png"></image>

Convert font files to base64

Mini programs don't support relative paths for font files, so this build system takes font faces used in your CSS, converts it to base64, and replaces the path in your CSS.

// Input: src/pages/index/index.scss
@font-face {
  font-family: 'fontello';
  src: url("assets/fonts/fontello.ttf") format('truetype');
}

// Output: dist/pages/index/index.wxss
@font-face {
  font-family: 'fontello';
  src: url(data:application/font-sfnt;charset=utf-8;base64,AAEAAAAPAIAA....FsASNsQIARAAA) format("truetype");
}

Fully automatic generation of sprites for Postcss

This feature comes from postcss-lazysprite. During development, after preparing an image you only have to write @lazysprite"xxxx" in your code, and the build system will create the sprite and corresponding CSS for you.

// Input: src/app.scss
@lazysprite "filetype";

// Output: dist/app.wxss
.icon-filetype-doc {
    background-image: url(../sprites/filetype.png);
    background-position: 0 0;
    width: 80px;
    height: 80px;
}

.icon-filetype-pdf {
    background-image: url(../sprites/filetype.png);
    background-position: -90px 0;
    width: 80px;
    height: 80px;
}

@media only screen and (-webkit-min-device-pixel-ratio: 2), only screen and (min-device-pixel-ratio:2) {
    .icon-filetype-doc {
        background-image: url(../sprites/filetype@2x.png);
        background-position: 0 0;
        background-size: 170px 170px;
    }

    .icon-filetype-pdf {
        background-image: url(../sprites/filetype@2x.png);
        background-position: -90px 0;
        background-size: 170px 170px;
    }
}

Highlights

Gulp 4

Uses all the features of the newest version of Gulp 4 for faster buold times

Simple but robust

With this workflow, there is just one core task to the build, taking care of a ton of busy work for you as the developer, greatly reducing tedium and repetitiveness in your development workflow.

Incremental implementation -> faster dev time

This workflow can be implemented incrementally, no need for 100% lock like a framework. Just using the sass compiler or image related functions can take serious time off your development workflow.

Folder structure

.
├── config.custom.js // your custom gulp config, will overwrite config.js
├── config.js // gulp config
├── gulpfile.js
├── package.json
├── src // dev folder, source code, where you write your code
│   ├── app.js
│   ├── app.json
│   ├── app.scss
│   ├── assets // static files, source files of assets
│   │   ├── fonts //font files
│   │   ├── images // image files, can be uploaded by build to CDN
│   │   ├── scss // where you usually put your scss files(variables, mixins, etc.)
│   │   └── sprites // source folder for image sprits
│   ├── image // for images that you actually need in the MP (tabbar, etc.)
│   ├── pages
│   └── utils
├── tmp //  the cache of temporary files compiled from src
└── dist // compiled output from src, the code that actually runs in the IDE and MP

Getting started

First, you need Node JS version 4.0 or higher. Because this build has dependencies, it is recommended you have a connection to the internet when running.

Installation

0、First, install globally Gulp-cli

npm install gulp-cli -g

1、Download the boilerplate with git clone

git clone https://github.com/Jeff2Ma/WeApp-Workflow

2、It's recommended that you delete the .git file in the directory. Windows users must manually delete.

cd WeApp-Workflow
rm -rf .git

3、Install dependencies

npm i

4、Start the development build
It's recommended that you copy config.js into config.custom.js if it doesn't exist already, and then build your custom build settings for your project. After you're ready:

gulp

null

There's also a clean command:gulp clean
This will delete the contents of dist & tmp

Config

After completing the setup steps above, you can open your WeChat IDE and apply the following config (applies to v1.x and up, no longer supporting v0.x):

1、Create a new project, and choose the entire working directory of your project, but make sure there is a project.config.json file in your directory pointing to the dist folder.

null

Developing

Now you can start writing code as normal! However, it is recommended you use a third party text editor or IDE (such as WebStorm, Sublime, etc.) to write your code in the src directory. After running gulp in the command line, gulp will be watching your files for changes and put the compiled code into the dist folder. The WeChat IDE will automatically refresh when the code in dist changes.

Tips for development:

  • SCSS: For example, if you write your scss in src/pages/page-name/page-name.scss, the build will automatically put your code as page-name.wxss in the dist folder, in the same path. px units in scss will automatically be converted to rpx unless you write the unit in all caps, like 120PX.
  • WXML: Other than CDN path replace function, wxml is still the same as normal, no changes.
  • WebFonts: First you can use a site such as fontell.com to convert your sprites to a ttf file, upon which you can put the file in src/assets/fonts, where it will then get converted to base64 by the build system.
  • CDN Images: This function is turned off by default, need to config manually. As mentioned, mini programs don't support relative paths in WXSS or WXML, you need to provide an absolute path starting with HTTPS. This workflow can allow you to write a relative path during development, which gets replaced with an absolute path to the image CDN of your choice. The build system uploads the image from src/assets/images and replaces it in the code in the dist folder. You can write the relative path in your WXML or CSS like so %ASSETS_IMG%/filename.png.
  • Image sprites: It's not recommended to use image sprites in mini programs, instead use the image itself or convert to a webfont format. If you must use image sprites, it's recommended to put them insrc/assets/sprites and use the @lazysprite "xxxx" syntax in your app.scss. For more info about image sprites click here.