weapp-cookie: giving WeChat mini programs a cookie jar

The gap: a mini program has no cookie jar

The README's Intro section states the problem in a sentence. The native request interface of a mini program does not support traditional cookies, but sometimes the existing backend interfaces really do depend on cookies, for example a server-side login state. The library implements a cookie mechanism for your mini program with one line of code, so that a session based on cookies does not expire and can be shared with the web side.

That last part is the interesting one. The problem is not only that a mini program cannot hold a cookie, it is that the same user, in the same session, may be talking to the same backend from a browser and from a mini program, and the backend expects the session identifier to be in a cookie. Without a cookie jar in the mini program, the user is logged out of the mini program the moment they log in on the web, and the application has to carry a third-party session key in every request instead.

The feature list is short and matches that promise: one line of code makes the mini program support cookies, an API is provided to get and set cookies, and domain and path scoping is supported.

The project is JavaScript, published on npm as weapp-cookie, with the repository metadata recording an MIT licence and the package manifest in the repository recording ISC, and the default branch on master. The last push was on 2026-09-25, and the published releases are v1.2.6 in November 2018 and 1.4.6 in January 2020.

It proxies wx.request underneath

The mechanism is the part that makes the promise of one line of code true.

The original wx.request calling style stays unchanged. After the import, weapp-cookie automatically proxies the wx.request interface at the underlying level, to support cookie storage and sending. The README illustrates it in a page that logs in:

wx.requestWithCookie({
    url: 'https://example.com/user/current',
    success: function (res) {
        console.log(res)
    }
})

In the success callback, weapp-cookie automatically saves every cookie the backend sends, a session identifier for instance, and includes it in all subsequent requests, so that a cookie based server session mechanism does not expire. The effect the README describes is sharing a session mechanism with the web, with no need to maintain a third-party session key by hand.

That is the whole trick, and it explains why the library is small. It does not implement an HTTP client, it wraps the one you already have, and the cookie jar is a store that is consulted on the way out and updated on the way back.

It also explains the one sharp edge in the library, which is the alias mechanism, and that comes next.

WeChat will not let a plugin rewrite wx.request

There is a platform constraint in the middle of this, and the README explains it clearly.

Because of the WeChat mini program security mechanism, wx.request is not allowed to be overwritten in the mini program plugin environment, so a built-in alias or a custom alias has to be used to support cookie requests.

The built-in alias is wx.requestWithCookie, which is the version shown in the previous section. The custom alias is configured through the library's own config call:

cookies.config({ requestAlias: 'requestx' })

and then the alias is used the same way, wx.requestx in place of wx.request, with the same url and success callback.

So there are two ways to use the library depending on where it runs. In an ordinary mini program, the import at the top of app.js is enough, and the interception happens transparently for every wx.request in the app. In a plugin environment, the interception is not permitted, so the calls have to be written against an alias, and the library gives you one that you can name.

That is a small API with a real reason behind it, and it is a good example of a library documenting a platform limitation instead of pretending it does not exist. The cost for a user is that the alias has to be used in the code, and that the choice of alias name is visible in the source of every call that uses it.

The cookie API, and the scoping rules

Cookies are reached through a default export, and the operations mirror the browser cookie API closely enough to be recognisable.

let token = cookies.get('csrf_token', 'example.com')
let cookie = cookies.set('uid', 100, { domain: 'example.com' })
let isRemoved = cookies.remove('uid', 'example.com')
let hasToken = cookies.has('uid', 'example.com')

The domain argument is optional everywhere. When it is omitted, the operation applies to any domain, which is stated in the API documentation for has and remove, and it is the reason the same cookie name can exist for several hosts in one mini program.

The full API has more than these four. There is getCookie, which returns the cookie object rather than its value, getCookies, which returns an object of cookie values for a domain or for all domains, clearCookies, which clears the cookies for a domain or for everything, and dir, which returns the structure of all stored domains and cookies. The set method takes an options object with domain, path, expires, maxAge and httpOnly, and it returns the cookie object that was created.

That object has the usual properties, name, value, domain, path, expires, maxAge and httpOnly, and two methods of its own, isExpired() and isPersistence(), which answer whether the cookie is past its expiry and whether it will survive a restart. Those two methods are small but useful, because a mini program that keeps state in memory has to work out for itself whether the session it is holding is still valid, and a browser normally does that for you.

Installing it, and the vendor copy

Installation is an npm install with the save flag:

npm install weapp-cookie --save

And then a second step that catches people out, because the mini program build does not always resolve node_modules the way a bundler does. The README's advice is to copy the npm package into a vendor folder to avoid the mini program not finding the file, and it notes that a development environment which supports npm packages does not need this step:

cp -rf ./node_modules/ ./vendor/

With that done, the import goes at the top of the root app.js:

import './vendor/weapp-cookie/dist/weapp-cookie'

And in an environment that supports npm packages, which the README names as uni-app, wepy and mpvue, the module can be imported directly in the entry file as weapp-cookie.

The choice of the vendor path is therefore a deployment decision rather than a development one, and the copy step is what keeps the mini program build working on the platform tools that do not resolve packages the way webpack does.

One detail from the repository is worth noticing for anyone who has to debug this in the field. The package manifest points its main entry at dist/weapp-cookie.js, and the files array ships assets, dist, src, test and index.js, so the published package contains both the built bundle and the sources, which means the import path that works for a bundler is not necessarily the one that works in a plain mini program project.

A gulp and rollup build with one runtime dependency

The package manifest is from the era when the toolchain looked like this, and it is worth reading because it explains what the library does and does not do.

There is exactly one runtime dependency, set-cookie-parser at ^2.3.8, and that single entry tells you the design. The library does not implement cookie parsing, it uses a parser for Set-Cookie headers, and everything else it does is store the parsed values and put them back into outgoing requests.

The development dependencies are the tooling of that period: gulp at ^3.9.1 as the task runner, with gulp-babel, gulp-concat, gulp-eslint, gulp-watch and gulp-webserver, rollup at ^0.49.3 with the babel, commonjs and node-resolve plugins, a set of babel-preset-es2015 packages, babel-register, mocha at ^5.2.0 for the tests, and the standard eslint-config-standard family with the html, import, node, promise and standard plugins.

The scripts are three: build is gulp build, lint is gulp lint, and test is mocha. The repository listing matches, with a gulpfile.js at the root, a src/ directory for the source, a dist/ directory for the built bundle, a build/ directory, a test/ directory, an index.js, a .babelrc and an .eslintrc.

So the library is a small amount of source, built with rollup under gulp, tested with mocha, and shipped with one dependency. For a package whose entire job is to wrap the platform's request function, that is a proportionate amount of machinery, and it is also the machinery that will need attention if you pick it up again, since rollup 0.49 and gulp 3.9 are both well past their supported years.

Six years between the release and the last commit

The release history and the commit history tell different stories, and the difference is worth weighing before you depend on the package.

The releases are v1.2.6 on 2018-11-16 and 1.4.6 on 2020-01-02, and the version in the package manifest is 1.4.6, matching the newest release. The last push to the repository was on 2026-09-25, more than six years after that release.

So the published package is from January 2020, and the repository has been touched since, without a new release. The practical consequence is the one that matters for a dependency: if you install from npm, you get the 2020 build, and the recent commits are not in it. If you want the recent state, you have to build from source, and the source is built with a toolchain from 2018.

The licence question is similar. The repository's own metadata lists MIT, while the package manifest inside it lists ISC, and the README does not state a licence. For a package whose job is to hold session cookies for your users, the difference between those two licences is not academic: ISC is a permissive licence with a short notice requirement, and MIT is permissive with the same kind of requirement, so in practice the difference is small, but the two statements in the same repository should not both be relied on. Read the LICENSE file that is actually in the repository.

The remaining question is whether the code still fits. The interception approach is still the right approach for the platform, and the alias mechanism is a response to a platform rule that has not changed, so the design has aged better than the toolchain. The parts to check first are the cookie parsing against the Set-Cookie headers your backend actually sends, and the storage behaviour when the mini program is closed and reopened, which is where a cookie library earns its keep or loses it.

Editorial conclusion

Adopt weapp-cookie if you have a mini program talking to a backend that authenticates with cookies, because the alternative is maintaining a third-party session key by hand in every request, and the library does the storage, the domain scoping and the resending for you. Do not adopt it if your backend uses token headers, because there is nothing to solve in that case, and be aware that it works by intercepting the request API, so it needs the alias path in a plugin environment. Before you install it, check the version you get, because the newest published release is 1.4.6 from January 2020, and confirm which licence applies, since the repository metadata and the package manifest in the repository name different licences.

Frequently asked questions

Official sources

1. charleslo1/weapp-cookie on GitHub
2. Issues
3. License: MIT
4. README
5. Releases