@sohu-bpd/wechat

@sohu-bpd/wechat

WeChat JS-SDK utility library with initialization helpers and SPA support.

Features

• 🔄 SPA Support - Auto re-initialization on URL changes for single-page apps
• 📱 iOS Compatible - Handles iOS WeChat signature URL quirks automatically
• 🎯 High-level APIs - Simple config() and share() APIs for common tasks
• 📦 TypeScript - Full type definitions included
• 🌐 Multiple Formats - ESM, CommonJS, and IIFE bundles

Installation

npm install @sohu-bpd/wechat
# or
pnpm add @sohu-bpd/wechat
# or
yarn add @sohu-bpd/wechat

Quick Start

1. Load WeChat JS-SDK

First, include the WeChat JS-SDK script in your HTML:

<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>

2. Configure Once

import { config } from '@sohu-bpd/wechat'

config({
  getSignature: async (url) => {
    // Fetch signature from your backend
    const response = await fetch(`/api/wechat/signature?url=${encodeURIComponent(url)}`)
    return response.json()
  },
  debug: false,
  spa: true, // Enable SPA mode (default)
})

3. Use Anywhere

import { share } from '@sohu-bpd/wechat'

// Set share content
await share({
  title: 'My Page Title',
  desc: 'Share description',
  imgUrl: 'https://example.com/image.jpg',
  link: 'https://example.com/page', // optional, defaults to current URL
})

Usage

ESM / CommonJS

import { config, share } from '@sohu-bpd/wechat'

// or
const { config, share } = require('@sohu-bpd/wechat')

Browser (IIFE)

<!-- Load WeChat JS-SDK first -->
<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
<!-- Then load this library -->
<script src="https://unpkg.com/@sohu-bpd/wechat/dist/index.global.js"></script>
<script>
  const { config, share } = SohuWechat

  config({
    getSignature: async (url) => {
      const res = await fetch('/api/wechat/signature?url=' + encodeURIComponent(url))
      return res.json()
    }
  })

  share({
    title: 'My Page',
    desc: 'Description',
    imgUrl: 'https://example.com/image.jpg'
  })
</script>

API Reference

High-level APIs

config(options)

Set global configuration for WeChat JS-SDK.

Note: You must load the WeChat JS-SDK script in your HTML before using this library.

interface GlobalConfig {
  /** Function to fetch signature, receives current URL */
  getSignature: (url: string) => Promise<SignatureResult>
  /** Enable debug mode, default false */
  debug?: boolean
  /** Enable SPA mode (auto re-init on URL change), default true */
  spa?: boolean
}

function config(options: GlobalConfig): void

Example:

config({
  getSignature: async (url) => {
    const res = await fetch(`/api/wechat/signature?url=${encodeURIComponent(url)}`)
    return res.json()
  },
  debug: process.env.NODE_ENV === 'development',
  spa: true,
})

share(options)

Set WeChat share content for both friends and moments.

interface ShareOptions {
  /** Share title */
  title: string
  /** Share description (for friends) */
  desc?: string
  /** Share link, defaults to current URL */
  link?: string
  /** Share image URL */
  imgUrl: string
}

function share(options: ShareOptions): Promise<void>

Example:

await share({
  title: 'Amazing Product',
  desc: 'Check out this amazing product!',
  imgUrl: 'https://example.com/product.jpg',
  link: 'https://example.com/product/123',
})

getConfig()

Get current global configuration (throws if not configured).

function getConfig(): GlobalConfig

isConfigured()

Check if global configuration has been set.

function isConfigured(): boolean

Low-level APIs

For advanced use cases, you can use the low-level APIs:

initSDK(jsApiList)

Initialize WeChat SDK with specified APIs (automatically called by high-level APIs).

Note: Requires WeChat JS-SDK to be loaded globally first.

function initSDK(jsApiList: string[]): Promise<void>

getWx()

Get the global wx object after SDK is loaded.

function getWx(): any

resetSDK()

Reset SDK state (useful for testing or manual re-initialization).

function resetSDK(): void

Original init Function

For use cases that don't need global configuration.

Note: Requires WeChat JS-SDK to be loaded globally first.

interface InitConfig {
  /** Public account appId */
  appId: string
  /** Signature timestamp */
  timestamp: number | string
  /** Signature nonce string */
  nonceStr: string
  /** Signature */
  signature: string
  /** JS API list to use */
  jsApiList: string[]
  /** Enable debug mode */
  debug?: boolean
}

function init(config: InitConfig): Promise<void>

SPA Mode

By default, spa: true is enabled, which means:

• On the first API call (e.g., share()), the SDK is initialized with the current URL
• On subsequent API calls, if the URL has changed, the SDK is automatically re-initialized
• This is essential for single-page applications where the URL changes without page reloads

To disable SPA mode:

config({
  // ...
  spa: false, // Only initialize once
})

iOS WeChat Quirk

On iOS WeChat, the signature URL should be the first entry URL of the app, not the current URL. This library handles this automatically:

• On iOS, it remembers the first URL and always uses it for signatures
• On Android, it uses the current URL for each signature request

You don't need to do anything special - it just works.

Backend Signature Endpoint

Your backend should provide an endpoint that generates WeChat JS-SDK signatures. Here's an example implementation:

// Node.js + Express example
app.get('/api/wechat/signature', async (req, res) => {
  const url = req.query.url as string

  // Generate signature using WeChat's algorithm
  const signature = await generateWeChatSignature(url)

  res.json({
    appId: 'your-app-id',
    timestamp: signature.timestamp,
    nonceStr: signature.nonceStr,
    signature: signature.signature,
  })
})

Refer to WeChat JS-SDK Documentation for signature generation details.

TypeScript Support

Full TypeScript definitions are included:

import type {
  GlobalConfig,
  SignatureResult,
  ShareOptions
} from '@sohu-bpd/wechat'

const config: GlobalConfig = {
  sdkUrl: '...',
  getSignature: async (url: string): Promise<SignatureResult> => {
    // ...
  }
}

Bundle Formats

• ESM (.mjs) - Modern JavaScript modules
• CommonJS (.js) - Node.js and bundlers
• IIFE (.global.js) - Browser <script> tag with global SohuWechat

Changelog

0.0.3 (2026-01-29)

• Breaking Change: Removed automatic SDK loading functionality
• Users must now manually include the WeChat JS-SDK script in their HTML
• Removed sdkUrl configuration option from GlobalConfig
• Removed loadSDK() export from public API
• Updated documentation with instructions for manual SDK inclusion

0.0.2 (2026-01-29)

• Extract WeChat JS-SDK module as standalone package
• High-level config() and share() APIs
• Automatic SDK loading and initialization
• SPA mode with auto re-initialization on URL changes
• iOS WeChat signature URL handling
• Full TypeScript support
• Comprehensive unit tests
• Multiple bundle formats (ESM, CJS, IIFE)

License

MIT