Programming | Attack on Life

Why img onerror Doesn't Trigger on HTTP 404: A Common Pitfall

Sat, 16 May 2026 19:34:00 +0800

The img element has an onerror event, which in theory fires when an image fails to load. Recently, however, I ran into a case where it didn’t fire. After digging in, I found a subtle detail worth knowing.

Example

# Does NOT trigger onerror
<img src="https://i.postimg.cc/76vzQ3fQ/C01.jpg" onerror="alert(111)" />


# DOES trigger onerror
<img src="C01.jpg" onerror="alert(111)" />

In the example above, the image request returns a 404 status code, but the response body is still valid image content, so onerror does not fire. The conclusion: onerror doesn’t care about the HTTP status code — it only cares whether the response is a properly-formed image.

What MDN Says About onerror

If an error occurs while loading or rendering an image, and an onerror event handler has been set for the error event, that event handler will get called. This can happen in several situations, including:

The src or srcset attributes are empty ("") or null.
The src URL is the same as the URL of the page the user is currently on.
The image is corrupted in some way that prevents it from being loaded.
The image’s metadata is corrupted in such a way that it’s impossible to retrieve its dimensions, and no dimensions were specified in the element’s attributes.
The image is in a format not supported by the user agent.

So MDN confirms that onerror is triggered based on whether the image can be properly loaded — not based on the HTTP status code.

Conclusion

onerror only works as a fallback when the image itself cannot be loaded. If the server returns a 404 status code but the response body is still a valid image, onerror won’t fire. Keep this in mind when relying on onerror. If you really need to make decisions based on the HTTP status code, consider an alternative approach — for example, using fetch to request the image first, checking the status code, and only then setting the src attribute on the img element.

References

https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img

Trezor Hardware Wallet: Firmware, Emulator, and Custom Firmware Notes

Tue, 28 Apr 2026 16:49:49 +0800

imKey does not support flashing custom firmware, so our team looked into another hardware wallet brand: Trezor. I am noting down some resources here for future reference.

Firmware

https://github.com/trezor/trezor-firmware

It looks like all models share one unified firmware repository.

App Support

https://github.com/trezor/trezor-firmware/tree/main/core/src/apps

Emulator

https://docs.trezor.io/trezor-firmware/core/build/emulator.html

Custom Firmware

https://trezor.io/trezor-suite?srsltid=AfmBOortBR02GKnAknyFOeS8YWKwWmQuYZeSHtu-ix4v0_7UJaBYd-5w

Twitter Follower Count

Trezor has about 230k followers.
Ledger has about 670k followers. Based on the numbers, Trezor has roughly one third of Ledger’s follower count, which may suggest its community influence is lower than Ledger’s.

Web-to-Wallet Communication

@trezor/connect-web

Firmware Development / Build

$ git clone git@github.com:trezor/trezor-firmware.git

# Fetch all submodule resources.
$ git submodule update --init --recursive --force --progress

# Install nix. It supports Linux/macOS, and you need to restart the shell after installation.
$ curl -L https://nixos.org/nix/install | sh

$ nix-shell --arg devTools true

# Environment.
$ uv sync

$ source .venv/bin/activate

# Test whether the environment is set up correctly.
$ python -c "import click; print('click ok')"

# Enter the core directory and install dependencies.
$ cd core

# Fetch third-party dependencies.
$ make vendor


# Note: if the code has not changed but you build the firmware repeatedly, it will error because the file already exists.
# A normal build will print something like: cp build/firmware/firmware.bin build/firmware/firmware-T3T1-2.11.2-6daa3bd.bin (trezor-firmware)
$ make build_firmware
# For example, if the device model is T3B1, specify the environment variable.
$ TREZOR_MODEL=T3B1 make build_firmware

# TREZOR_MODEL=T3B1 make upload

# Device list, used to confirm the device is connected and recognized correctly.
$ trezorctl list

Firmware File

After building, the file is at core/build/firmware/firmware-T3B1-2.11.3-3a8d901.bin.

Note: if your local git tree has uncommitted changes, the built firmware will include a dirty marker.

Check the Device’s Real Model

trezorctl get-features | grep -E "model|internal_model|vendor|major_version"

Flashing Firmware

Unlocking `add this if the prompt does not pass`

$ trezorctl device unlock-bootloader

Unlock it according to the on-device prompts.

Note: trezorctl is the official CLI tool written in Python. I recommend following the firmware development flow to install the environment.

$ git clone git@github.com:trezor/trezor-firmware.git

# Fetch all submodule resources.
$ git submodule update --init --recursive --force --progress

# Install nix. It supports Linux/macOS, and you need to restart the shell after installation.
$ curl -L https://nixos.org/nix/install | sh

$ nix-shell --arg devTools true

# Environment.
$ uv sync

$ source .venv/bin/activate

# At this point, trezorctl commands should work. For example, trezorctl list can show the device list.

Enter Bootloader Mode

Hold down both hardware wallet buttons and connect it to the computer to enter bootloader mode.
Tap Install FW on the hardware wallet. It will show waiting for host.

Install Firmware from the Command Line `method 1`

# This will trigger firmware flashing on the physical device. You can also use Trezor Suite to flash firmware.
$ make upload

Install Firmware with Trezor Suite `method 2`

The prerequisite is entering bootloader mode. After entering it, the hardware wallet will prompt for installation; tap install, then choose the connected device from the top-left corner on the PC side.

Download Trezor Suite from the official site.

Note: firmware size is only about 1-2MB in my test, so installation is fast. It needs confirmation on the hardware wallet side.

Note: after flashing locally custom-signed firmware, the wallet will show a warning on startup. The warning disappears only after flashing official signed firmware again.

web3.js and Trezor Interaction

It uses the PB message protocol.
Communication goes through WebUSB or the bridge protocol.

https://docs.trezor.io/trezor-firmware/core/build/embedded.html

China Website ICP Filing: Domain, Server, and Practical Notes

Tue, 14 Apr 2026 12:16:31 +0800

Does ICP Filing Follow the Domain or the Server?

For example: after a domain is filed through Alibaba Cloud, it can point to a Tencent Cloud server, but you need to complete an access filing first. According to the relevant rules, ICP filing follows the cloud server, not the domain. If your domain was filed with Alibaba Cloud but you want to point it to a Tencent Cloud server, you need to go through the access filing process.

So the conclusion is: ICP filing follows the server, not the domain. No matter where your domain was originally filed, as long as the server is in mainland China, filing is required. Of course, if you move from one Alibaba Cloud server to another Alibaba Cloud server, you generally do not need to file again.

How Long Does Filing Take?

Domestic cloud provider pages usually show an estimated time. In short, it is not very efficient. Just assume the timeline will not be optimistic and evaluate based on the longest expected duration.

Filing Entity

Sometimes one company has multiple legal entities, so pay attention to the filing entity. I recently ran into an issue where the WeChat developer account entity did not match the filing entity of the domain I wanted to bind, which caused problems.

Does Hosting in Hong Kong or Overseas Avoid Filing?

Yes, but there are tradeoffs. For example, if you want to use Baidu Webmaster tools or earn ad revenue in China, it may not work, because domestic sites must have ICP filing.

Yes. According to the relevant rules, websites operated in mainland China must display the ICP filing number in the page footer. The filing number indicates that the website has completed the required filing process and meets the relevant requirements.
For the homepage, or for a closed system, the login page must show the filing number. Other pages may not need it, but for an open system, I recommend placing it on every page because users may directly access pages other than the homepage.

Final Thoughts

If your business targets mainland China, you cannot move forward without ICP filing. The process is unpleasant, but there is no real workaround.
If you do not care about mainland China business, then you have much more freedom.

How to Use Exa AI Search with Claude MCP

Sun, 05 Apr 2026 20:57:48 +0800

Most AI tools now have web search capabilities. For example, Claude Code can use online search, and when the AI performs a web lookup, you can clearly see it calling WebFetch. I heard that Exa is a good AI search engine, so I used it for a while and found it genuinely strong. Here is my experience.

Advantages of Exa Search

My understanding is: 1. quality, 2. speed. AI web search is essentially direct search, but Exa appears to have its own index, so the quality is much better and the response is also much faster.

Free/Paid

Exa currently has a free credit allowance, but it is still a paid product. Registration gives you 10 USD in credits, though this amount often changes, so use the official information as the source of truth. The free credits can last for a while, and after that you need to pay. Fortunately, it supports domestic Visa cards.

I am still using free credits at the moment, since I have more than 60 dollars available. After I use them up, I may consider paying.

Exa occasionally runs campaigns that provide credit promo codes. If you have one, you can redeem it on this page.

If you cannot find a promo code, try looking on social media or Xianyu.

Install

Exa provides MCP, SDKs, and APIs directly, so choose whichever fits your use case.

Here I use Claude MCP as an example.

claude mcp add exa -e EXA_API_KEY=YOUR_API_KEY -- npx -y exa-mcp-server

For the specific MCP server configuration, refer to the example below.

 "exa": {
 "command": "npx",
 "args": ["-y", "exa-mcp-server"],
 "env": {
 "EXA_API_KEY": "xxxxxx"
 }
 }

Usage

Here is how to let the AI call MCP. The method is basically the same as other MCP servers.

The simplest way is to tell Claude directly, for example: Use Exa to search how to preview images in a WeChat Mini Program. Then you can see a relatively high-quality response, and the response speed is indeed fast.
You can also define in the project prompt that online search should use Exa MCP. Then when the AI decides which tool to call, it will use Exa MCP instead of the built-in web search.

Which one to choose depends on your workflow.

Aside from MCP, the SDK or API usage is straightforward. Just follow the documentation.

https://exa.ai/docs/reference/search-api-guide

Final Thoughts

If you have not tried Exa before, I recommend giving it a shot. Personally, I think it is very good.

Understanding OneKey Hardware Wallets

Wed, 25 Mar 2026 00:00:00 +0800

I recently needed to research hardware wallets for work. After looking at Ledger, I also wanted to understand OneKey, since it is another mainstream option and worth considering in a technical evaluation.

Supporting a Custom Blockchain

If you want a custom blockchain to use OneKey for secure storage and signing, there are two paths:

Develop an app under the firmware repository, submit a PR, and once merged, the new chain is supported after users upgrade their firmware.
Use an official SDK such as the Web SDK to connect the wallet in the appropriate context.

How End Users Use It

There is no concept of “installing an app” on OneKey. All the user can do is upgrade the firmware.

Ledger vs OneKey Comparison

Ledger requires installing an app on the device; OneKey does not, but it requires a firmware upgrade. You can think of Ledger as an app store model and OneKey as an OS model.
Ledger app submission goes through a store listing request. OneKey support is added via a GitHub PR on the open-source firmware repo — once the PR is merged, it is done.
In development, both use a simulator for non-device testing. For real hardware, Ledger has restrictions and requires a model that supports sideloading, while OneKey has no such restriction, though it still requires a firmware upgrade.

References

https://developer.onekey.so/zh/

Understanding Ledger Hardware Wallets

Fri, 20 Mar 2026 09:42:15 +0800

Ledger /'ledʒər/ is a hardware wallet brand. I recently needed to verify the signing flow for a new blockchain, so I tested it with a Ledger Nano X device.

This post records the process and the main technical points.

Buying a Ledger

The one I have was purchased by my company. If you want to get your own, the official store is the simplest option: Ledger Shop

What It Is

A Ledger device stores private keys securely through physical isolation and a secure element chip.

What It Does

Private key storage without exposing the key to the computer or phone
Transaction signing with the signing action completed on the device itself

Example: Ethereum Signing Flow

sequenceDiagram box Client participant U as User participant D as dApp participant M as MetaMask end box External Signing Device participant L as Ledger Device (Ethereum App) end box Blockchain Infrastructure participant R as RPC / Ethereum Network end U->>D: Start transfer / approve / swap D->>M: Ask wallet to create a transaction M->>R: Fetch nonce / gas / fee / chainId R-->>M: Return on-chain parameters M->>U: Show transaction details U->>M: Confirm in MetaMask M->>L: Send unsigned transaction data L->>U: Show key details on the device screen U->>L: Confirm or reject with hardware buttons alt User confirms L-->>M: Return signature M->>R: Broadcast signed transaction R-->>M: Return tx hash / pending / confirmed M-->>U: Show transaction status else User rejects L-->>M: Reject signing M-->>U: Transaction canceled / failed end

Supporting a Custom Blockchain

If you want a custom chain to use Ledger for secure key storage and signing, there are two main parts:

Build a Ledger Device App that runs on the hardware device and knows how to sign transactions for your chain.
Build a plugin or integration layer that connects MetaMask or another wallet to that device app. If your stack uses libraries such as web3.js, you may also need to extend those libraries to support signing through the Ledger device app.

Call Chain / Data Flow

Your code
 ↓
Ledger SDK (wraps APDU)
 ↓
WebHID (transport)
 ↓
Ledger device
 ↓
Your ChainMaker App (parses APDU)

HID means human interface device, and APDU means application protocol data unit.

Ledger Device App Requirements

The device app is typically written in C or Rust because device resources are limited.
- Rust template: https://github.com/LedgerHQ/app-boilerplate-rust
- C template: https://github.com/LedgerHQ/app-boilerplate
Install the official VS Code extension for development and debugging.
Building the device app requires Docker because Ledger provides a containerized toolchain.
For simulator-based testing, install Speculos.

VS Code Extension

The extension provides a solid development, build, and debug workflow, which helps a lot when iterating on a device app.

Real Device vs Simulator

Item	Real Device (WebHID)	Simulator (Speculos)
Connection	`TransportWebHID.create()` with browser HID picker	`SpeculosHttpTransport.open(url)` over local HTTP
Protocol	USB HID frames via the browser WebHID API	HTTP JSON such as `{ data: "hex..." }`
User confirmation	Physical button confirmation is required	Manual confirmation in Speculos
Signer setup	Usually pass `signDigest` and `fetchPublicKey` explicitly	Defaults are often enough
Later flow	`isReady()` -> `fetchPublicKey()` -> `signMessage()` -> submit on-chain	Same overall flow

Submission and Release

What you submit is not a binary package. You submit the app source repository plus the required deliverables. Ledger then forks your app repository and manages deployment in their own release flow.

Typical process:

Contact the Ledger team and submit the project form: https://developers.ledger.com/docs/device-app/submission-process/submission-form
Make sure the code meets Ledger’s security and cryptography requirements.
Prepare deliverables:
- The app source repository
- docs/apdu.md describing APDU commands and status words
- User documentation
- Device compatibility information for Nano S Plus, Nano X, Stax, and Flex
- Legal entity information and contact details
Submit the official device app or plugin form.
Pass the security audit before Ledger publishes the app.

This review process is heavy and can take weeks or even months.

How End Users Use It

The user installs Ledger software and sets up the device.
The user installs the target app onto the Ledger device.
- If the app has not been officially published yet, you usually sideload it through the official VS Code tools.

Other Notes

Why are there so many models, and why are they expensive?

A hardware wallet is more than just a security chip.
Different models trade off security level, user experience, storage capacity, and use case, so the pricing differs naturally.

About `navigator.hid`

navigator.hid (WebHID) connects to physical USB HID devices. Speculos is only a simulator that exposes TCP sockets and an HTTP API. It is not a real HID device, so the browser cannot discover it through WebHID scanning.

Contact Ledger

Discord
Email: hello@ledger.fr

References

Hardware Requirements for Deploying Openclaw

Fri, 06 Mar 2026 17:48:36 +0800

A friend recently asked me: what kind of machine do you actually need to deploy OpenClaw (formerly ClawdBot)? Bottom line up front: it’s very lightweight, and hardware isn’t the bottleneck. A low-spec machine can run it, but whether you run it stably and fast depends on your specific use case.

OpenClaw Minimum Requirements

OpenClaw is officially positioned as “low barrier to deploy.” The following specs serve as a baseline:

CPU: 2+ cores (Intel N-series, entry-level AMD Ryzen, or ARM all work)
RAM: 4GB (basic chat functionality can go as low as 2GB)
Storage: At least 2GB free disk space
Runtime: Node.js v22+
OS: Linux, Windows (via WSL2), or macOS 13+
Network: Stable internet connection; if using overseas models, make sure your network can reach them

Recommended Specs

For more stable long-term operation:

RAM: 16GB or more
Storage: 256GB SSD (improves system responsiveness and I/O)
CPU: 4+ cores (better experience for concurrent tasks and browser automation)

The baseline gets you “can it run,” while the recommended specs determine “will it run without frequent freezes or disconnects.”

Deployment Options

1) Cloud

Budget VPS: Starting around $5/month; domestic cloud providers work too.
Free option: Oracle Cloud free tier (4 ARM cores + 24GB RAM available).

Best for:

24/7 availability
Not tying up your local machine

2) Local Deployment

Can use Docker
Or install Node.js directly on the host and run it; personally, I deploy on a Mac mini at home.

Best for:

Frequent debugging and development
Data locality requirements

When You Need More Power

OpenClaw itself is lightweight, but these scenarios significantly raise hardware demands:

Running local LLMs: At least 8GB–16GB RAM recommended
Browser automation enabled: 16GB RAM recommended for a stable experience
High concurrency (scraping + automation + chat simultaneously): Leave headroom in both CPU and RAM

Practical Advice

If you’re just trying it out, 2 cores + 4GB RAM + Node.js 22+ is enough to get started.

If you plan to run automation tasks long-term, go straight for 4 cores + 16GB + SSD — you’ll save a lot of troubleshooting and restart time down the road.

Also, the installation process typically supports a one-liner CLI command. Get it running first, then scale up based on actual load — that’s the most efficient approach.

OpenClaw MCP Setup Guide: How to Connect Third-Party Tools to Your AI Assistant

Wed, 04 Mar 2026 17:35:58 +0800

I needed to call TAPD MCP in OpenClaw, but found that it doesn’t natively support MCP. A third-party solution is required. The official recommendation is to use MCPorter as a middleware layer.

Install MCPorter

npm i mcporter


which uvx

curl -LsSf https://astral.sh/uv/install.sh | sh

source ~/.bashrc # or source ~/.profile

Add MCP

npx mcporter config add mcp-server-tapd
–stdio “uvx mcp-server-tapd”
–env TAPD_ACCESS_TOKEN=xxxx
–env TAPD_API_BASE_URL=https://api.tapd.cn
–env TAPD_BASE_URL=https://www.tapd.cn

The config file is located at /root/config/mcporter.json.

View

Run this command to check the MCP status:

mcporter list

OpenClaw Getting Started - installation, configuration, Telegram Bot integration, and MCP basics
OpenClaw Memory Management and Invocation - global memory via SOUL.md and AGENTS.md
OpenClaw for Social Media Publishing - using MCP to publish to WeChat, Xiaohongshu, and Toutiao

Usage

When using it, you can explicitly tell OpenClaw to use the mcp-server-tapd under MCPorter at the beginning. Once it’s saved to memory, you can simplify it afterward by just sending the ticket link directly.

Using Tapd MCP

Tue, 03 Mar 2026 17:08:22 +0800

TAPD is used quite frequently at work, and I’ve recently been integrating MCP. Here, using Claude Code as an example, I’ll list how to set it up. Other AI tools work similarly.

Configuration

Note: You can use either a token or username/password, whichever you prefer. The token can be added at this location

"mcpServers": {
 "mcp-server-tapd": {
 "type": "stdio",
 "command": "uvx",
 "args": [
 "mcp-server-tapd"
 ],
 "env": {
 "TAPD_ACCESS_TOKEN": "xxxx",
 "TAPD_API_USER": "",
 "TAPD_API_PASSWORD": "",
 "TAPD_API_BASE_URL": "https://api.tapd.cn",
 "TAPD_BASE_URL": "https://www.tapd.cn",
 "BOT_URL": ""
 }
 }
 }

Testing

After setup, enter a conversation in Claude and use /mcp to check the connection status of the Tapd MCP.

https://cloud.tencent.com/developer/mcp/server/11474

Complete Guide to Migrating Tencent Cloud Static Resources to Cloudflare R2

Sun, 01 Feb 2026 17:41:35 +0800

Due to increasing dissatisfaction with domestic cloud vendors and to improve blog service performance, I’m migrating the blog’s static resources from Tencent Cloud to Cloudflare R2. The steps are quite tedious, including rclone configuration, Worker deployment, and custom domain binding. However, with AI assistance, the entire migration process took about 1 hour, and 0.5GB of static resources were switched over with zero downtime. Here’s a complete record of the steps for everyone’s reference.

Background and Goals

The main purposes of migrating static resources from Tencent Cloud to Cloudflare R2 are:

Cost Reduction: Cloudflare R2 has completely free egress traffic. In the future, I plan to abandon services that rely on domestic clouds, as they are full of rogue practices from login to use.
Performance Improvement: Utilize Cloudflare’s global CDN acceleration to optimize blog access speed and SEO.

Final Architecture

Server local directory
/var/www/blog/static-assets
 ↓ (rclone sync)
Cloudflare R2 (private bucket)
 ↓ (Worker)
static.1991421.cn (custom domain)

Architecture Features:

Blog URLs remain unchanged
R2 Bucket remains private
Access controlled via Worker
Zero egress traffic costs

1. Install rclone

Install rclone on the server:

curl https://rclone.org/install.sh | sudo bash

2. Configure rclone to Connect to R2

1. Start Configuration Wizard

rclone config

2. Create a New Remote

Configure according to the following steps:

Select n to create a new remote
Name: cf-r2
Storage type: s3 (S3 compatible object storage)
Provider: 47 (Any other S3 compatible provider)

Why not select Cloudflare R2 option? R2 is not in the built-in vendor list, so we must use the generic S3 compatible configuration.

3. Fill in Authentication Information

After creating an API token in the Cloudflare R2 console, you will see three fields. Here’s the corresponding relationship:

Cloudflare Console Field	rclone Config Item	Required?
Access Key ID	`access_key_id`	✅ Required
Secret Access Key	`secret_access_key`	✅ Required
Token Value	-	❌ Ignore

Enter in rclone:

access_key_id> [Your Access Key ID]
secret_access_key> [Your Secret Access Key]

4. Configure Connection Parameters

Region (leave empty):

region> [Press Enter directly]

R2 doesn’t have a region concept, leaving it empty is the official recommended approach.

Endpoint (required):

endpoint> https://<AccountID>.r2.cloudflarestorage.com

Example: https://xxxxx.r2.cloudflarestorage.com

You can find this address on the Bucket details page in the R2 console.

Location Constraint (leave empty):

location_constraint> [Press Enter directly]

ACL (empty = private):

acl> [Press Enter directly]

R2 doesn’t use S3 ACLs; permissions are managed by Workers.

Advanced config (not needed):

Edit advanced config? n

5. Confirm Configuration

y) Yes this is OK

Configuration complete!

3. Perform Data Migration

Initial Migration (Recommended: copy)

rclone copy /var/www/blog/static-assets cf-r2:static-assets \
 --progress \
 --transfers=16 \
 --checkers=16

The copy command only copies files and doesn’t delete files on the destination, making it safer.

Daily Synchronization (Use sync)

rclone sync /var/www/blog/static-assets cf-r2:static-assets \
 --progress \
 --transfers=16 \
 --checkers=16

sync makes the destination exactly match the source and will delete excess files on the destination.

Parameter Explanations:

--progress: Show transfer progress
--transfers=16: Transfer 16 files concurrently
--checkers=16: Check 16 files concurrently

4. Configure Cloudflare R2 Bucket

Create an R2 Bucket in the Cloudflare console:

Bucket Name: static-assets
Storage Type: Standard
Region: Auto
Public Access: ❌ Disabled (keep private)

Important: Do not enable public access; we will control access through Workers.

5. Deploy Cloudflare Worker

1. Create a Worker

In the Cloudflare console:

Go to Workers & Pages
Click Create Application
Select Create Worker
Select Start from Hello World

2. Write Worker Code

Paste the following code into the Worker editor:

export default {
 async fetch(request, env) {
 const url = new URL(request.url);
 const key = url.pathname.slice(1);

 if (!key) {
 return new Response('Not Found', { status: 404 });
 }

 const object = await env.STATIC_ASSETS.get(key);
 if (!object) {
 return new Response('Not Found', { status: 404 });
 }

 return new Response(object.body, {
 headers: {
 'Content-Type':
 object.httpMetadata?.contentType || 'application/octet-stream',
 'Cache-Control': 'public, max-age=31536000, immutable'
 }
 });
 }
};

Code Explanation:

Extract file key from URL path
Get object from R2
Set correct Content-Type
Add long-term cache headers (1 year)

3. Bind R2 Bucket

This is the most critical step and is easily overlooked!

In Worker settings:

Go to Settings > Variables and Secrets
Select R2 Bucket Bindings (not environment variables!)
Add binding:
- Variable Name: STATIC_ASSETS
- R2 Bucket: Select static-assets

Note: Must use R2 Bucket binding; do not use environment variables or plain text.

4. Test Worker

After deployment, test using the workers.dev domain:

curl -I https://static-assets.your-account.workers.dev/2018-06-06-Validate.jpg

If it returns the image correctly, the Worker to R2 connection is established.

6. Bind Custom Domain

1. Add Custom Domain

In Worker settings:

Go to Triggers
Click Add Custom Domain
Enter domain: static.1991421.cn

If the domain is already managed by Cloudflare:

DNS records will be created automatically
HTTPS will be enabled automatically
Usually takes effect within 1 minute

2. Verify Domain

curl -I https://static.1991421.cn/2018-06-06-Validate.jpg

Check response headers:

server: cloudflare
cache-control: public, max-age=31536000, immutable

These indicate that it’s officially online!

7. Update Blog References

If you used a new domain, you need to update the static resource URLs in your blog. In my case, they remain unchanged, so this step isn’t necessary. If you need to update, you can use batch replacement:

Old: https://old-domain.com/image.jpg
New: https://static.1991421.cn/image.jpg

You can use a batch replacement tool to complete this.

Summary

This migration achieved:

✅ Cost Optimization: R2 egress traffic is $0 ✅ Performance Improvement: Cloudflare global CDN acceleration ✅ Architecture Optimization: Standard practice of Private Bucket + Worker ✅ Zero Downtime Migration: URLs remain unchanged, users are unaware

The entire migration process took only 1 hour, and all 0.5GB of static resources were migrated. This is the Cloudflare R2 + Worker approach.

How to Use AI to Build a Full-Stack Project (Step-by-Step Guide)

Thu, 22 Jan 2026 21:59:44 +0800

You can spin up a solid full-stack project quickly with AI. To avoid back-and-forth, here’s the tech stack I rely on in real projects. Feed it to your AI or drop it in project docs—just hand it to the model.

Frontend stack

Package manager: npm
React
TypeScript
Vite
dayjs
Tailwind CSS + ShaCDN Components
Need charts? Use ECharts

Backend stack

Package manager: npm
NestJS
TypeScript
Database: MySQL
ORM: TypeORM
JWT for auth
Swagger for API docs

Mini‑program stack

Package manager: npm
Taro framework
TypeScript
Build with Vite
dayjs for dates/times
Component library: TDesign Mini

Automating WeChat Mini Program Deployment with miniprogram-ci

Thu, 15 Jan 2026 17:52:17 +0800

Every time I release a new version of my mini program to the preview environment, I need to: build the package => open WeChat Developer Tools => click upload => click submit. The whole process is tedious. This manual publishing workflow is extremely inefficient, so I wanted to automate it with a script. I discovered the official miniprogram-ci npm package, and after some exploration, I finally solved this pain point. However, the official documentation is quite sparse, so I’m documenting my solution here.

My Original Project Setup

I’m using Taro, so before each release I need to run npm run build:weapp to compile and build the project. The built files are located in /dist/weapp, and this is the folder I need to upload and publish.

Implementing Automated Publishing with miniprogram-ci

Here’s the script code for publishing to the development version. Based on this code block, create a publish.js script. Integrating it with the build process is also straightforward.

(async () => {
 const project = new ci.Project({
 appid: "",
 type: "miniProgram",
 projectPath: path.resolve(__dirname, "../", "dist"),
 privateKeyPath: path.resolve(__dirname, "private.key"),
 ignores: ["node_modules/**/*"],
 });

 // Common compilation settings
 const setting = {
 // Key: Disable ES6 to ES5 conversion, as Taro already handles this
 es6: false,
 // Disable enhanced compilation
 enhance: false,
 // Disable ES7 to ES5 conversion
 es7: false,
 // Code protection (obfuscation)
 minified: true,
 // Auto-prefix styles
 autoPrefixWXSS: true,
 // Compress WXML
 minifyWXML: true,
 // Compress WXSS
 minifyWXSS: true,
 // Compile JS to ES5
 codeProtect: false,
 };

Important Notes

The official documentation lacks many details, so here are some clarifications:

Note that if the version is already set as the preview version on the WeChat Official Accounts Platform, it will be published as the preview version; otherwise, it will be the development version.
The private.key file needs to be downloaded from the WeChat Official Accounts Platform. Path: Development -> Development Settings -> Download Developer Tools Configuration File. After extracting, you can find the private.key file.
The projectPath here is the directory where project.config exists. Since I’m using Taro, which handles compilation to WeChat Mini Program language, I need to disable those compilation switches in the configuration above. If you’re developing natively, I believe you can simply use the project configuration directly.
The ci tool’s upload function only performs size checks and doesn’t validate syntax. So if you select the wrong directory or enable extra compilation options, the result is that the upload succeeds but the preview fails with errors like Component is not found in path "wx://not-found"

Final Thoughts

miniprogram-ci isn’t about whether it’s good or not - it’s just barely usable.
WeChat Mini Program documentation is truly terrible, and the community is mediocre at best. Just browse through and you’ll see complaints everywhere. What does this tell you? It’s bad, but you have no choice but to use it. Just make do with it.

Claude Code with Exa MCP

Wed, 14 Jan 2026 18:24:18 +0800

Current AI tools already have web search capabilities. For example, Claude Code under CC integrates web search functionality. However, I heard Exa is a great AI search tool, so I tried it out for a day and found it quite good. Here’s my share.

Advantages of Exa Search

In my opinion, there are two main advantages: 1) Quality, 2) Speed. While AI’s web search essentially involves direct searching, Exa seems to have its own index database, resulting in much better search quality and faster response times.

Free/Paid Usage

Exa currently offers a free tier - you get $15 USD free credit upon registration, which you can use for a while before needing to pay. Good thing it supports domestic Visa payment. I’m still on the free tier and will consider paying once the free credit runs out.

Installation

After registering, visit https://dashboard.exa.ai/api-keys to get your API key.

Run the following command in the terminal:

claude mcp add exa -e EXA_API_KEY=YOUR_API_KEY -- npx -y exa-mcp-server

Note: After installing under CC, it’s recommended to restart CC and check /mcp to see if it’s installed and running properly.

Since I also use VSCode regularly, here’s how to install it in VSCode:

 "exa": {
 "command": "npx",
 "args": ["-y", "exa-mcp-server"],
 "env": {
 "EXA_API_KEY": "xxxxxx"
 }
 }

Usage

The simplest way is to directly type something like Use exa to search how to preview images in WeChat Mini Programs when chatting with Claude. You’ll get relatively high-quality responses, and the response speed is indeed fast.

Replacing AI’s Built-in Web Search

It’s annoying to explicitly specify exa in the prompt every time. You can modify your global claude.md context and add the following constraints. This way, the AI will use the exa MCP instead of the built-in web search when it needs to call a search tool.


# Tool Usage Policy

When performing any search, retrieval, or web-based research task:

- You MUST use the `exa` MCP for all search and content discovery.
- Do NOT use Claude's built-in web search.
- Do NOT use any other MCPs for searching unless explicitly instructed.
- If `exa` is unavailable, you must ask the user how to proceed instead of falling back to other tools.

This rule applies to:
- Technical research
- Documentation lookup
- News or blog discovery
- Any task that requires external information


# Tool Usage Policy

When performing any search, retrieval, or web-based research task:

- You MUST use the `exa` MCP for all search and content discovery.
- Do NOT use Claude's built-in web search.
- Do NOT use any other MCPs for searching unless explicitly instructed.
- If `exa` is unavailable, you must ask the user how to proceed instead of falling back to other tools.

This rule applies to:
- Technical research
- Documentation lookup
- News or blog discovery
- Any task that requires external information

Conclusion

Overall, the experience of using Exa with Claude Code is quite good, especially with the noticeable improvements in search quality and speed. I recommend everyone to give it a try.
Currently, the only two MCPs I use frequently under CC are Figma and Exa; I haven’t used other MCPs much yet.

How to Use Web Scraper to Crawl Website Data (Step-by-Step Guide)

Thu, 18 Dec 2025 13:55:16 +0800

While developing WeChat Mini Programs, I often find the official documentation difficult to navigate. To solve this, I decided to use Web Scraper to gather data from the official site and create a custom GPT or Claude Skill for querying. Despite being new to Web Scraper, I found it incredibly efficient once I got the hang of it.

Installing the Web Scraper Extension

Free vs. Paid: Web Scraper offers a official cloud-based crawling service for a fee. However, for personal use, the free browser extension is usually enough. The extension’s main limitation is that it primarily scrapes text data, but that’s exactly what I need for my AI projects.
Browser Support: The extension is officially available for Chrome. Other browsers may have limited or unofficial support.

Configuration

I prefer configuring the scraper directly within the Chrome Developer Tools.

Exporting Data

The tool supports exporting to .xlsx and .csv. I typically use CSV because it’s a lightweight format that most AI models can easily ingest.

Using the Data with AI

Once you have the data, the possibilities are endless. For example, I created a Custom GPT in ChatGPT and uploaded the scraped documentation. Now, I can query the official documentation through a conversational interface.

I’ve built a WeChat Mini Program Documentation Assistant using this method. You can try it out here: WeChat Mini Program Documentation Assistant GPT

Final Thoughts

While specialized APIs are often used for web scraping, many sites block automated crawlers. A browser-based extension like Web Scraper elegantly bypasses many of these restrictions by mimicking human browsing behavior. It’s a powerful tool for anyone looking to build custom datasets. Highly recommended!

Antigravity with Figma MCP Server

Tue, 16 Dec 2025 15:27:30 +0800

Recently, I tried Google’s Antigravity IDE with the G3 model and Figma MCP Server. The results were quite good, so I’m sharing how to use it here.

Antigravity Installation

No need for lengthy explanations, just download and install from the official site. Google login is required. The free version of Antigravity can use g3. Regarding the quota, actual testing shows I can use it for 2 days. If that’s not enough, consider paying or switching accounts.

Figma MCP Server Installation

Installing MCP in Antigravity is relatively convenient, but also somewhat hidden.

Search for and install the Figma MCP Server, then install it.

Usage

For actual usage, just paste the Figma design layer link in the prompt, and specify that the code should be generated according to the Figma design.

Figma MCP Settings

One small detail is that the Figma side can configure how images and icons are handled. This way, during use, the AI can download Figma resources to the project or directly use web addresses, etc. The official documentation is quite rough, so I’m specifically mentioning this here.

Usage Experience

Currently, compared to Sonnet/GPT, I think this has the highest fidelity. Recommended to try out.

Creating Claude Skills with Claude Code

Sun, 14 Dec 2025 18:13:15 +0800

With the growing adoption of AI “Skills” as a standard for extending AI capabilities, I decided to create a specialized Skill for WeChat Mini Program documentation. This allows Claude to accurately reference official docs while assisting with development.

Scrapping WeChat Mini Program Documentation

I used Web Scraper, a free Chrome extension, to gather the data.

Configure the sitemap to navigate through the official documentation.
Select the specific content elements (API descriptions, components, etc.) to scrape.
Start the scraping process. The extension will open a new window to crawl the site. Due to the large volume of data, this may take some time.
Once completed, export the data as a CSV file.

Creating Skills in Claude Code

Claude Code provides built-in tools for creating Skills. When you create a Skill, it results in a .skill file, which is essentially a ZIP archive. You can find these in the ~/.claude/skills directory.

Adding Official Skills

You can reference and add official skills from the Anthropic repository: https://github.com/anthropics/skills.git

Building the WeChat Mini Program Skill

I used the scraped data to feed into a new Skill definition.

Currently, Claude Code doesn’t have a UI to list installed Skills; you must use the command line to verify them.

Usage

Once installed, you can simply ask questions related to the document in Claude Code:

“How do I get the user’s avatar in a WeChat Mini Program?”

Claude will automatically trigger the WeChat Mini Program documentation Skill, search the indexed content, and return accurate results. You will see a notification in the terminal when a Skill is being invoked.

Final Thoughts

So far, the results are promising. However, I’ll need to monitor token usage over the long term to see how cost-effective this approach is. Done!

Custom Slash Commands in Codex

Sun, 07 Dec 2025 23:02:18 +0800

Custom slash commands in CC are really convenient. For example, I often perform specific operations directly with slash commands, which is efficient. The Codex CLI can achieve similar functionality.

Create prompts file

Create a prompts folder in your user’s home directory, not in the project directory.
```
mkdir -p ~/.codex/prompts
```
Edit the prompt file Create a new text file in the ~/.codex/prompts/ directory, such as deploy.md, and write your desired prompt content.

Restart Codex session

Type /prompts:deploy-dev and press enter to execute the target command.

https://developers.openai.com/codex/guides/slash-commands/#create-your-own-slash-commands-with-custom-prompts

Claude Pro Nigeria Low-Price Region Subscription Guide: Cheapest Way to Subscribe & Payment Tips

Sat, 29 Nov 2025 16:09:50 +0800

While reviewing my annual app subscription costs recently, I found they had gotten way too high. One of the biggest expenses was Claude Pro at $20/month (~¥140 CNY), roughly ¥1,800/year. To cut costs, I switched to the Nigeria region subscription — now about ¥88 CNY/month, saving nearly half. Here’s how I did it.

Why Choose the Nigeria Region

I already use Turkey region for some services like YouTube Premium and GPT Plus. However, Claude’s Turkey pricing is barely cheaper than the US price, so there’s no real advantage. That’s why I went with Nigeria instead.
If money isn’t a concern or your company covers it, there’s no need to bother — just go with the US region.
As shown in the screenshot below, Nigeria is significantly cheaper than the US. For Max, the US price is $200 while Nigeria is $144.6 — a big difference. The gap is even more pronounced for the Pro tier.

Prerequisites

A Nigerian Apple ID account. I registered a new one. If creating a Nigerian account directly keeps failing, you can start with another region (e.g., China or the US) and switch the account country later in settings.
- If you need help registering a Nigerian Apple ID or run into issues, check out this tutorial.
A Nigerian payment method is ideal but not required. If you don’t have one, you can buy Nigerian iTunes gift cards instead. Chinese users can usually use Xianyu (Idle Fish); if you do not have access to a Chinese Xianyu account, use another gift-card channel.

🎁

Nigerian iTunes Gift Card

~14,900–15,000 NGN · Delivered within 24 hrs · Slightly above market price to cover service & transaction fees

USD $--/card

⚠️ Loading...

Quantity

Total: USD $--

After payment, the gift card code will be sent to your email within 24 hours.

Payment issues?

If you see 'payment blocked' or 'too risky', this is Stripe's automated fraud prevention — not a merchant decision. Common causes and fixes:

1. VPN / Proxy
Turn off your VPN or switch to a node matching your card's issuing country. IP-to-card country mismatch often triggers the block.

2. Card not enabled for international payments
Make sure your credit/debit card has international online transactions enabled — some banks disable this by default.

3. Try a different card
Prefer Visa / Mastercard credit cards. Prepaid or virtual cards are more likely to be blocked.

4. Browser issues
Try incognito/private mode, or a different browser. Some extensions can interfere with the payment flow.

5. Still not working?
Contact the author via Alipay or PayPal to complete the payment.

Subscription Steps

Open the App Store and sign in with your Nigerian Apple ID.
Tap your profile icon in the top right, select Add Funds, then choose Redeem Gift Card or Code and enter the gift card code you purchased.
Open the Claude app, sign in to your account, and go to the subscription page.
Select the monthly plan and complete the payment as prompted.
If you only want one month, remember to cancel the auto-renewal after subscribing.

Note: To subscribe via a different region, you must sign into the Nigerian Apple ID on an iPhone. iPad should theoretically work as well. For Android or other devices, please check on your own.

For a newly registered account or an account that has just switched regions, Apple may apply purchase protection. In the early stage, this can cause paid subscriptions for some apps to fail. This is a normal Apple risk-control mechanism, not a gift card issue. Usually, waiting a few days will resolve it automatically.
I ran into similar issues before when subscribing to services like YouTube Premium. You can try waiting a few days.

Final Notes

Claude Pro subscribed through a low-price region has exactly the same features as the US or any other region — no differences at all.
Having a Nigerian and Turkish Apple ID on hand is always useful. I recommend setting them up in advance.
For a full list of services I’m currently subscribed to, check out My App Subscription List.

How to Use the Gemini CLI (Step-by-Step Guide)

Thu, 27 Nov 2025 22:05:13 +0800

Installation

You can install the Gemini CLI using Homebrew:

brew install gemini-cli

Alternatively, you can use npm:

npm install -g @google/gemini-cli

Upgrading

To update to the latest version via Homebrew:

brew upgrade gemini-cli

Once you enter a Gemini session, use the /login command to authenticate. Since Gemini currently offers a free tier (e.g., G3), you can simply use your Google account to log in.

Installing the Figma MCP Extension

You can extend Gemini’s capabilities by installing the official Figma MCP (Model Context Protocol) server:

gemini extensions install https://github.com/figma/figma-gemini-cli-extension

To uninstall the extension:

gemini extensions uninstall figma

Resources

CodeTracker: A WakaTime Client for WeChat Mini Programs

Sun, 23 Nov 2025 12:03:49 +0800

For those of us who use WakaTime to track our coding hours, checking stats on mobile can be a bit clunky. Years ago, I started building a WeChat Mini Program for this, but I eventually abandoned it because the UI was lackluster—I didn’t even like using it myself. However, with the help of modern AI tools, I decided to reboot the project. After a few hours of AI-assisted coding, version 2.0 is finally out. It looks much better now, and I plan to keep iterating based on real-world needs.

Important Notes

This app acts solely as a client for WakaTime. All data is fetched from the official WakaTime API. To use it, you must already have a WakaTime account and the corresponding plugins installed in your IDE (VS Code, JetBrains, etc.).
To avoid potential trademark issues, I’ve named the app CodeTracker instead of “WakaTime Mini Program.” This also gives me more flexibility to add non-WakaTime features in the future.

The App

If you’re interested in tracking your coding productivity on the go, feel free to give it a try!

Roadmap

Now that I’m using it daily, I’ve already thought of a few new ideas:

Daily Reports: A scheduled push notification (e.g., at 7:00 PM) summarizing today’s coding activity.
Visual Avatars: A virtual character that reflects your coding intensity—for example, a character developing “dark circles” under their eyes if you’ve been coding for too long.
Goal Tracking: Setting weekly coding targets and tracking progress.

For now, I’m focusing on perfecting the core functionality. Stay tuned for more updates!

Implementing Email Notifications for Waline Comments

Sun, 16 Nov 2025 20:15:11 +0800

I integrated the Waline comment system into my blog a while ago. Recently, I noticed that several readers had left questions on my posts, but because I hadn’t set up notifications, I didn’t see them in time to respond. Since Waline supports various notification methods, I decided to configure email alerts. Here is the process for future reference.

Choosing a Notification Method

WeChat was ruled out because it lacks an official bot API (current solutions are often “hacks”). While Telegram is an option, it can get quite noisy. For a blog, email is a professional and non-intrusive way to stay updated.

Selecting an Email Provider

I decided to use my QQ Mail account. Since it’s only acting as the sender, any reliable provider with a low chance of being flagged as spam will work.

For QQ Mail, you need to generate an Authorization Code from the settings to use as the SMTP password. Note: This is different from your regular login password.

Pro-tip: The same authorization code can be used across multiple clients; for example, I use one code for two separate Waline server instances.

Waline Server Configuration

My Waline server is hosted on Vercel, so I simply added the necessary environment variables to the project settings. After saving, restart the service to apply the changes.

Environment Variable	Description
`SMTP_SECURE`	Set to `true`
`SMTP_USER`	Your email address (e.g., `user@qq.com`)
`SMTP_PASS`	Your SMTP Authorization Code
`SMTP_SERVICE`	Your provider (e.g., `QQ`)
`SITE_URL`	The URL of your blog
`SITE_NAME`	The name of your blog

For more advanced options, refer to the official Waline notification guide.

Result

Once configured, you will receive an email like the one below whenever a new comment is posted:

Final Thoughts

The email notification feature in Waline is extremely useful for bloggers who want to stay engaged with their readers. I hope future updates bring even more customization options.
For lightweight blogs, Waline remains an excellent, easy-to-configure choice for a commenting system. Kudos to the open-source contributors!

Resources

Waline Documentation: Comment Notifications

Custom Slash Commands in Claude Code

Tue, 11 Nov 2025 23:01:33 +0800

In my current project, I frequently need to deploy builds to a development server. While CI/CD pipelines are great, they can be slow for quick iterations; sometimes a simple scp command is much faster. Since I spend most of my time in the Claude Code (cc) CLI, I wanted a more integrated way to trigger these scripts without manually typing out bash commands. Here is how I set up custom slash commands in Claude Code.

Configuration

Custom commands are scoped to the project. Create a directory named .claude/commands/ in your project root. For example, to create a development deployment command, create a file named deploy-dev.md.

The content should follow this structure: use Markdown for the description and a code block for the actual script.

# Deploy to Development Server
Run this command to build the project and sync files to the dev environment.

```bash
npm run build
scp -r ./dist user@dev-machine:/path/to/deploy


After saving the file, restart your `claude` session. You can now execute it by typing `/deploy-dev` in the CLI.

## Permissions

Commands like `scp` are considered sensitive. By default, Claude Code will ask for permission before executing shell scripts. You have two options:
1. Start Claude Code with the `--dangerously-skip-permissions` flag (not recommended for general use).
2. Allow the command when prompted and select the "Always allow for this project" option to add it to your project's whitelist.

## Summary

1. This is a basic example, but you can use natural language within the Markdown file to provide more context or complex instructions for the command.
2. The Claude Code CLI is arguably the best AI-driven terminal tool available right now. Mastering its custom commands can significantly boost your development workflow.

Guide to Using Claude Code with Codex

Sun, 09 Nov 2025 22:57:38 +0800

I primarily use Claude Code (cc) for development, but the Pro membership’s quota is surprisingly limited. I frequently hit the ceiling and have to wait for my weekly or hourly reset. To keep my momentum, I needed a reliable backup. While DeepSeek is cheap, it doesn’t quite match the quality I need. I decided to try Codex, and it has exceeded my expectations. Since they are products from different companies, there are some nuances to using them together. Here’s a summary of my experience.

(Note: This post is continuously updated.)

Requirements

Codex: Requires a ChatGPT Plus (or higher) subscription; it is not available for free users.
Claude Code: Requires a Pro or Max membership, or a pay-as-you-go API account.

Project Configuration Files

Codex uses the /init command to generate an AGENTS.md file, while Claude Code uses /init to generate a CLAUDE.md file. Maintaining both manually is tedious.

My solution is to link them: in AGENTS.md, I added the instruction: Read CLAUDE.md for more details on development commands, project architecture, and key directories. My testing shows that Codex will then automatically read the contents of CLAUDE.md. This allows me to maintain only the CLAUDE.md file for project-specific rules. You can also do the reverse if you prefer AGENTS.md.

Custom Commands

Custom slash commands are implemented differently in Claude Code and Codex. Unfortunately, these cannot be shared directly and must be configured separately for each CLI. If you don’t use custom commands, you can ignore this part.

Final Thoughts

CLI Experience: In terms of pure terminal user experience, Claude Code (cc) is the clear winner. For example, cc handles session recovery gracefully across logins. Codex requires you to manually select a session upon startup, and it doesn’t effectively isolate sessions by repository, which can lead to a cluttered session list.
Code Quality: Both have their strengths. Codex noticeably outperforms Claude Code when generating code from Figma via the MCP server. However, for general logic and iterative coding, I still find Claude’s output to be slightly superior.
Cost vs. Quota: Given the quota issues, I’ve opted for a dual-subscription strategy: GPT Plus + Claude Pro. Since both memberships also provide access to their respective web interfaces, I find the value proposition to be solid. If you’re constantly hitting your Claude quota, this hybrid approach is a great way to stay productive.

Integrating Codex with Figma MCP Server

Sun, 09 Nov 2025 22:13:30 +0800

Claude Code (cc) works well with Figma MCP, but the biggest hurdle is the limited weekly quota. Since I also have a ChatGPT Plus subscription, I decided to see if I could bridge Codex with Figma MCP. Although there isn’t much official documentation on this, it is indeed possible and works quite well. Here is the setup guide.

Requirements

Figma Permissions: You need Dev or full Editor permissions.
ChatGPT Plus Membership: Codex is currently not available for free users; I use the GPT Plus tier.

Codex Configuration

Locate your configuration file at ~/.codex/config.toml and add the following:

experimental_use_rmcp_client = true

[mcp_servers.figma_local]
url="http://127.0.0.1:3845/mcp"

In this setup, I am using a locally hosted MCP server, so make sure you have the Figma MCP server running locally.

Once configured, start Codex. If there’s a connection issue with the MCP server, you’ll see an error; otherwise, you’re good to go.

Note: experimental_use_rmcp_client = true is essential for enabling HTTP stream support, which is required to interface with the Figma MCP server.

Usage

Copy Layer Link: In Figma, right-click the desired layer and copy the link.
Command Codex: Use natural language in Codex to ask for code generation or modifications based on the linked design.

Personal Impressions

Fidelity: In my experience, Codex sometimes offers slightly higher fidelity when translating Figma designs into code compared to Claude. However, for general logic and complex coding tasks, Claude remains superior. Note that neither is perfect—you will still need to manually polish the generated code, but it definitely saves a significant amount of time.
Cost & Quota: A single Claude Pro subscription’s weekly quota is often insufficient for heavy use. If you find yourself hitting the limit, combining GPT Plus with Claude Pro (totaling around 250 CNY/month) provides a robust, multi-model workflow that keeps you productive.

How to Use Claude Code with the Figma MCP Server (Step-by-Step Guide)

Sat, 01 Nov 2025 23:46:44 +0800

My project’s UI designs are provided as Figma files. Since Figma recently released an official MCP (Model Context Protocol) server, I decided to experiment with combining Claude Code and Figma MCP to generate and modify code based directly on design specs.

Requirements

Figma Permissions: You must have Dev mode access or full Editor permissions.
Claude Code Membership or API Key: Required for using the official Claude Code CLI. (If you use other MCP-compatible clients, you might only need an API key).

Claude Code Configuration

I used the local server installation for this setup. Once your local Figma MCP server is running, add it to Claude Code:

claude mcp add --transport sse figma-dev-mode-mcp-server http://127.0.0.1:3845/sse

# Verify the setup
claude mcp list

Usage Workflow

Select a Layer: Open your design in Figma and select the specific layer or component you want to work on.
Copy the Link: Right-click the node and select “Copy Link” (or use the Cmd + L shortcut on macOS).
Instruct Claude: Paste the link into the Claude Code terminal and use natural language to tell the AI what you need (e.g., “Generate a React component based on this design link”).

Personal Impressions

Fidelity: The results are surprisingly good and save a lot of boilerplate coding time. However, it’s not a “100% perfect” translation yet. There are often minor CSS or layout discrepancies that still require manual adjustment and polishing.

Resources

Generating gRPC Web and gRPC SDK from Protocol Buffers

Fri, 10 Oct 2025 17:40:07 +0800

Recently working on web3js, I needed to revisit gRPC and organize the related gRPC-web and gRPC topics.

First, the code generated for gRPC and gRPC-web from Protocol Buffers is different. Therefore, different plugins must be used to generate the code.

Generating gRPC-web from Protocol Buffers

The generated code is in CommonJS format.
The generated code can be JavaScript with TypeScript definition files (dts).
The mode is set according to needs; both modes are selectable and relate to backend proxy gateways.

 protoc --proto_path="$PROTO_PATH" \
 --js_out=import_style=commonjs,binary:"$OUTPUT_DIR" \
 --grpc-web_out=import_style=commonjs+dts,mode=grpcwebtext:"$OUTPUT_DIR" \
 "$relative_dir/$proto_filename" \
 -I "$PROTO_PATH"

Generating gRPC from Protocol Buffers

Requires installing the grpc_tools_node_protoc_ts package to support TypeScript definition generation.
Requires installing grpc-tools, which provides the grpc_tools_node_protoc tool.

 # Using grpc_tools_node_protoc to generate JS + TS in one step
 grpc_tools_node_protoc \
 --plugin=protoc-gen-ts=../../node_modules/.bin/protoc-gen-ts \
 -I="$PROTO_PATH" \
 --js_out=${IMPORT_STYLE}${OUTPUT_DIR} \
 --grpc_out=grpc_js:${OUTPUT_DIR} \
 --ts_out=grpc_js:${OUTPUT_DIR} \
 "$grpc_proto"

Third-party Dependencies in Protocol Buffer Files

For example, import "google/api/http.proto" requires downloading Google’s proto files and placing them in the specified directory to avoid errors during generation.

Final Thoughts

In summary, this covers generating gRPC client code for both web JavaScript and Node.js.

How to Use Chrome DevTools MCP in the Claude Desktop App (Step-by-Step Guide)

Mon, 29 Sep 2025 14:46:00 +0800

Google recently launched a Chrome DevTools MCP (Model Context Protocol) server, which essentially gives AI models the ability to control parts of the Chrome browser. As someone who frequently translates articles and manages content, my workflow often involves translating text, opening a site, and pasting content. I hoped MCP could automate this. During the setup, I encountered some tricky configuration issues—here’s how I solved them.

Installing Chrome DevTools MCP

In theory, you only need to add the following to your Claude Desktop configuration file (found at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). However, note that MCP servers rely on Node.js, and this specific server requires Node 22 or higher.

{
 "mcpServers": {
 "chrome-devtools": {
 "command": "npx",
 "args": ["chrome-devtools-mcp@latest"]
 }
 }
}

Note: If the app doesn’t recognize the changes after you save the config file, you may need to restart the Claude Desktop app.

Solving Node.js Version Conflicts with NVM

If you use NVM (Node Version Manager) on your Mac, you might run into trouble. On my machine, I have multiple versions ranging from v16 to v22. Since chrome-devtools-mcp strictly requires Node 22+, and Claude might default to an older version (like my v16), it will fail to start.

To fix this, you have two choices:

Uninstall all Node versions below 22 (not ideal for developers).
Explicitly point Claude to the Node 22 binary and the global module path.

I chose the second option. First, install the package globally:

# Use Node 22 to install
nvm use 22
npm install -g chrome-devtools-mcp

Then, update your claude_desktop_config.json with absolute paths:

{
 "mcpServers": {
 "chrome-devtools": {
 "command": "/Users/alanhe/.nvm/versions/node/v22.15.1/bin/node",
 "args": [
 "/Users/alanhe/.nvm/versions/node/v22.15.1/lib/node_modules/chrome-devtools-mcp/build/src/index.js"
 ]
 }
 }
}

This resolved the connection issues for me.

Using MCP within Claude Projects

I often use MCP within specialized Claude Projects. When writing your Project Instructions, be very explicit. Instruct the AI to follow strict sequential steps (e.g., “Step 1: Open the URL… Step 2: Extract content…”). This ensures the MCP triggers reliably; otherwise, the AI might skip the automation step.

Final Thoughts

Practicality: While the functionality is impressive, it has limitations. For instance, when asking the AI to type content into a web input field, it currently simulates keypresses one by one (like a typewriter effect), which is agonizingly slow. For large amounts of text, manual pasting is still faster.
Experimentation: Despite the speed issue, it’s a fascinating glimpse into the future of AI-browser interaction. It’s worth trying out just to see what’s possible.

Resources

Investigation into Web Clipboard Copying Failures

Thu, 25 Sep 2025 15:07:08 +0800

Recently, I worked on a project using Tencent’s TEA component library. It includes a Copy component that relies on copyToClipboard, which in turn depends on document.execCommand('copy'). This API has several pitfalls; here is a summary of what I encountered.

The Problem

When visiting a site via an IP-based URL, the Copy component fails to copy text if a specific DOM element is currently in full-screen mode.

Component Dependency Graph

How the Copy Component Works

Under the hood, it creates an invisible element, populates it with text, selects that text, executes document.execCommand('copy'), and then removes the element from the DOM.

Analysis

Deprecated API: document.execCommand('copy') is deprecated. However, it is still widely used because it can function even when the browser hasn’t explicitly granted Clipboard API permissions.
Full-screen Conflict: In Chrome, document.execCommand('copy') fails silently (no error, but no copy) when a DOM element is in full-screen mode.
Secure Context Requirement: The newer Clipboard API requires a secure context (HTTPS). On internal sites or IP-based URLs that lack HTTPS, the Clipboard API will not work.

Solution

Prefer the Clipboard API: Always attempt to use the modern navigator.clipboard API first. Use document.execCommand('copy') only as a fallback if the Clipboard API throws an error.
Full-screen Check: Use document.fullscreenElement to detect if the user is in full-screen mode. Since the fallback won’t work in this state, you should handle this explicitly (e.g., by notifying the user to exit full-screen if the modern API fails).

How to Use Hugo Blox (Step-by-Step Guide)

Wed, 24 Sep 2025 12:15:03 +0800

After migrating my blog from Hexo to Hugo, I settled on the Hugo Blox (formerly Wowchemy) theme framework. After six months of use, I’m quite happy with it. Here are some tips and insights from my experience.

Upgrading Hugo Blox

It’s a good practice to check for updates every few months. This prevents your project from falling too far behind the upstream repository, simplifying future maintenance.

To update the module:

hugo mod get -u

Note: This command updates the blog template framework modules, not Hugo itself. To update the Hugo binary, use your system’s package manager (e.g., brew upgrade hugo on macOS).

Recommended Service Integrations

Hugo Blox comes with many features, but I’ve found that adding a few external services enhances the experience. These typically require a bit of custom code:

Comments: Waline (a great self-hosted option).
Analytics: 51.la (or any other lightweight tracking script).

Customization: Adding Your Own Code

Hooks: Hugo Blox provides hooks that allow you to inject custom HTML into specific parts of the page without modifying the core theme. Create code snippets in the appropriate directory (e.g., layouts/partials/hooks/). Multiple files will be executed in alphabetical order. Refer to the official documentation for the list of available hooks.
New Layouts: You can add entirely new layouts under the layouts/ directory.
Overriding Defaults: To modify an existing layout, copy the file from the vendor directory (e.g., _vendor/github.com/HugoBlox/hugo-blox-builder/modules/blox-tailwind/layouts/_default/single.html) to your project’s layouts/ directory (e.g., layouts/_default/single.html) and edit it there. Hugo will prioritize your local version over the vendor version.

Final Thoughts

Have fun building your site!

Resources

Hugo Blox Official Documentation

How to Use Codex (Step-by-Step Guide)

Sun, 14 Sep 2025 21:28:58 +0800

Codex is OpenAI’s coding tool and also provides a CLI. Because I subscribe to ChatGPT Plus, I can also use Codex. Here is a quick guide to using it.

Prerequisites

You need working network access so it functions normally. For example, the terminal must be able to reach OpenAI services.

Codex paid usage

Claude Code is paid, with two ways to use it:

You need an OpenAI account and a ChatGPT Plus subscription.

GPT costs USD $20/month. There are still some lower-price regions, but they may be canceled soon. I currently subscribe via the Turkey App Store at around RMB 100/month.

Use an OpenAI API key and pay per usage.

Usage

Install codex-cli

npm i -g @openai/codex

codex

Follow the prompts to choose a login type and sign in. After a successful login, you can use it normally.

Permissions

Codex, like cc, will ask for approval on sensitive operations such as scp and rm. If you want to skip these prompts, add this flag when you start the command. Then it will not ask again during the session.

codex --dangerously-bypass-approvals-and-sandbox

Usage limits

Codex and cc both have usage limits.

Local tasks: regular users can send 30 to 150 messages every 5 hours, with a weekly cap. Cloud tasks: temporarily enjoy looser usage limits. Best for: developers who need a few focused programming sessions each week.

For details, see the official docs

Check usage

After installing the Codex extension in VS Code, you can view usage.

Initial impressions

It is much slower than Claude in terms of speed.
Auto-execution feels better than Claude’s Sonnet model.
Missing features: executing shell commands and automatic CLI upgrades. Both are must-haves for me.
Code generation is still uncertain; I need more use before drawing conclusions.

Final Thoughts

If you already subscribe to GPT Plus, give it a try so you do not waste the benefit.
For general AI CLI users, cc or Codex is a matter of preference. One is enough.

Claude Code: Install ccstatusline to Monitor Usage in Real Time

Thu, 28 Aug 2025 09:00:17 +0800

Add the following configuration to ~/.claude/settings.json to view Claude Code usage, model info, and more. If the file does not exist, create it manually.

{
 "statusLine": {
 "type": "command",
 "command": "npx ccstatusline@latest",
 "padding": 0
 }
}

Note: running npx ccstatusline@latest in the terminal also lets you customize the status line. Follow the prompts after it starts.

Claude Code Is Expensive? Try Connecting to DeepSeek

Fri, 22 Aug 2025 21:13:36 +0800

I subscribe to Claude Pro, but the quota is limited and often runs out. Yesterday DeepSeek released v3.1 and also provided a ClaudeCode-compatible API. Today I tried connecting Claude Code to DeepSeek. If you have network issues or insufficient quota for ClaudeCode, you can try DS. I think it is pretty good, so I am noting the steps here.

Shell configuration

Open ~/.zshrc or ~/.bashrc and add the following:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

For ANTHROPIC_AUTH_TOKEN, get it at https://platform.deepseek.com/api_keys.

After configuring, restart your terminal session or run source ~/.zshrc or source ~/.bashrc to apply the changes.

Launch Claude Code

Type claude in the terminal. If the proxy is configured correctly, you will see the proxied service URL in the output.

│ • API Base URL: │
│ https://api.deepseek.com/anthropic

Now you can use the DeepSeek version of ClaudeCode. The experience is basically the same as Claude, since only the model is changed.

Flexible switching between DeepSeek and Claude

With the method above, you can only use DeepSeek models. If you want to switch back to Claude, you would have to comment out the environment variables and restart the terminal. That is too annoying, so here is a more flexible approach.

alias claudeds="claude --settings '{\"env\":{\"ANTHROPIC_BASE_URL\":\"https://api.deepseek.com/anthropic\",\"ANTHROPIC_AUTH_TOKEN\":\"sk-\",\"ANTHROPIC_MODEL\":\"deepseek-chat\",\"ANTHROPIC_SMALL_FAST_MODEL\":\"deepseek-chat\"}}'"

After setting this alias, in any terminal session, use claudeds for DeepSeek and claude for Claude. No need to toggle environment variables.

Note: settings passed via command line have the highest priority, but they still merge with config files in the current directory and in the user home directory.

Current DS issues

After using it, I think DS is still a bit behind.

Request speed is slower than Claude, but acceptable.
AI understanding is weaker. For example, if you ask it to translate a Markdown article without modifying certain meta fields, it still changes them. Code generation is also not as good as Claude. But it is cheaper, so for general scenarios it is fine.

Pricing note

DeepSeek API gives some free credit at registration. If it runs out, you need to top up. DS is cheaper than Claude, so costs are lower. Still, keep an eye on it because Claude Code consumes tokens.

I used DS for one hour to translate an article and spent a bit over 3 RMB. Not bad.

Final Thoughts

I think it is great that DS provides a compatible API. It saves the effort of building a separate CLI and gives users a cheaper way to use ClaudeCode. Although DS is still slower and weaker in code quality than Claude, it is good enough for general usage. If you have not tried it, give it a shot.

How to Use Corepack (Step-by-Step Guide)

Tue, 12 Aug 2025 10:47:17 +0800

While browsing the metamask-extension source code, I saw a field in package.json: “packageManager”: “yarn@4.9.1”, but when checking yarn on npm, the latest version is still 1.22.22. Strange, so how does the actual project install this v4 yarn? After careful investigation, I found that it uses corepack for package manager and version management.

Description

Corepack is an official Node.js project, not third-party. The current latest version is v0.34.0.

How to use corepack

corepack enable


# Use yarn, pnpm, npm etc. normally for package installation

yarn install
pnpm install
npm install

When executing these package commands, corepack will automatically switch to the specified version. If the package manager or that version of the package manager doesn’t exist, it will automatically install and switch to use it.

Is corepack built-in?

Starting from Node.js v16.9.0, Corepack is a built-in feature of Node.js

Is corepack enabled by default?

Actual testing shows that even Node.js v20 doesn’t have it enabled by default, you still need to manually corepack enable.

Final Thoughts

I personally think corepack does solve a pain point, because different versions of package managers have different behaviors when installing dependencies, often causing lock file changes, which is super annoying. This way everyone uses unified package managers and versions, so lock file changes become very stable. Of course, if you need to use package managers like yarn outside of projects, you still need to install them globally yourself.

https://github.com/nodejs/corepack

Claude Pro US Subscription Guide: How to Subscribe, Pay, and Use Claude Code

Mon, 04 Aug 2025 18:16:02 +0800

Two things pushed me to subscribe to Claude Pro: first, Claude Code had become too useful to ignore; second, GPTs kept failing on system-prompt-heavy tasks, so I wanted to try Claude seriously. This post records how I solved the US-region Claude Pro subscription flow.

Prerequisites

Network access: Since Claude AI service is abroad, if you have difficulty accessing the web version, Claude Code will be the same. It’s recommended to solve the network issue first.
Non-China Apple account, such as a US Apple account.
Visa credit card: A credit card from mainland China works fine.

Purchasing Gift Cards

It’s recommended to purchase directly from Apple’s official website, which supports Visa payment. For specific usage tutorials, you can refer to US Apple ID Payment Issues

Redeeming Gift Cards

Log into your Apple ID account, go to account settings, click “Redeem Gift Card or Code”, and enter the purchased gift card code.

Download and Install Claude Pro

Works on both mobile and PC. Simply search for “Claude” in the App Store.

https://apps.apple.com/us/app/claude-by-anthropic/id6473753684

Subscription

If you do not want a long-term subscription, just subscribe for one month, complete the payment, and cancel afterward. That prevents automatic renewal when the month ends. I do not recommend paying annually here. Monthly is enough.

Following the above steps, you can successfully subscribe to Claude Pro.

Claude Pro Benefits

Use the Claude client to access Claude Chat models like Sonnet, etc.
Use Claude Code in the terminal without additional payment. Since it’s terminal-based, it’s cross-platform - you can use Claude Code wherever there’s a terminal.

Final Thoughts

I personally think Claude is currently the strongest coding model. For other aspects, GPT is still stronger. Everyone can use them according to their needs.

Mini-Program Avatar and Nickname Retrieval

Mon, 04 Aug 2025 15:30:00 +0800

Recently, while working on mini-programs, I discovered changes in how WeChat mini-programs retrieve user avatars and nicknames. Of course, the official documentation can easily mislead people. Here I’ll mark the current solution.

The current solution is as follows:

wx.getUserProfile - Server-side Decryption to Get User Information

Note: wx.getUserProfile no longer shows authorization popup, but will normally retrieve encrypted_data/code/iv information. The userinfo in the message body is only for compatibility with older versions, do not use it.

Mini-program Side Support for User Modifying Avatar/Nickname Information

1. Avatar Retrieval

Use <button open-type="chooseAvatar"> to let users actively select avatars:

<!-- wxml -->
<button class="avatar-wrapper" open-type="chooseAvatar" bind:chooseavatar="onChooseAvatar">
 <image class="avatar" src="{{avatarUrl || '/images/default-avatar.png'}}"></image>
</button>

// js
Page({
 data: {
 avatarUrl: ''
 },

 onChooseAvatar(e) {
 const { avatarUrl } = e.detail
 this.setData({
 avatarUrl: avatarUrl
 })

 // Optional: upload to server
 this.uploadAvatar(avatarUrl)
 },

 uploadAvatar(tempFilePath) {
 wx.uploadFile({
 url: 'https://your-server.com/upload',
 filePath: tempFilePath,
 name: 'avatar',
 success: (res) => {
 console.log('Avatar upload successful', res)
 }
 })
 }
})

2. Nickname Retrieval

Use <input type="nickname"> to let users input nicknames:

<!-- wxml -->
<form bindsubmit="onSubmit">
 <input
 type="nickname"
 class="weui-input"
 placeholder="Please enter nickname"
 value="{{nickname}}"
 bindinput="onNicknameInput"
 />
 <button formType="submit">Save</button>
</form>

// js
Page({
 data: {
 nickname: ''
 },

 onNicknameInput(e) {
 this.setData({
 nickname: e.detail.value
 })
 },

 onSubmit(e) {
 const { nickname } = e.detail.value
 if (!nickname.trim()) {
 wx.showToast({
 title: 'Please enter nickname',
 icon: 'none'
 })
 return
 }

 this.saveUserInfo(nickname)
 },

 saveUserInfo(nickname) {
 // Save to local storage or server
 wx.setStorageSync('nickname', nickname)
 wx.showToast({
 title: 'Save successful'
 })
 }
})

Final Thoughts

WeChat mini-program documentation is still as terrible as ever. We can only be disgusted while using it. Take care.

How to Use Claude Code (Step-by-Step Guide)

Fri, 01 Aug 2025 17:27:10 +0800

After Cursor went viral, Claude Code quickly followed. I never expected terminal-based coding to be this powerful. I tried it out of curiosity, hit a snag on the very first step, but after a few rounds of tinkering I finally got it working. It is really good. Here are the basics I noted down.

Prerequisites

Network access: Claude AI is hosted overseas. If you cannot access the web version, Claude Code will face the same issue. Solve connectivity first.
A virtual card or a non-mainland Apple account: Either one works. The reasons are explained below.

Claude Code Paid Usage

Claude Code is a paid service, with two usage options:

Claude subscription users, such as Claude Pro or higher Max plans:
- I find Apple App Store subscription the most convenient. For example, I buy gift cards from Apple’s official website, log into a US Apple account on my iPhone, and subscribe directly. For how to purchase apps in the US region, see US Apple ID Payment Issues.
Anthropic Console account: bind a credit card for pay-as-you-go billing. If you do not have a US credit card, you will need a virtual card. I used nobepay before, but they stopped accepting new card applications, so I do not recommend it now.

I personally chose the Claude Pro subscription since it includes other features. My GPT subscription happened to expire, so I decided not to renew GPT for now.

Claude Installation

For installation, just run the following command:

curl -fsSL https://claude.ai/install.sh | bash

The npm installation method has been deprecated by the official team and is not recommended.

Terminal Proxy

PC global proxy

Shell proxy configuration

Set environment variables in your terminal profile (~/.bashrc or ~/.zshrc) using the following commands:

export http_proxy=http://127.0.0.1:6152
export https_proxy=$http_proxy
export all_proxy=$http_proxy
export HTTPS_PROXY=http://127.0.0.1:6152
alias disproxy='unset http_proxy https_proxy all_proxy'

Usage

Claude usage is fairly simple at the basic level.

Type claude. On first use you will go through the login flow. Choose the appropriate method to sign in.
Enter interactive mode, describe your task, and Claude will identify and apply changes. Repeat as needed.

For advanced usage, refer to the official documentation.

Usage Monitoring

Use /usage, or check it inside the Claude app.

Auto-Accept Edits

Either enable it globally in settings, or pass the parameter when launching from the command line.

claude --permission-mode acceptEdits

Using Agents/Skills

Personally, to save tokens, I do not want to use Claude to translate my blog. I can configure a DeepSeek translation agent so Claude Code will automatically call DeepSeek for translation tasks, which saves tokens. There are a few ways to trigger this.

Manually: in interactive mode, use @agent or skills, or explicitly mention the tool in your prompt.
System prompt convention: define that a certain scenario should use the target agent/skill. After configuration, the AI will automatically call the agent/skill during real interactions.

MCP

MCP is for extending CC capabilities.

# List installed MCPs
claude mcp list

Note:

If an MCP does not work, it is likely not connected. The command above also performs a health check. If it cannot connect, copy the MCP command and run it directly to verify.
Some MCPs require higher Node versions; consider upgrading Node to the latest.

Permissions

Whether it is MCP or CC itself, permissions are always an issue. Manual approval is safer but tedious. For some operations, you can add a direct allowlist.

# Grant all tool permissions under a specific MCP
"mcp__chrome-devtools"

Bash Command Suggestions

In earlier versions, CC said it removed command completion. I could not get it to work then. In recent versions, history-based command suggestions are supported, and it finally worked for me. Maybe the earlier release only had underlying support, while this time it is truly usable. Note this is history-only. Compared to traditional shells, this is autosuggestion, not autocomplete. True autocomplete should offer multiple options you choose from.

The effect looks like this.

Note

There will be no suggestions at first. You must type and successfully run a command once for CC to record it, then it can suggest next time.
CC’s bash history is stored separately and does not use your zsh/bash history file. You can clear the global history and still see suggestions here.
Because this is autosuggestion, it only suggests one item at a time. As you adjust input, the suggestion changes.

Personally, it would be even better if it could show full command completion suggestions. I hope CC keeps improving.

Solo Mode

For sensitive operations like scp, rm, etc., there will be authorization prompts. You can choose not to be reminded again, which essentially adds that operation to the project allowlist. Other operations will still prompt. If you want a one-time solution, you can grant full permissions to the AI, which is equivalent to Gemini’s Solo mode.

claude --dangerously-skip-permissions

Final Thoughts

The Claude Code experience is quite good right now. While you may run into network issues in China, overall it is very convenient. I hope this guide helps those who need it.

Tailwind Explained (Simple Guide)

Thu, 24 Jul 2025 18:10:37 +0800

Recently, an open source project needed an H5 version, so I decided to try Tailwind. Here I’ll mark down my understanding and feelings after using it.

For learning materials, the official website is of course the top recommendation. Here I’ll mainly share my rough understanding.

Positioning

CSS framework, not a UI component library, and not UI component CSS. For example, it’s not equivalent to Bootstrap.

Usage Methods

Direct CDN loading of JS is possible, but the downside is full loading, so file size needs to be considered.
PostCSS plugin form, very convenient to integrate with build tools like Webpack, Vite. This method generates final CSS during the build process, on-demand loading, smaller size.

Characteristics

Atomic CSS, the advantage is that on-demand use is very comfortable, can combine many styles, the downside is that there will be many class names
Style names are very semantic, after playing with it more you’ll become familiar and can get started quickly

Actual Projects Used

Recent mini-program project using Taro+Webpack, Taro supports Tailwind, so it was very convenient to integrate and use.
For mobile web H5 projects, because Webpack is used, Tailwind can also be integrated.

Tailwind vs Bootstrap

The comparison isn’t quite appropriate, but for beginner users, it’s helpful to understand the differences.

Bootstrap is a UI component library, meaning the final product is a pre-designed button that follows the Bootstrap design system.
Tailwind is a CSS utility library, meaning the final product is a set of CSS classes defined semantically, allowing you to build your own buttons in a semantic way.

These two are different tools for different use cases.

Final Thoughts

I personally think Tailwind is simple and pure enough to make it a great CSS framework. In actual projects, it doesn’t interfere with using other UI component library styles, so it’s a great tool that’s indeed suitable for rapid development.

Keyof for Nested Objects

Tue, 22 Jul 2025 18:27:32 +0800

Problem

interface User {
 parent: {
 name: string;
 };

 age: number;
 name: string;
}

type Column = {
 key: keyof User;
};

const columns: Column[] = [
 {
 key: 'name'
 },
 {
 key: 'name1'
 },
 {
 key:'parent.name'
 }
];

Solution

type Paths<T> = T extends object ? { [K in keyof T]:
 `${Exclude<K, symbol>}${"" | `.${Paths<T[K]>}`}`
}[keyof T] : never

type Column = {
 key: Paths<User>;
};

In addition to writing your own Paths type, you can also use existing libraries, such as the Path type from type-fest.

Result

const columns: Column[] = [
 {
 key: 'name'
 },
 {
 key: 'parent.name' // ok
 },
 {
 key: 'parent.name1' // error
 }
];

References

https://stackoverflow.com/questions/58434389/typescript-deep-keyof-of-a-nested-object

NotebookLM Audio Podcast Experience Review: Current Limitations

Fri, 27 Jun 2025 23:09:16 +0800

I’ve been using NotebookLM for several months, and the audio overview/voice podcast feature is one I use frequently. Here’s a summary of some current limitations I’ve discovered.

Voice Tone/Speed

Currently doesn’t support prompt-based control of speech narration speed, and you can’t choose between male/female voice tones. For example, if you set the output language to Chinese, both male and female voices are fixed.

Interaction Mode

PodcastLM’s interaction mode allows you to participate in conversations between two hosts, but it currently doesn’t support Chinese. If the output podcast is in Chinese, the interaction mode button won’t be visible.

Podcast Output Language is Global Setting

This means if I change the output language, any new podcast output from any notebook will use that language.

Final Thoughts

Checking the official documentation, I see NotebookLM has some features coming soon. I can only hope they’re released early. If purchasing becomes necessary, as long as it’s good enough, it might be worth considering.

Submit URLs to Baidu via API

Fri, 02 May 2025 22:33:53 +0800

I wanted Baidu to index more of my blog posts, so I set up API submissions. Here’s the process.

Get the API Token

Open Baidu Search Console, select your site, then Regular Inclusion → Resource Submission → API Submission. The token displayed there authorizes submissions—keep it secret.

Submit URLs

Example Node.js script for my Hugo blog; any language works.

const SITEMAP_FILE = path.join(__dirname, '../public/sitemap.xml'); // sitemap path
const BAIDU_API_URL = `http://data.zz.baidu.com/urls?site=1991421.cn&token=${process.env.BAIDU_ZZ_TOKEN}`; // Baidu submission endpoint
const MAX_URLS = 5; // max URLs per request

async function submitToBaidu(urls) {
 try {
 console.log('Submitting URLs', urls);
 const response = await fetch(BAIDU_API_URL, {
 method: 'POST',
 headers: {
 'Content-Type': 'text/plain'
 },
 body: urls.join('\n') // newline-delimited list
 });

 if (!response.ok) {
 throw new Error(`HTTP error: ${response.status}`);
 }

 const data = await response.json();
 console.log('Submit success:', data);
 } catch (error) {
 console.error('Submit failed:', error.message);
 }
}

My Workflow

I run this script in GitHub Actions. Each build generates sitemap.xml; the action grabs the newest N URLs and posts them to Baidu.

Common Questions

Daily Quota

10 URLs per day.
Exceeding the quota returns HTTP 400.

Common 400 Errors

Quota exceeded
Invalid token
Wrong site parameter (omit the protocol, e.g. site=1991421.cn)

Closing Thoughts

Baidu isn’t my favorite, but it’s still worth submitting URLs for mainland readers. If you know a better method, leave a comment.

Migrate Blog from Hexo to Hugo

Wed, 30 Apr 2025 18:26:20 +0800

I’ve used Hexo for 9 years. While Hexo is still alive, themes are scarce, the visuals feel tired, and customization costs are high. Over the holiday, I decided to try migrating to Hugo.

Steps

Install Hugo

brew install go

brew install hugo

Note: newer Hugo versions can sometimes cause errors. When using HugoBlox, I hit startup errors. The fix was installing hugo@0.134.2. If you see odd issues, try downgrading.

Use HugoBlox

HugoBlox is a higher‑level framework that simplifies theme customization and feature development. It’s flexible and feature‑rich.

Visit the HugoBlox template gallery and pick a theme. Paid themes don’t have an Edit button and must be purchased. I chose a free theme and clicked Edit, which jumps to GitHub. There, create a repo from the template. Once created, proceed with theme configuration.

Theme customization

Clone the repo locally. Refer to the official docs for simple customizations.

Examples:

Enable site search
Set favicon
Configure share buttons …there are many options.

Migrate Hexo posts to Hugo

After theme setup, migrate posts. Since my site has run for years and URLs are indexed by search engines and other platforms, I need to keep URLs stable. That requires some work:

Change Hexo frontmatter description → summary.
Change Hexo frontmatter addrlink → slug.

Adjust Hugo permalink rules:

permalinks:
 blog: '/:year/:month/:day/:slug/' # Output: /2025/04/30/my-post/

Additional notes

Installing an older Hugo

Package managers like Homebrew may not provide older versions. If you hit the version issue above, install manually. Download a specific release from GitHub. For macOS, grab the darwin-universal.tar.gz archive.

Copy the binary to your PATH:

 mv $HOME/Desktop/hugo_0.134.0_darwin-universal/hugo /opt/homebrew/bin/

You may see a security warning; allow it under Privacy & Security. Then hugo version should work.

Final Thoughts

That completes the migration — total time: one day.

References

Dart Development Guide in VS Code

Mon, 28 Apr 2025 11:19:22 +0800

I recently started working with Flutter and chose VS Code as my primary editor. Here’s the tooling stack and setup notes.

Tools

VS Code — editor
- Install the Dart extension and the Flutter extension.
FVM — Dart/Flutter version manager.
Android Studio — emulator + SDK manager.

Tips for the Dart Extension

After editing pubspec.yaml, VS Code generally runs pub get automatically. For Git dependencies, trigger Pub: Upgrade Packages manually instead of deleting the lock file.
The extension resolves the Dart SDK in this order: explicit SDK path in settings, then the global PATH (e.g., fvm global).

How to Use FVM (Step-by-Step Guide)

Tue, 15 Apr 2025 17:44:50 +0800

When there are many Flutter projects, you also face the same multi-version environment maintenance issues as Node.js projects. Fortunately, there’s a similar product called FVM. Here’s a simple introduction.

Installation

brew install fvm

Install a Specific Version

fvm install 3.19.2

Note that after installation, fvm list will show that dart and other modules are not installed, but prompt that configuration is needed. This will only install when actually used, i.e., fvm use.

Use a Specific Version

fvm use

After using, you’ll find that the actual installation begins. After installation is complete, re-executing list will show the dart version information.

Generate FVM Configuration for Project

fvm use *** --save

Note that after save, the project configuration will be generated, and you can use fvm use directly afterwards.

Global Package Version Setting

Sometimes for convenience, you need to set a global version so you don’t have to use fvm commands every time. The specific setting method is as follows.


# Configure PATH in zshrc
export PATH="$HOME/fvm/default/bin:$PATH"

# Set global version
fvm global

# Cancel global version
fvm global -u

https://fvm.app/documentation/getting-started

Options for Compiling TypeScript

Wed, 02 Apr 2025 18:01:02 +0800

I’ve seen projects using tsc, ts-loader, or babel-loader for TypeScript builds. Here’s a short comparison so it’s clear what each does.

tsc

The official compiler. It performs type checking (unless you disable it—which defeats much of TypeScript’s value).

ts-loader

Webpack loader that delegates to tsc under the hood. You can configure it to skip type checking for faster builds.

babel-loader

Babel is a general-purpose compiler; TypeScript support is just one plugin. It’s fast but doesn’t type-check, so pair it with tools like ForkTsCheckerWebpackPlugin if you need type safety.

Which Should You Use?

Within our team we use both ts-loader and babel-loader depending on the project. It largely comes down to preference and build requirements.

Frontend Basics — P3

Wed, 02 Apr 2025 14:56:19 +0800

Will AI replace IT? Not anytime soon. Keep an eye on AI, but don’t forget the fundamentals — they’re the foundation, and AI is just a tool. Here’s a JS array question to illustrate some basics.

const list = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
const list2 = [,undefined, null, '', 0, false, NaN, 1,];

for (let item of list) {
 console.log(item);
 list2.map(item => console.log(item));
}

console.log('list2.length', list2.length);

// 1、输出啥
// 2、list2长度是多少

Output

1
undefined
null

0
false
NaN
1
2
undefined
null

0
false
NaN
1
3
undefined
null

0
false
NaN
1
4
undefined
null

0
false
NaN
1
5
undefined
null

0
false
NaN
1
6
undefined
null

0
false
NaN
1
7
undefined
null

0
false
NaN
1
8
undefined
null

0
false
NaN
1
9
undefined
null

0
false
NaN
1
10
undefined
null

0
false
NaN
1

8

Key points

A leading comma creates a “hole” at the head; trailing commas don’t add an extra hole.
When iterating, holes don’t trigger the callback, but iteration still advances the index — the first printed index is 1, not 0.

Will There Be Webpack 6?

Wed, 02 Apr 2025 11:35:50 +0800

Webpack 5 has been out for a long time. Will there be a Webpack 6, or is Webpack exiting the stage? I checked the repo and found the answer.

Research shows v5 shipped in 2020.

Is There a Webpack 6?

YES—Webpack is far from retiring. It remains one of the most widely used build tools and is still actively developed.

Roadmap for Webpack 6?

There’s no public v6 plan at the moment. The team is focused on stability and performance improvements for Webpack 5. Not every good feature needs a major version bump.

Other bundlers tout performance—how does Webpack respond?

The team is aware and has introduced performance optimizations in Webpack 5, with ongoing improvements.

Final Thoughts

In my team, Webpack is still the primary build tool; some projects use Vite.

References

https://github.com/webpack/webpack/issues/16377

How to Use React Hook Form (Step-by-Step Guide)

Mon, 31 Mar 2025 14:18:19 +0800

Forms are a common interaction method in user interfaces, and validating/managing their state can be challenging.

In the React ecosystem, React Hook Form package name: react-hook-form is a powerful solution for complex form management. To use it flexibly and appropriately, this guide summarizes common scenarios, usage patterns, easily overlooked points, and core principles. Please provide feedback if there are any omissions.

Usage🔨

In practical use, we often only use useForm/Controller/getValues, but hook-form has other methods/configurations that are worth exploring.

mode in useForm

Different modes affect when form validation occurs, such as when errors are obtained after validation.

The default mode is onSubmit

export const VALIDATION_MODE = {
 onBlur: 'onBlur',
 onChange: 'onChange',
 onSubmit: 'onSubmit',
 onTouched: 'onTouched',
 all: 'all',
} as const;

Note: mode affects validation strategy, but the form always detects value changes. Validation strategy before submitting behaviour.

reValidateMode

Note: If mode itself is configured as onChange, then reValidateMode becomes meaningless.

useFormContext

hook - If a form is an N-level component tree, managing complex nested form items and passing form control parameters becomes problematic. We need to pass control/setValue etc. created by create form to child components, which then pass them down to lower-level components, creating a cumbersome chain. If using useFormContext, you can directly manage form values within components without needing to pass them down layer by layer.

Layer-by-layer passing

Context

<FormProvider {...formProps}>
...
</FormProvider>


const {control} = useFormContext();

useFieldArray

hook - Sometimes data exists in array/List format. For dynamic item addition, useFieldArray is more convenient.

 const { fields, append, prepend, remove, swap, move, insert } = useFieldArray(
 {
 control, // control props comes from useForm (optional: if you are using FormProvider)
 name: 'test' // unique name for your Field Array
 }
 );

Note: You can still use arrays without useFieldArray, but it’s less convenient


<Form.Item label={'Person 0'}>
 <input
 {...register('persons.0', {
 })}
 />
 </Form.Item>

watch

watchfunc - useWatch is used to monitor specific field changes or all current field values, but if you want to know which field changed each time or perform batch watching for logic processing, you can use the watch method.

useEffect(() => {
 const wFn = watch((data, {name}) => {
 console.log('column changed', data, name) // data contains the latest values after modification
 });
 return wFn.unsubscribe;
 }, [])

Note: Remember to unsubscribe when subscribing.

watch vs useWatch

React-hook-form has two watch methods: useWatch and watch. useWatch is a hook method, watch is a function method. For single field subscriptions, you can use either watch or useWatch, but useWatch is recommended. WHY?

const allFieldWatch = useWatch({
 control,
 name:['price'], // If name is not provided, it watches all fields
 })

const priceWatch = watch(['price']);

register

registerfunc - Registers a form field and returns an object. This method is primarily for native form elements. For non-native form elements like Input components in Tea component libraries, be cautious about potential issues with onChange methods.

 <input
 {...register('address', {
 validate: (s) => {
 console.log('address validate', s);
 }
 })}
 />

Note:

name supports nested notation, such as persons.0, address.city.
For arrays, you can directly register with non-zero indices.

register vs Controller

As mentioned above, register is suitable for native elements, while Controller is suitable for higher-order form components, such as third-party components.

<Form.Item label={'Person 0'}>
 <input
 {...register('persons.0', {
 // valueAsNumber: true,
 })}
 />
 </Form.Item>
 <Form.Item label={'Person 1'}>
 <Input
 {...register('persons.1', {
 // valueAsNumber: true,
 })}
 />
 </Form.Item>

PS: The official documentation prefers using register.

Controller vs useController

Controller essentially calls useController, so they are the same - just different usage patterns: one is a component tag, the other is a hook function.

const Controller = <
 TFieldValues extends FieldValues = FieldValues,
 TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
 TTransformedValues = TFieldValues,
>(
 props: ControllerProps<TFieldValues, TName, TTransformedValues>,
) =>
 props.render(useController<TFieldValues, TName, TTransformedValues>(props));

export { Controller };

reset`func`/ setValue

If reset method doesn’t specify field values, it resets to the values set in defaultValues.
```
reset();
```
reset operation resets all fields, not just specific ones. For example, if reset only specifies field A, other fields will become undefined.
To reset a single field, you should use setValue method or carry all field values when resetting
```
 reset({
 ...getValues(),
 price: 111
})
```

Note: There is setValue but no setValues, so to implement multiple values with setValue, you need to handle it yourself through iteration

shouldDirty

The second parameter in setValue has shouldDirty, indicating whether to set the dirty state. When set to true, the form will check the dirty state to determine updates to dirtyFields. For example, if there’s no change compared to defaultValues, dirtyFields will have values.

Note: After reset, defaultValues may be updated to the newly set values.

valueAsNumber/valueAsDate

 <input
 {...register('quantity', {
 // valueAsNumber: true,
 })}
 />


// "quantity": "2121212121"
// "quantity": 2121212121

If using Controller approach, you need to implement it yourself, such as field.onChange(Number(value))

dirtyFields

formState contains dirtyFields, indicating which fields in the current form have been modified. Use this property when you need to determine which form fields have been changed.

```shell
 const {isDirty, dirtyFields} = useFormState({
 control
 });

Official Recommendations - Practice👊

transform/parse

transform and parse mentioned in react-hook-form are just practices, not built-in functionality.

const form_fields = [
 {
 name: 'price',
 transform: {
 output: v => +v
 }
 },
 {
 name: 'num'
 },
 {
 name: 'quantity'
 }

]

 {
 form_fields.map(item => <Form.Item label={item.name}>
 <Controller key={item.name} render={({field}) => <Input {...field}
 onChange={v => {
 return field.onChange(item?.transform?.parse ? item.transform.output(v) : v);
 }}
 />} name={item.name}
 control={control}/>
 </Form.Item>)
 }

Integration with validation libraries like yup

Common libraries include yup/Joi/Superstruct/zod.

const schema = yup
 .object()
 .shape({
 price: yup.number().required(),
 quantity: yup.number().min(1).max(100).required(),
 })
 .required();

const formProps = useForm({
 ...,
 resolver: yupResolver(schema),
});

Note: Validation triggering still depends on the mode setting.

Common Issues❓

setValue with null values

When setting values to null/undefined, controlled form components may not render updates properly.

This is due to React’s controlled component handling mechanism, not special handling by hook-form.

setValue('price', null, {
 shouldDirty: true,
});

const [inputValue, setInputValue] = useState(1_0);
<div>
 <label>
 <span>Name</span>
 <input value={inputValue}/>
 </label>
 <button onClick={() => {
 setInputValue(5);
 }}>
 Set to empty
 </button>
 </div>

Solution

For example, handle it during rendering like this.

<input value={inputValue??''}/>

Source Code👀

Here we examine some parts of hook-form’s source code to answer certain questions.

Package dependencies - zero dependency

React-hook-form has no dependencies, only peerDependencies. So can any React project use react-hook-form normally???

"peerDependencies": {
 "react": "^16.8.0 || ^17 || ^18 || ^19"
 },

For example, the WeChat mini-program development framework taro uses React for development. Can react-hook-form be used for form validation if needed?

Answer: YES.

Sample Taro mini-program code, using taro-ui for UI form components:

 const { control } = useForm({
 mode: 'onChange',
 });

...

<Form>
 <Controller
 control={control}
 name="name"
 render={({ field }) => <AtInput {...field} title="Name"/>}
 />
 <Controller
 control={control}
 name="test"
 render={({ field }) => <AtInput {...field} title="Test Input"/>}
 />
 </Form>

resolver principle

React hook form can integrate with different schema validation libraries because there’s a separate package - @hookform/resolvers that provides adapter support for various libraries.

2. The resolver validates based on formState values combined with the schema, then returns error information to the form in the agreed format.

...
if (result.error) {
 return {
 values: {},
 errors: toNestErrors(
 parseErrorSchema(
 result.error,
 !options.shouldUseNativeValidation &&
 options.criteriaMode === 'all',
 ),
 options,
 ),
 };
 }
...

Good performance?

Avoid unnecessary re-renders.
Use native form registration mechanism + ref management.
Controller implements minimal rendering for controlled components.
Destructure state as needed, rather than reading everything at once.

useWatch principle

Essentially calls form.control’s subscribe method in the hook’s effect to monitor form value changes. Once values change, it updates the value object.

export function useWatch<TFieldValues extends FieldValues>(
 props?: UseWatchProps<TFieldValues>,
) {
 ...
 React.useEffect(
 () =>
 control._subscribe({
 name: _name.current as InternalFieldName,
 ...
 callback: (formState) =>
 !disabled &&
 updateValue(
 generateWatchOutput(
 _name.current as InternalFieldName | InternalFieldName[],
 control._names,
 formState.values || control._formValues,
 false,
 _defaultValue.current,
 ),
 ),
 }),
 [control, disabled, exact],
 );

 const [value, updateValue] = React.useState(
 control._getWatch(
 name as InternalFieldName,
 defaultValue as DeepPartialSkipArrayKey<TFieldValues>,
 ),
 );
...
 return value;
}

Additional Information🔗

When was react-hook-form released?

Research shows that react-hook-form released its first version on Mar 3, 2019 and is currently actively maintained.

Package size

Current version: v7.56.3, with GZIP compressed package size of approximately 11KB.

Support for third-party UI form components

Such as tea-component, mui, antd.

Final Thoughts

React Hook Form provides an excellent solution for form management in React applications, offering performance optimizations, flexibility, and a clean API. Its zero-dependency approach and small bundle size make it suitable for various projects, from web applications to mini-programs. By understanding its core concepts like validation modes, field registration, and state management, developers can build robust and efficient forms that provide great user experiences.

Resumable Transfers with ssh2-sftp-client

Fri, 21 Mar 2025 10:46:13 +0800

I’ve used ssh2-sftp-client to implement terminal-side upload/download. Because it supports streams, I implemented chunked uploads/downloads with progress bars. But networks are unreliable and transfers can be interrupted, so resumable transfer is needed. Looking into the implementation, I found that ssh2-sftp-client can support resuming.

put/get Methods

The third parameter to put/get is options. It includes writeStreamOptions/readStreamOptions. Inspecting their definitions shows a start parameter, which indicates the byte offset to start from.

With start, resumable transfer becomes straightforward.

export interface ReadStreamOptions extends ReadableOptions {
 flags?: OpenMode;
 mode?: number;
 start?: number;
 end?: number;
 autoClose?: boolean;
 handle?: Buffer;
}

export interface WriteStreamOptions extends WritableOptions {
 flags?: OpenMode;
 mode?: number;
 start?: number;
 autoClose?: boolean;
 handle?: Buffer;
 encoding?: BufferEncoding;
}

Conceptual Implementation

Take upload as an example. After a successful transfer segment, record the last transferred byte offset on the client. If the network drops, the next attempt sets start to that offset and continues. In essence, resumable transfer is similar to chunked transfer.

Next.js Project Build and Release Speed Optimization

Thu, 20 Mar 2025 18:28:38 +0800

Recently worked on a project using Next.js, the entire build and release time consumption was 12min, or longer. Looking at the entire build process, found there were optimization points, marking this here.

Description

CD pipeline uses Tencent Coding.

Pre-optimization Logic

Pipeline directly goes to docker build after pulling, dockerfile has following steps

Builder intermediate process, npm install packages
next build, package frontend resources
run process, install packages, next start project

After Optimization

First about time, average 6min, currently fastest 5min.

CI pipeline loads custom image environment for build, here using nodejs image
Mount /root/workspace/.next/cache and npm cache
Package under custom image, and choose next standalone mode
docker build image doesn’t need multiple steps, only CP all next resources into directory, node server.js start

Note: After optimization, packaged image is 300MB, before optimization was 2GB.

Summary

Minimize build time as much as possible, thereby improving delivery speed.

https://vwood.xyz/archive/89b4cf53-b249-4055-935b-07fcf5abf4bf

Once Handling in EventEmitter

Tue, 18 Mar 2025 15:48:53 +0800

EventEmitter Initial Version

class EventEmitter{

 constructor(){
 this.events={}
 }

 on(type,listener){
 if(!this.events[type]){
 this.events[type]=[]
 }
 this.events[type].push(listener)
 }


 emit(type,...args){
 this.events[type].forEach(listener=>{
 listener.call(this,...args)
 })
 }

 off(type,listener){
 if(this.events[type]){
 const index=this.events[type].indexOf(listener)
 if(index!==-1){
 this.events[type].splice(index,1)
 }
 }
 }


 once(type,listener){
 const onceListener=(...args)=>{
 listener.call(this,...args)
 this.off(type,onceListener)
 }
 this.on(type,onceListener)
 }
}

Testing

const eventEmitter=new EventEmitter()
const listener=(args)=>{
 console.log(args);
}
eventEmitter.once('test',listener)
eventEmitter.off('test',listener)
eventEmitter.emit('test',{a:1})

When executing the above code, you’ll find that the test event was triggered once, but it should not execute because it was turned off. The solution is as follows.

Once Failure

...
 off(type,listener){
 if(this.events[type]){
 const index=this.events[type].findIndex(l=>l.fn===listener||l===listener)
 if(index!==-1){
 this.events[type].splice(index,1)
 }
 }
 }

...

 once(type,listener){
 const onceListener=(...args)=>{
 listener.call(this,...args)
 this.off(type,onceListener)
 }
 onceListener.fn=listener
 this.on(type,onceListener)
 }

Final Thoughts

Loading node_modules Resources in VSC WebView

Mon, 17 Mar 2025 18:50:52 +0800

Recently, while developing the gitlink plugin, I encountered an issue loading node_modules resources in WebView. Although CDN resources could be used directly, loading local resources is faster. Here’s how to solve the loading of node_modules resources.

Configuration

Install npm dependency

npm install @highlightjs

Note that this should be a dependency, not a dev dependency.

Configure localResourceRoots in webview

 const panel = vscode.window.createWebviewPanel(
 'codeImage',
 'Code Snippet Image',
 vscode.ViewColumn.Beside,
 {
 enableScripts: true,
 retainContextWhenHidden: true,
 localResourceRoots: [
 vscode.Uri.joinPath(extensionContext.extensionUri),
 ]
 }
 );

Here, we use extensionContext.extensionUri as localResourceRoots, allowing us to access node_modules resources within the extension.

Load resources in webview

<link rel="stylesheet" href="node_modules/@highlightjs/cdn-assets/styles/github-dark.min.css">

Please note that relative path syntax is preferred over absolute path syntax. Absolute paths are not supported, but web addresses are.

Handle HTML href paths

const readHtml = async (htmlPath: string, panel: vscode.WebviewPanel) =>
 (fs.readFileSync(htmlPath, {
 encoding: 'utf8'
 }))
 .replace(/%CSP_SOURCE%/gu, panel.webview.cspSource)
 .replace(
 /(src|href)="([^"]*)"/gu,
 (_, type, src) =>
 `${type}="${panel.webview.asWebviewUri(
 vscode.Uri.file(path.resolve(htmlPath, '../../../', src))
 )}"`
 );


this._panel.webview.html = await this._getHtmlContent(code, language, options);

 let htmlTemplate = await readHtml(
 path.resolve(this._extensionContext.extensionPath, 'resources/webview/index.html'),
 this._panel
 );

This is how I handle it - processing all resources in the HTML based on the HTML’s location to obtain the path relative to the extension for node_modules resources.

Note

Don’t add the node_modules folder in the .vscodeignore file. Otherwise, the package won’t include node_modules.

At the end

Following these steps solves the issue of loading node_modules resources in WebView. When updates are needed in the future, run the npm update and repackage the extension.

VSCode Extension Internationalization Support

Fri, 14 Mar 2025 16:05:42 +0800

Recently, I needed to implement internationalization for my VSCode extension. Since the official documentation on this topic was sparse, with only an example provided, I’ll summarize how to implement internationalization here.

Internationalization can be divided into two categories: menu internationalization and extension content internationalization, such as prompt messages.

Configure package.json

 "contributes": {
 "commands": [
 {
 "command": "gitlink.openInGitHub",
 "title": "%command.openInGitHub.title%"
 }
 ]
 }

Note that the title uses a key format, and the key needs to be wrapped with %.

Internationalization JSON Files in Project Root

Below are two language files, default English and Simplified Chinese. If other languages are needed, corresponding JSON files can be added.

package.nls.json
package.nls.zh-cn.json

The content format is as follows:

{
 "command.openInGitHub.title": "Open in GitHub"
}

Extension Content Internationalization

Create l10n Folder

Create an l10n folder in the project root directory.

Configure package.json

{
 "l10n": "./l10n",
}

Execute Resource Extraction Command

Execute the following command to extract all strings from the src directory to form internationalization JSON files.

npx @vscode/l10n-dev export --outDir ./l10n ./src

Note that files need to use the following format to be correctly extracted.

vscode.l10n.t('Congratulations, your extension "GitLink" is now active!')

Create Target Language JSON Files

Test

With the internationalization configuration complete, try changing VSCode’s language settings to experience different languages during operation.

References

https://github.com/microsoft/vscode-extension-samples/tree/main/l10n-sample

The Host Field in HTTP Request Headers

Thu, 13 Mar 2025 18:08:11 +0800

Recently came across a frontend question: “Is the Host field necessary when sending HTTP request headers?” I hadn’t paid much attention to this before, so I did some research and here’s a summary.

Is the Host Field Necessary?

Yes, it is necessary. For example, the same machine can have multiple hosts bound to the same port. In my blog server setup, I have domains like 1991421.cn, en.1991421.cn, etc., all bound to the same server. Without the Host field, the server wouldn’t know which specific host you’re trying to access.

Why You Don’t See Host in Chrome Network Tab

Starting with HTTP/2, the :authority field is used instead of Host.
If you examine HTTP/1.1 requests, you can see the Host field.

When we check on the server side, we can usually use req.host normally because frameworks typically abstract away the differences between these fields.

Why I use chrome request a site URL do not see Host header?

Final Thoughts

The Host header is indeed essential for modern web hosting where multiple domains share the same IP address and port. While HTTP/2 introduced the :authority pseudo-header as a replacement, the underlying concept remains the same - identifying which specific host the client wants to communicate with on a shared server.

node-sass Discontinued Maintenance

Mon, 10 Mar 2025 18:16:55 +0800

Recently while looking at dependency package upgrades for an old project, I noticed that node-sass has been discontinued from maintenance, so I’m documenting this specifically.

Main Reasons

1. Insufficient Maintenance Manpower

The recent maintenance team no longer has enough bandwidth (energy and time) to continue updating the project
node-sass hasn’t had a new release version for a year and a half

2. Technical Evolution Process

node-sass was the first official Sass compiler available in the JavaScript ecosystem
It’s essentially a Node.js wrapper for LibSass
Now the official recommendation is to use Dart Sass as the primary implementation

3. Current Status

The npm package has been marked as deprecated
The GitHub repository has been archived to avoid confusion with active Sass repositories
The underlying LibSass implementation:
- Although deprecated, it hasn’t completely reached end-of-life
- Maintainer Marcel Greter still occasionally makes fixes
- There’s no officially supported way to use this implementation from Node.js

Migration Recommendation

If you’re currently still using node-sass, the official strongly recommends migrating to the primary implementation Dart Sass.

Historical Significance

This change marks an important transition in the Sass ecosystem:

Initially developed in the Ruby community
node-sass helped it take root in the JavaScript ecosystem
Now shifting to Dart Sass as the primary implementation

Reference Sources

Node Sass is end-of-life

Cloudflare Security Check

Mon, 10 Mar 2025 17:23:30 +0800

Recently, a friend in our group chat encountered an error while filling out a waitlist form on manus and thought it was a site issue. After investigating, I found it was actually a Cloudflare issue. Once the problem was identified, it was easy to solve. I used my proxy node to help fill out the form. This small issue highlights how many people are unaware of Cloudflare’s security checks, so I’ll briefly summarize it here.

Cloudflare Security Check Results

The screenshots above show Cloudflare’s security check page on the manus website. Figure 1 shows success, Figure 2 shows failure.

For websites that use Cloudflare, when accessing them, Cloudflare performs security checks. If the check fails, it can prevent further operations, such as form submissions.

What Does the Security Check Verify?

Basic security validation
Bot detection
Threat intelligence checks
DDoS protection checks And more. Simply put, issues like problematic IP addresses can also cause the check to fail.

Things to note:

If you’re accessing from mainland China, you may need to use a proxy since many CF IPs are blocked by the Great Firewall
Some normal proxies or VPNs might trigger CF’s security checks
The strictness of the checks can be adjusted by the site owner in the CF control panel

How to Resolve Security Check Issues as a User

Change proxy nodes. If you’re in China, you need to use a proxy because many CF IPs are blocked.

For example, in my Surge configuration, I have the following rule to route Cloudflare traffic through a specific proxy node:

DOMAIN-SUFFIX,cloudflare.com,Final-select

Final Thoughts

This provides a basic understanding of Cloudflare’s security checks. Since my personally hosted sites still need to serve users in China, I’m not considering using Cloudflare for now.

How to Use Firecrawl MCP in Cursor (Step-by-Step Guide)

Sun, 09 Mar 2025 09:53:53 +0800

Features

Let’s first discuss what Firecrawl MCP can do.

Supports scraping, crawling, searching, extraction, deep research, and batch scraping
Web scraping with JS rendering
URL discovery and crawling
Web search with content extraction
Automatic retries with exponential backoff
Efficient batch processing with built-in rate limiting
Credit usage monitoring for cloud API
Comprehensive logging system
Support for both cloud and self-hosted FireCrawl instances
Mobile/desktop viewport support
Smart content filtering with tag inclusion/exclusion

Configuration

Configure the Firecrawl MCP Server startup command in Cursor.

env FIRECRAWL_API_KEY=your-api-key npx -y firecrawl-mcp

# Windows
cmd /c "set FIRECRAWL_API_KEY=your-api-key && npx -y firecrawl-mcp

I only have a Mac, so Windows hasn’t been tested.

Available Tools

As you can see, Cursor has integrated all Firecrawl tools. Therefore, you only need to use natural language to communicate with Cursor and access all Firecrawl tools.

Results

Note: The more detailed the prompt, the more accurately Firecrawl tools can be called and the more accurate information you can get. I just did some simple testing here.

Final Thoughts

The AI crawler Firecrawl is good so far. If you need to crawl web page data, consider using it.

GitLink for VSCode: Seamless Cross-Platform Code Sharing Experience

Sun, 02 Mar 2025 10:53:31 +0800

I frequently use the GitLink plugin in JetBrains IDEs to copy Git web URLs for files with one click, which significantly streamlines code collaboration.

Increased VSCode usage at work recently revealed a lack of comparable extensions. To improve efficiency, I developed Beautiful GitLink, a VSCode extension that replicates and enhances this functionality.

Demo

Features

Supports one-click copying of Git web URLs from both File Explorer and active editors
Multiple copy formats: raw URL, Markdown link, or Markdown link with code snippet
One-click browser access to Git web URLs
Built-in templates for major Git platforms with options for custom templates

Built-in Supported Git Platforms

Currently supports these platforms, with custom platform configuration available:

GitHub
GitLab
Gitee
Tencent Coding
Tencent WorkerBee (Community Edition, Internal Network Version)

Installation

https://marketplace.visualstudio.com/items?itemName=AlanHe.cn-alanhe-gitlink

Settings Sync

VSCode natively supports configuration syncing through GitHub account login. For Cursor IDE users, manual sync or third-party sync extensions are necessary.

Data Security

No server interactions
Zero-user data collection

Final Notes

Active maintenance and development continue. Please submit issues for feedback.

Building Real-time Web Page Ranking Monitoring with GitHub Action

Thu, 20 Feb 2025 14:57:07 +0800

Recently, I had a requirement to monitor the ranking situation of a certain entry in a competition. Unfortunately, the event itself doesn’t have a ranking page, and the event data is paginated and unordered. Therefore, I thought of using GitHub Action to build a real-time web page ranking monitoring tool.

Implementation Approach

Set up a GitHub Action schedule cron job, for example, execute every 10 minutes.
Execute a script to request the web page’s API interface and get data information. Since I’m more familiar with JS, I use Node.js for implementation.
Based on the data information, calculate ranking situations and process into needed data.
Update to HTML based on the data.
SSH connect to the server and upload HTML files.
Meanwhile, send data to Telegram for instant IM notifications.

Final Deliverables

HTML page displaying ranking information, refreshed every 10 minutes
Telegram bot sending ranking information

GitHub Action Usage Notes

GitHub Action’s cron expressions currently do not support timezone settings
For individual accounts/organizations, non-public repositories have execution quotas - currently 2000 minutes. If exceeded, usage will be suspended Quota details: https://github.com/settings/billing/summary
GitHub Action execution environments include macOS, which can be configured if needed

Final Thoughts

Building this entire system including development took just about an hour. I have to say GitHub Action is truly powerful, and you can create many creative solutions with it. The scheduled jobs and web scraping mentioned above are just the tip of the iceberg - there’s much more to explore in the future.

Web Dev — Show Search Button on iOS Keyboard

Thu, 20 Feb 2025 14:04:21 +0800

On mobile, focusing a web input field brings up the system keyboard. If you want a “Search” button to appear on the keyboard, some attributes are needed.

input type=“search”

With the following, iOS does not show a Search button in testing, while Android does.

<input type="search" />

enterKeyHint=“search”

With the following, iOS does show the Search button. Android also displays it correctly.

<input type="search" enterKeyHint="search" />

search event firing

On Android, pressing the Search button fires the search event. On iPhone, pressing Search only triggers the Enter event. So listen for Enter and check accordingly.

el.addEventListener('search', (e) => {
 console.log(e)
})

el.addEventListener('enter', (e) => {
 if (e.key === 'Enter') {
 console.log('Search')
 }
})

Final Thoughts

The above solves showing a Search button on the mobile keyboard for both iOS and Android when an input is focused.

References

https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/enterkeyhint

How to Use ESLint (Step-by-Step Guide)

Wed, 19 Feb 2025 12:35:31 +0800

Common Plugins

 "eslint-config-tencent"
 "plugin:react/recommended",
 "plugin:@typescript-eslint/recommended",
 "plugin:react-hooks/recommended"

https://www.npmjs.com/package/eslint-config-tencent

Webpack Plugin to Auto-Rename Variables

Fri, 14 Feb 2025 16:21:49 +0800

I previously built a webpack loader called domain-replace-loader to replace domains in frontend JS, e.g., swapping to a new domain or a global window property, avoiding manual edits across repos. Sometimes the requirement isn’t about domains. A colleague recently asked to rename variables in code automatically. For example, rename T_PROJECT to P_PROJECT. I updated the plugin to support automatic variable renaming.

Approach

The core is parsing code with esprima, walking tokens, and operating based on each token’s type.

As you can see, the token type for identifiers is Identifier. So we just check whether the identifier name matches, and if it does, perform the replacement.

Be mindful of performance overhead during replacement.

Key Code

if (item.type === 'Identifier') {
 const {value} = item;
 let res = value;
 q?.forEach((obj) => {
 res = res.replace(obj.reg, `${obj.value}`);
 });
 if (value === res) return;
 source = source.replace(value, res);
 }

Final Thoughts

With auto-renaming supported, you can build other useful features—for example, keyword masking. For masking, you’d need to handle not just Identifier but also string literals.

References

npm Cache

Thu, 13 Feb 2025 17:36:48 +0800

When developing with npm, you may notice that if you delete the node_modules folder and then reinstall dependencies, the installation is very fast. This is because npm has a caching mechanism.

What is npm Cache

npm cache is a mechanism where npm downloads dependency packages to a local cache directory during installation. The next time you install, if the dependency package already exists in the cache directory, npm retrieves it directly from the cache instead of downloading it again.

How to View npm Cache


npm config get cache

npm cache ls

Cache Directories for Different Package Managers

Package Manager	Cache Directory
Maven	/root/.m2/
Gradle	/root/.gradle/
npm	/root/.npm/
composer	/root/.cache/composer/
yarn	/usr/local/share/.cache/yarn/

Final Thoughts

Done.

How to Use OpenResty (Step-by-Step Guide)

Fri, 07 Feb 2025 21:16:44 +0800

Recently, I needed to modify the GZIP configuration for a web service. After checking the network, I noticed the response header showed server:openresty/1.21.4.1, which revealed that the gateway was using OpenResty. After confirming with the backend team, I needed to modify the GZIP configuration, which required some understanding of OpenResty.

What is OpenResty

OpenResty is a web server based on nginx that integrates nginx’s powerful performance with Lua’s dynamic capabilities.

Modifying GZIP Configuration in OpenResty

OpenResty’s GZIP configuration is similar to nginx’s configuration, primarily using the gzip directive.

nginx configuration path: /usr/local/openresty/nginx/conf/nginx.conf

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
gzip_min_length 256;

Testing Configuration

In practice, you should first test if the configuration is correct before restarting.

openresty -t

Restarting OpenResty

openresty -s reload

Checking OpenResty Version

openresty -v

Final Thoughts

So far, I’ve only worked with OpenResty’s GZIP configuration. I’ll add more when I encounter other configurations.
As of now, I still prefer Caddy’s configuration approach - it’s more straightforward and clear.

Handling Browser Compatibility in Vite

Fri, 07 Feb 2025 15:09:45 +0800

Vite ships an official solution for legacy browser support.

Install the Plugin

npm install @vitejs/plugin-legacy

Configure

plugins: [
 // ... other plugins
 legacy({
 targets: [
 'defaults',
 'chrome >= 55',
 'safari >= 12',
 'not IE 11',
 'firefox >= 52',
 ],
 }),
]

The plugin simplifies compatibility—no need to fiddle with Browserslist or core-js directly.

Notes

Because polyfills are injected based on targets, expect longer build times.
Avoid configuring core-js manually; the plugin handles it.

Final Thoughts

That’s all—quick and clean.

Detect and Remove Unused Dependencies in Projects

Sun, 26 Jan 2025 09:52:22 +0800

Recently when looking at some projects, I found many dependencies. After searching a few randomly, I discovered they weren’t being used and could be removed. However, checking and removing these packages one by one is too troublesome. Based on this need, I wrote a small tool to efficiently detect and remove unused dependencies.

@stacker/remove-unused-deps

Usage: Execute the following command in the project root directory, interactively select unused dependencies, and press enter to uninstall and remove them.

npx @stacker/remove-unused-deps@latest

Principle

depcheck: This tool is excellent mainly because it can detect unused dependencies and development dependencies in projects. However, it has the drawback of only outputting unused dependencies without actively uninstalling them. Therefore, it must be combined with other tools to complete the task.
fs scans the project’s lock file to determine whether the package manager is yarn or npm
Build an interactive command line that executes the corresponding uninstall command after the user selects the dependencies to be removed

Special Case Packages

Some packages, although detected as unused, may not be unnecessary but are needed in the project. For example, if the project depends on package A and package A uses package B, but package B isn’t listed in the dependencies, manual user confirmation is still needed.

At the end

With this tool, it’s convenient to detect and remove unused dependencies in projects. Removing unused packages helps clarify project dependencies and prevents developers from using packages just because they’re available, which can lead to multiple solution packages coexisting in the project. Currently, this tool only supports yarn and npm; other package managers are not yet supported. However, as demand increases, this will be supported later.

Pipeline Optimization — Cache Directories

Sat, 25 Jan 2025 10:17:23 +0800

Continuous integration pipelines often rebuild frontend projects, and package installs happen constantly. If every job starts from scratch—fresh checkout, fresh npm install—the feedback loop crawls. Caching pays off quickly.

Typical Case: Cache npm on the Host

Scenario: the CI agent installs dependencies directly on the host with npm install. Persist the host’s npm cache so subsequent runs reuse it. This doesn’t help Docker-based builds because installing inside the container doesn’t touch the host’s node_modules.

Docker Builds: Mount the npm Cache

pipeline {
 agent any
 stages {
 stage('npm cache') {
 steps {
 script {
 docker.image('node:14').inside('-v /root/.npm/:/root/.npm/') {
 sh 'npm install'
 }
 }
 }
 }
 }
}

Scenario: the CI pipeline builds the frontend Docker image, and the npm install step happens inside the container. Mount the host’s npm cache into the container to avoid redownloading packages.

Timing Comparison

Measure your pipeline both ways. In my tests, caching slashed repeated builds from minutes to seconds.

Final Thoughts

Whether it’s frontend or backend, look for caches that can be safely shared between runs to boost throughput.

References

One-Click Open VSCode Projects with Alfred

Thu, 23 Jan 2025 14:10:02 +0800

Cursor(VSCode) has been used frequently for coding, but opening projects is inefficient. I wanted to create an Alfred Workflow for a one-click VSCode project opening. Research showed that VSCode stores recently opened projects, making this technically feasible.

Screenshots

Download: VSCode-Open Project

Implementation Approach

Database Access

VSCode/Cursor stores recent file/folder history in:

VSCode $HOME/Library/Application\ Support/Code/User/globalStorage/state.vscdb
Cursor $HOME/Library/Application\ Support/Cursor/User/globalStorage/state.vscdb

Note: Application Support contains spaces, requiring \ escaping in the command line.

Database Query

Use Ruby to query and extract recent project paths from history.recentlyOpenedPathsList in ItemTable, parsing JSON data with jq.

Mac has SQLite pre-installed for direct use.

Alfred Format Output

With data extracted, the output follows the Alfred Script Filter format.

Open VSCode/Cursor

Multiple methods:

URL Scheme
Command line (vscode, cursor)

URL Scheme was used, and both VSCode and Cursor support it.

Conclusion

This workflow significantly simplifies opening VSCode/Cursor projects.

Is Deploying Node.js on Multi-Core Machines a Resource Waste

Mon, 06 Jan 2025 15:49:56 +0800

Our server-side project is deployed in a cluster, with each POD running a docker-nodejs application. POD configuration is 2 CPU cores, 16GB memory. Since Node.js is single-threaded, is there resource waste here? Let’s think about this issue.

Application Situation

Multiple HTTP servers are started under app.js, each server listening on a different port.

Although multiple port services are started here, they still only occupy one process on the machine. Since Node.js is single-threaded, these multiple web services themselves also run in a single thread, and there is resource competition between them.

CPU Waste?

Looking at the actual situation of the production project, CPU usage is very low, reaching only 18% at maximum.

Is Multi-Core Usage Possible?

Node.js applications run under a single process, but Node.js has some commands like child_process, cluster, worker_threads. These commands can create child processes, and child processes can run in different threads, thus utilizing multiple cores. Therefore, there is a possibility of multi-core usage.

Conclusion

Single-threaded Node.js applications on multi-core machines have the possibility of resource waste. But to be safe, it should be based on actual load conditions
Considering that Node.js has the possibility of multi-process usage, multi-core is also fine.

Command Line Git Operations Repeatedly Prompt for Username and Password

Mon, 06 Jan 2025 15:02:31 +0800

When executing git pull/push operations in the terminal, it keeps prompting for username and password, even though I’ve already entered them before. Here’s how to solve this issue.

Git Prompting for Username and Password

Username for 'https://git.xxx.com': Password for 'https://git.xxx.com':

Solution

Open the terminal and execute git config --global credential.helper store command to store credentials locally.
Execute the git pull/push operation, enter username and password once, and it won’t prompt again for subsequent operations.

Command Scope Explanation

When using the --global parameter, the setting affects all Git repositories for the current user. The configuration is saved in the ~/.gitconfig file in the user’s home directory.
If you want it to only affect the current repository, remove the --global parameter and execute git config credential.helper store. The configuration will be saved in the .git/config file of the current repository.

Alternative Solutions

If the above operation doesn’t work, try the following steps:

First, clear existing credential configuration:

git config --global --unset credential.helper

Reset credential storage:

git config --global credential.helper store

At the end

Git is a frequently used tool, so it’s important to document common issues promptly for future reference.

peerDependencies Explained (Simple Guide)

Thu, 02 Jan 2025 11:05:26 +0800

Besides dependency and devDependency in package.json, there’s also peerDependency. Let’s resolve a real-world error to understand how it works.

Error Message

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: a@0.0.1-beta
npm ERR! Found: ssh2@1.15.0
npm ERR! node_modules/ssh2
npm ERR! ssh2@"1.15.0" from the root project
npm ERR! ssh2@"^1.12.0" from ssh2-sftp-client@9.1.0
npm ERR! node_modules/ssh2-sftp-client
npm ERR! ssh2-sftp-client@"^9.1.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer ssh2@"1.16.0" from a@0.0.1-beta
npm ERR! packages/a
npm ERR! a@0.0.1-beta
npm ERR! node_modules/a
npm ERR! workspace packages/a from the root project
npm ERR!
npm ERR! Conflicting peer dependency: ssh2@1.16.0
npm ERR! node_modules/ssh2
npm ERR! peer ssh2@"1.16.0" from a@0.0.1-beta
npm ERR! packages/a
npm ERR! a@0.0.1-beta
npm ERR! node_modules/a
npm ERR! workspace packages/a from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR!
npm ERR!
npm ERR! For a full report see:
npm ERR! /Users/alanhe/.npm/_logs/2025-01-02T02_53_13_141Z-eresolve-report.txt

npm ERR! A complete log of this run can be found in:
npm ERR! /Users/alanhe/.npm/_logs/2025-01-02T02_53_13_141Z-debug-0.log

Error Analysis

The project’s direct dependency pins ssh2 at version 1.15.0, while package a lists ssh2@1.16.0 in its peerDependency field.

Because peerDependencies declare which version the consuming project must install, npm expects us to have ssh2@1.16.0. With 1.15.0 installed, it throws a conflict.

Solution

Once you know the root cause, the fix is simple: upgrade ssh2 in the main project to the required version.

Summary

PeerDependencies let a package specify the acceptable version range of another dependency in the consuming project. When the consuming project also depends on it, that version must satisfy the peer constraint.
Declaring something in peerDependencies doesn’t install it automatically if the main project doesn’t list it in dependencies. In current npm versions (such as v9), it only gets installed when another package depends on it.

Click-to-Component Source Code Analysis

Tue, 31 Dec 2024 16:08:48 +0800

Click-to-component is a React component that enables one-click navigation to source code, significantly improving development efficiency. Here I attempt to read the source code and document key points.

Source Code Structure

The project uses pnpm as the package management tool, with pnpm workspace managing multiple packages.

The core package is click-to-component-react under packages, while the apps directory contains projects that integrate this component package for testing and validation.

├── apps
│   ├── cra
│   ├── next
│   └── remix
├── package.json
├── packages
│   └── click-to-react-component
├── pnpm-lock.yaml
├── pnpm-workspace.yaml
└── turbo.json

Source Code Analysis

Starting from the index entry point for source code interpretation.

export const ClickToComponent =
 process.env.NODE_ENV === 'development' ? Component : () => null

Here, NODE_ENV is used to determine if it’s a development environment. If it is, the Component is returned; otherwise, a null component is returned. The benefit of this approach is that in production builds, this component won’t be included, reducing bundle size.

When the component loads, the window directly listens for click/contextmenu/keydown/keyup/mousemove/blur events. When clicked, the event can capture the target element.

In development mode, elements have properties starting with __reactInternalInstance$ or __reactFiber. These properties point to the fiber object.

The fiber object has a _debugOwner property, which points to the parent fiber object. Using the following logic, you can obtain nested fiber objects all the way up to the root fiber object.

 const instances = new Set()
 let instance = getReactInstanceForElement(element)

 while (instance) {
 instances.add(instance)

 instance = instance._debugOwner
 }

Additionally, the fiber object has a _debugSource property, which points to the source code file.

 const {
 columnNumber = 1,
 fileName,
 lineNumber = 1,
 } = instance._debugSource

Note: Production builds also have fiber properties on elements, but they lack debug property information

Once you know the source file path, line and column numbers, you just need to combine them with URL Scheme to navigate to the corresponding source file. VSCode has excellent URL Scheme support, refer to VSCode URL Scheme.

Final Thoughts

This completes the source code analysis of the entire component. The implementation logic isn’t complex but tests fundamental knowledge:

React Fiber
Tree shaking
Event listening
URL Scheme

The component demonstrates how React’s internal debugging information can be leveraged to create powerful developer tools that enhance the development experience without impacting production performance.

Get GitHub Education Verification for Free Copilot Access

Fri, 27 Dec 2024 21:38:18 +0800

The better AI code assistance tools are Cursor/GitHub Copilot/JB’s AI Assistant. Due to cost considerations, I only subscribe to ChatGPT, but I still need an AI tool for JetBrains IDEs. I decided to use my student identity to get GitHub education verification for free Copilot access.

Application

Application URL: https://education.github.com/pack

Just fill in according to the official requirements.

Notes

Your GitHub account email doesn’t need to be .edu - as long as identity verification is OK
During the entire GitHub student verification process, do not use proxies (except for Bing Maps, mentioned below) and keep location permissions enabled for GitHub (required)

For a complete application guide, I recommend reading this article contributed by a community member.

If the review is fast, you’ll receive an email with results the same day. Then within a few days, you’ll receive GitHub Pro membership and Copilot.

Other Education Verification Benefits

There are many other benefits from education verification, not just limited to GitHub.

For example:

JetBrains
Notion
Axure

Enhance Development Experience with click-to-component

Thu, 26 Dec 2024 10:50:17 +0800

In actual development, finding code often involves copying styles or text from the browser and searching in the IDE. Can I directly click any element on the page and jump to open the corresponding code file in the IDE? click-to-component is such a tool.

Effect

Installation

npm install click-to-component

Usage

Add the following code to your render function. Using environment variables to control the IDE is recommended so individual developers can control which IDE to open. If everyone uses the same IDE, you can hardcode it, like vscode.

 <ClickToComponent editor={process.env.REACT_APP_CTC_EDITOR} />

ClickToComponent can be placed in any render position; it doesn’t have to be in the root component.

Dependencies

click-to-component only requires you to install and configure the component in your project and have the corresponding editor adequately installed, with no other installations needed.

Bonus: If you have react devtools installed, it will be even better as it will improve the tool’s speed in finding components.

Production Build

ClickToComponent already includes environment variable checks, so for production builds, just ensure NODE_ENV=production, and ClickToComponent won’t be included in the build.

JetBrains IDE Support?

The official repo currently only supports vscode/vscode-insiders/cursor. Regarding JB IDE support, I’ve submitted a PR that is waiting to be merged. If you’re eager to use it, you can directly reference the commit as a version.

{
 dependencies: {
 "click-to-component": "https://github.com/alanhg/click-to-component.git#abc56dfb574efcc49cb31e14743e769c5429c85f"
 }
}

Using JB is slightly more complicated than vscode.

You need to install JB’s plugin IDE Remote Control.
The IDE needs to have the project open.

At the end

click-to-component’s initial purpose was to enhance the development experience by reducing time spent finding code during development and improving development efficiency. I’ve been using it for a while now and like it. I recommend that everyone try it.
If you’re curious about how this tool is implemented, check out its source code.

Docs

JetBrains URL Scheme Explained (Simple Guide)

Wed, 25 Dec 2024 10:55:11 +0800

While using click-to-component recently, I discovered it didn’t support JB IDE integration, so I spent some time implementing support. Here, I’ll mark down JB’s URL Scheme support situation.

JB IDE itself doesn’t provide direct URL Scheme support. After research, I found the following 2 solutions.

JetBrains Toolbox

After installing the toolbox, it provides support for various JB IDEs.

Supported IDE List

IntelliJ IDEA
AppCode
CLion
PyCharm
PhpStorm
RubyMine
WebStorm
Rider
GoLand
RustRover

Supported Actions

Checkout a repository and open it with the corresponding IDE

jetbrains://${toolTag}/checkout/git?checkout.repo=${cloneUrl}&idea.required.plugins.id=Git4Idea

Open a repository file and move to the corresponding line and column position.

jetbrains://${toolTag}/navigate/reference?project=${project}&path=${filePath}:${lineIndex}:${columnIndex}

For specific URL Scheme rules, see the repository jetbrains-url-schemes

The drawback of this solution is that it doesn’t provide functionality to open a specific file directly.

IDE Remote Control

JB officially provides IDE Remote Control support, which means the IDE offers a control server that can be operated through HTTP API.

API Specification

* @apiExample {curl} Absolute path
* curl http://localhost:63342/api/file//absolute/path/to/file.kt
*
* @apiExample {curl} Relative path
* curl http://localhost:63342/api/file/relative/to/module/root/path/to/file.kt
*
* @apiExample {curl} With line and column
* curl http://localhost:63342/api/file/relative/to/module/root/path/to/file.kt:100:34
*
* @apiExample {curl} Query parameters
* curl http://localhost:63342/api/file?file=path/to/file.kt&line=100&column=34

For specific details, see JB’s official commit

The drawback of this solution is that IDE needs to install the IDE Remote Control plugin. And because it’s an HTTP service, it might conflict with local ports, requiring manual modification.

At the end

Both solutions above can achieve file click-and-jump functionality, but both have shortcomings. Looking forward to JB IDE providing comprehensive URL Scheme support directly in the future.

GZIP Compression Not Working?

Sat, 14 Dec 2024 22:15:28 +0800

Recently, a site was loading extremely slowly, and analysis revealed that one reason was that GZIP compression wasn’t enabled. However, I encountered issues during configuration, so I’m documenting this here.

Benefits of GZIP

For text files like JS/HTML, compressed size is about 1/3 of the original, so GZIP should generally be enabled unless there are specific reasons not to.
Note that Nginx doesn’t enable GZIP by default, and by default only compresses text/html. Caddy enables it by default.

Enabling GZIP

Using Nginx as an example, the following configuration is needed to enable compression for target file types:

gzip on;
gzip_types text/plain application/xml text/css application/javascript application/json text/javascript text/html; # Enable compression for specified types

When I added this configuration to our service, I found it didn’t work. It turned out the changes weren’t applied to the gateway service.

Service Architecture

Let me explain the service architecture, simplified as follows. If GZIP is only configured on Service B, communication between Service A and Service B will use GZIP for faster transmission, but since Service A doesn’t have GZIP enabled, Service A will still deliver uncompressed content to the browser client. Therefore, Service A must also have GZIP enabled for it to work.

When Service A also enables GZIP, actual testing shows that the browser receives compressed content. So does Service B still need to enable it? Personally, I think enabling it is still better since it speeds up communication between A and B, but enabling Service A is more critical.

Factors Determining GZIP Effectiveness

The client request headers include accept-encoding: gzip, which browsers include by default.
The server supports and has GZIP enabled.

Final Thoughts

While enabling GZIP is simple, it’s important to understand how it actually works.

useFieldArray in React Hook Form

Fri, 06 Dec 2024 18:22:02 +0800

In web page interactions, forms are common elements. For form validation/management, react-hook-form is a commonly used and excellent helper library. For example, useFieldArray is used for managing array values, and formContext is used for complex nested component forms. Understanding these usage patterns helps you use it more effectively.

Use Case

When handling forms, you sometimes need to process array form items, such as when users can dynamically add N rows of form items. useFieldArray is designed for this type of array handling.

Example

function FormTest() {
 const {control, register, getValues} = useForm();
 const {fields, append, prepend, remove, swap, move, insert} = useFieldArray({
 control, // control props comes from useForm (optional: if you are using FormProvider)
 name: "test", // unique name for your Field Array
 });

 console.log(fields, 'fields');
 return (
 <form>
 {fields.map((field, index) => (
 <div><input
 key={field.id} // important to include key with field's id
 {...register(`test.${index}.value`)}
 /></div>
 ))}

 <Button onClick={() => {
 append({
 value: 1,
 })
 }}>
 Add
 </Button>
 {
 JSON.stringify(getValues())
 }
 </form>
 );
}

As shown above, when clicking the Button to add, fields can automatically insert a new value, and each value can also be monitored and maintained through register/controller.

Important Details

The append value must be an object - for example, append(1) won’t work. This means fields must maintain objects, so test.${index}.value cannot be set as test.${index}.

Final Thoughts

For form handling requirements, I recommend trying this library as a solution.

Implementing Passwordless Login for Sites in iframes

Sun, 24 Nov 2024 10:09:11 +0800

Recently, in a private project, I encountered a requirement where sites embedded in iframes needed to implement passwordless login. Here are some initial thoughts on possible solutions.

Any request to the server can obtain the client IP from the request object, making IP-based authentication possible. However, the drawback is that users cannot log in once they change their network environment.

Same-Site + Cross-Domain

If two sites are same-site but cross-domain, and cookies are set with the parent domain when writing login information, then the cookie information will naturally be carried during requests, enabling passwordless login.

Different Sites

If the two sites are not on the same domain, login needs to be addressed.

When the iframe loads dynamically, it accesses a login link first, and after successful login, redirects to the target page.

Final Thoughts

This appears to be an incomplete draft exploring various approaches to implementing passwordless authentication for iframe-embedded sites. The key considerations include:

Security vs. Convenience: IP-based authentication is convenient but lacks flexibility when users change networks
Domain Strategy: Same-site configurations simplify authentication through shared cookies
Cross-Domain Challenges: Different domains require more complex authentication mechanisms

For production implementations, additional considerations would include token-based authentication, OAuth flows, and proper security measures to prevent unauthorized access.

Monaco-Editor Implementation of Syntax Highlighting

Thu, 07 Nov 2024 23:27:55 +0800

You need to configure the language to implement syntax highlighting in Monaco Editor. Here, we introduce the related operations.

Set Language

If setting the language during initialization, the operation is as follows:

monaco.create(el, {
...
language: 'sol',
 })

If setting the language dynamically:

const model = editor.getModel();
monaco.editor.setModelLanguage(model, 'json');

Built-in Language Support in Monaco

Which languages support syntax highlighting? You can confirm this in several ways.

Retrieve in the program.

const languages = monaco.languages.getLanguages();

Note: The number of languages retrieved by this method includes custom-registered languages in the application, not limited to built-in languages only.

Visit https://microsoft.github.io/monaco-editor/ and check the language dropdown options directly.
Directly visit the npm package monaco-editor/esm/vs/basic-languages, where the built-in languages are registered.

Note that each folder name does not necessarily represent the language name; the ID defines the language name.

Pack Language Files as Needed

Monaco Editor supports many languages by default. However, if you package them all, the file may be too large, so you can pack languages as needed.

To import Monaco Editor:

# Correct method
import * as monaco from 'monaco-editor/esm/vs/editor/editor.api';

# Incorrect method
import * as monaco from 'monaco-editor';

The webpack configuration is as follows:

new MonacoWebpackPlugin({
 filename: 'monaco_[name].worker.[contenthash].js',
 languages: ['json', 'solidity', 'sql'],
 })

Note: If you find that all languages are still packaged after configuring the languages in webpack, it is usually due to an incorrect import method for Monaco.

At the end

Now, we know how to configure languages in actual projects to achieve syntax highlighting.

Which Option to Choose for Git Merge

Wed, 30 Oct 2024 18:53:15 +0800

When submitting a Merge Request (MR) for a project branch, there are three options: Merge, Rebase, and Squash.

What are the differences between these three options, and how should you choose? Here’s a summary.

Merge

The essence of Merge is creating a new commit node, with all commits from the source branch brought over. If there were initially three commits, after the Merge, four commit nodes will exist, with one being the Merge Commit. The commit created by Merge also carries the source branch’s commit information. Therefore, in many Git GUI tools, these details form a commit relationship graph.

Rebase and merge

Rebase modifies the parent node of commits, moving all commits from the source branch to the end of the target branch. If there were three commits initially, after the Rebase, three new commit nodes will appear. Unlike Merge, it does not create a new commit node. Hence, in many Git GUI tools, it appears as a straight line.

Squash and merge

The essence of Squash is to merge the source branch’s commits into a single commit, generating a new commit message. In many Git GUI tools, this results in a single, latest commit node.

Which to Choose?

Understanding the differences between the three, how should you decide? Here’s a summary:

Prefer Squash because it reduces the number of commits, minimizes redundant commit messages, and makes the commit history clearer. A developer might make multiple commits on their branch. Choosing Merge or Rebase can clutter the main branch with too many commits, whereas Squash reduces the commit count. Of course, developers could also reset and re-commit in their branch, but that is more tedious.
Rebase as a secondary option, though the downside is that it does not retain merge information. If you don’t care about the merging relationship between branches and only focus on committed content and authors, this can be a good choice.
Lastly, Merge as it is the simplest and retains the merge relationship between branches. The downside is a more complex relationship graph.

How to Use the Custom name in the target attribute of <a> tag (Step-by-Step Guide)

Thu, 24 Oct 2024 23:05:24 +0800

I learned about the tag’s custom target attribute during the technical weekly meeting, and here is my note.

MDN Specification

HTML target

Where to display the linked URL as the name for a browsing context (a tab, window, or <iframe>). The following keywords have special meanings for where to load the URL: _self, _blank, _parent, _top.

As stated in the specification, the above keywords are just special meanings, which means we can define custom names.

Custom Name

For example, when clicking the following link:

It will open a new TAB window the first time, similar to the effect of _blank.
Clicking again will not open a new TAB but will switch to the originally opened TAB, and the page will automatically refresh.

<a href="https://x.com/alanhe421" target="myTarget">My Twitter</a>

This illustrates the meaning of a custom target, which is to specify a custom TAB window to open and switch to the originally opened TAB window.

At the end

We can use the custom target based on our example once we understand the custom target. We need it to avoid reopening a new tab. You can use a custom target name.

Quickly Fix Bugs in Open Source Community Repositories

Thu, 24 Oct 2024 11:39:09 +0800

In projects, we often use many third-party NPM packages, such as Mousetrap. We usually encounter bugs that have not yet been fixed or merged by the official repository. So, what should we do in such cases? Here is a summary of the methods.

Fork the Repository and Follow the PR Process

You can fork the repository, modify the source code, submit a PR, and wait for the official team to merge and release a new package. This method is undoubtedly the best; it benefits and gives back to the community.

However, this approach’s downside is also quite noticeable. If the official longed and we urgently need the package, this solution may not be very suitable.

Adjust NPM Dependency Version

Use commit hash or a different repository address. In package.json, you can use a git commit hash to lock onto a specific version directly, so whether it is merged won’t matter. Alternatively, you can publish a package yourself after forking, but the package name cannot be the same. For example, you can add a @namespace prefix.

npm install from Git in a specific version

"dependencies": {
 "package": "git://github.com/username/package.git#commit"
}

pkg alias

"dependencies": {
 "package-a": "npm:@stacker/package-b@1.0.0"
}

patch-package

In addition to the above two solutions, we can use patch-package to fix bugs quickly. This approach uses git diff to generate a patch file and then applies it directly using npm scripts hooks to modify files within node_modules. Without patch-package, directly modifying source code would not be manageable under version control. patch-package offers an elegant way to handle conflicts between patches and third-party package source code that isn’t under version control.

Modify the target package source code in node_modules, such as mousetrap-record.js under mousetrap.
Generate a patch file.
```
npx patch-package mousetrap
```
Configure npm scripts hook
```
"scripts": {
 "postinstall": "patch-package"
}
```
If the official repository fixes the bug in the future, we can delete the patch file, remove the package, and simply run npm install.

At the end

The above are a few methods for fixing bugs in open-source projects. Use them as needed.

Browser Fingerprinting

Tue, 22 Oct 2024 22:38:15 +0800

With logged‑in users, identification is trivial. For anonymous users, we can use a browser fingerprint — a unique identifier derived from available device/browser attributes at a point in time. JS doesn’t expose “a fingerprint” directly; you have to compute it (libraries like FingerprintJS help).

FingerprintJS v3

Latest is v4, but v4 uses BSL (becomes MIT after 4 years). In 2024, v4 isn’t MIT yet, so v3 (MIT) is the safe open‑source choice.

Accuracy

OSS accuracy ~40–60%; commercial ~99.5% (with server‑side components).
Fingerprints often remain stable only for weeks.

Usage

const fpPromise = new FingerprintJS.load();
 fpPromise
 .then(fp => fp.get())
 .then(result => {
 const visitorId = result.visitorId;
 console.log(visitorId)
 })

References

https://github.com/fingerprintjs/fingerprintjs/tree/v3

ua-parser-js Explained (Simple Guide)

Fri, 18 Oct 2024 16:40:22 +0800

In real-world development we often parse the UA header to detect device details—whether the user is on Windows or macOS, or if they’re on mobile. If you just use userAgent, you have to parse the string by hand, which is painful. A much easier option is to bring in ua-parser-js, a mature library that surfaces the UA information for you.

Usage

Here’s the basic usage:

const parser = new UAParser();

console.log(parser.getBrowser());
// {"name":"Chrome","version":"130.0.0.0","major":"130"}

console.log(parser.getOS());
// {name: 'Mac OS', version: '10.15.7'}

console.log(parser.getDevice());
// {vendor: 'Apple', model: 'Macintosh', type: undefined}

// 推荐使用v2版时，开启客户端提示
UAParser().withClientHints();

The result of UAParser is an object that contains browser, device, OS, engine, CPU, and other details.

Notes

ua-parser-js v2 is still in beta, but it’s recommended because it leverages newer JavaScript features for better accuracy.
It runs in both Node.js and browser environments.

TypeScript Type Safety

In v1, ua-parser-js didn’t include TypeScript definitions by default, so you had to install them manually. v2 bundles the typings, so no manual install is needed.

npm install --save @types/ua-parser-js

Bundle Size

Both v1 and v2 are about 20 KB.

Looking at the source, ua-parser-js doesn’t set sideEffects, so even with the ES module build in v2 you won’t get tree shaking.

Source Code

Under the hood, ua-parser-js parses navigator.userAgent and navigator.userAgentData. The logic is straightforward: run regexes and assemble the results into an object.

Limitations

The code primarily relies on the following APIs:

navigator.userAgent
navigator.userAgentData

That leads to a few constraints:

On Apple Silicon Macs, navigator.userAgent still reports Intel. That’s an OS-level issue in how macOS sends the UA; only Apple can fix it. v2 improves accuracy by tapping into userAgentData.
navigator.userAgentData has significant compatibility issues, so even v2 can’t guarantee complete coverage across browsers.
If the UA doesn’t expose something—like device memory or GPU—you won’t get it from ua-parser-js either.

v2 Accuracy and User-Agent Client Hints

In v2, the library calls navigator.userAgentData.getHighEntropyValues to fetch details like CPU architecture and bitness.

Here’s an example:

navigator.userAgentData
 .getHighEntropyValues([
 "architecture",
 "bitness",
 "formFactor",
 "fullVersionList",
 "model",
 "platformVersion",
 "wow64",
 ])
 .then((ua) => {
 console.log(ua);
 });

Online Validation

The official site lets you enter a UA or choose sample UAs to see the parsed device info:

https://uaparser.dev/
I tweaked the UI for personal use and host an alternative. It uses the same ua-parser-js version and features:

https://uaparser.1991421.cn/

Final Thoughts

That’s the quick tour of ua-parser-js. Hope it helps. If you want the most accurate and detailed device information, go with v2.

Frontend Visual Graph Editing

Thu, 17 Oct 2024 15:39:39 +0800

A recent project needed a visual flow editor. Here’s a survey of available libraries and tools.

IBM’s Open-Source Node-RED

Apache License

Graph Layout Library dagre-d3

MIT License

Graph Layout Library cola.js

MIT License

Open-Source Drawing Library Joint

MPL-2.0 License + GPLv2 License

Open-Source Drawing Library jsPlumb

MIT License

drawio

Apache License Version 2.0

Open-Source Draw2D

Apache License Version 2.0

GGEditor

MIT License

X6

MIT License

Note: Visual UIs can be built with SVG, Canvas, HTML+CSS, or a mix.

Opinion

Prefer actively maintained projects with an MIT license.

Passwordless Login for Linux Machines

Thu, 19 Sep 2024 16:41:56 +0800

For security reasons, passwordless login is generally implemented using public-private key pairs. Here, I’ll mark down the configuration method.

Log into the client machine and create a public-private key pair if you don’t already have one.

The public and private keys are stored in the ~/.ssh directory.
Log into the target server and open the ~/.ssh/authorized_keys file.

The authorized_keys file records the list of public keys authorized for login.
Copy the public key from the client machine into this file and save it.
Try SSH login to the target machine again, and you’ll find no password is required.

Get the Current Directory of Any Selected File in WebShell

Thu, 19 Sep 2024 14:14:29 +0800

While implementing “click to download selected filename” in a WebShell based on xterm.js, I ran into a challenge: how to determine the directory of the selected filename. After some research, here’s the solution.

Approach

First, have the terminal session report the current directory after each command using shell hooks.
Use registerOscHandler to listen for ANSI sequences and extract CurrentDir from the data.

const cwdArr = []; // index 0 unused
term.parser.registerOscHandler(1337, data => {
 const currenDirArr = data?.match?.(/(;CurrentDir=)([^;\u0007]+)/);
 if (currenDirArr?.length >= 3) {
 cwdArr[term.buffer.active.baseY + term.buffer.active.cursorY] = currenDirArr[2];
 }
})

Listen for selection changes. Combine the selection position with cwdArr to compute the CWD of the selected filename.

term.onSelectionChange(() => {
 const selection = term.getSelection();
 if (!selection) {
 return;
 }
 const selectionPosition = term.getSelectionPosition();
 term.getSelection() && copyToClipboard(term.getSelection());
 let rowNum = selectionPosition.start.y; // row
 while (rowNum < cwdArr.length && !cwdArr[rowNum]) {
 rowNum++;
 }
 const cwd = cwdArr[rowNum];
 console.log('Selected file', pathJoin(cwd, selection));
});

Final Thoughts

This approach lets you infer the working directory that produced any particular section of terminal output and, by extension, the directory of a selected filename.

babel-plugin-import Explained (Beginner's Guide)

Tue, 17 Sep 2024 16:01:23 +0800

Due to bundle size issues, I’ve revisited babel-plugin-import. I wasn’t clear about this plugin before, so I’m organizing my understanding here.

Plugin Introduction

babel-plugin-import is a Babel plugin that supports modular imports. The functionality of the plugin is to convert full imports to on-demand imports based on configuration.

Problems Solved

The import path is still for the full package, making paths shorter.
On-demand importing, resulting in smaller bundle sizes.

Examples

As mentioned officially, classic examples are antd/lodash, though this actually refers more to older versions of antd and lodash.

antd

import { Button } from 'antd';

import Button from 'antd/lib/button';

Note that although we use antd and lodash as examples here, in reality, both packages no longer need babel-plugin-import.

antd now supports tree shaking.
lodash has released an ES version package lodash-es; switching to that package name enables tree shaking as well.

Does it Conflict with Tree Shaking?

Not all projects use babel-plugin-import. Why? Because there’s tree shaking.

Are the two in conflict? Not at all, but they have the same ultimate goal: on-demand loading/bundling. When component libraries and the like support tree shaking, the build tool itself will remove unused modules during bundling. Therefore, as long as the component library supports tree shaking, you can use on-demand loading without needing babel-plugin-import.

Looking at the submission time of the plugin and when webpack started supporting tree shaking, it makes sense why babel-plugin-import was needed before. Because tree shaking wasn’t supported at that time.

Below is the submission time of babel-plugin-import:

While webpack’s support for tree shaking came in webpack v4, which was around 2019.

Conclusion

OK, that’s the analysis of babel-plugin-import.

The registry under the npm command does not work

Tue, 17 Sep 2024 15:40:08 +0800

Sometimes, switching the source of npm packages in a project is necessary due to network or security issues. The general practice is to switch the source in npmrc, but after switching and installing packages, you will find that the install still goes through the old source, primarily when a lock file has already been generated.

Here, we analyze the issue of the registry not working.

Version Information

For verification, I am using the following versions:

npm v9.5.1
node v18.16.1

Current lock file information

Reviewing the lock file, taking the @babel/plugin-proposal-private-property-in-object package as an example, you will find that the lock file directly records the address under the corresponding package version, here being https://registry.npmjs.org/.

npmrc

I tried updating the source via the npmrc file configuration as follows.

registry=https://registry.npmmirror.com

In practical testing, executing npm i does not download the package from the new source address.

install –registry

Since the RC configuration source does not work, try directly overriding the source with npm install –registry.

npm i @babel/plugin-proposal-private-property-in-object --registry=https://registry.npmmirror.com

Actual test executing the install command: --registry can override installation.

What about installing all the packages?

npm i –registry=https://registry.npmmirror.com

Tests show no change.

What if the lock file is deleted

With the lock file deleted and a re-execution of the npm install, the packages are still cached.

Deleting node_modules

After deleting node_modules and re-executing the npm install, the resolved packages are not configured via npmrc.

Deleting node_modules, lock file, then executing install –registry

It is found that all the package download addresses are https://registry.npmmirror.com. At this time, installing a new package, such as npm install antd. There is no need to set the registry manually; it will follow the source configured in npmrc.

At the end

From the above tests, it is understood that when installing npm packages, the priority processing of the registry is as follows:

Command parameter --registry
Resolved in the lock file/cache
npmrc or default registry

Based on this priority, when we need to change the package source in a project for existing packages, we either need to delete node_modules, package-lock.json and re-execute the package installation, or we need to edit the lock file to replace all registry manual addresses directly. I prefer the latter, as it does not affect the package version.

redux-logger Tree Shaking Not Working

Sat, 14 Sep 2024 15:37:24 +0800

Issue

Even in Webpack production builds, redux-logger sticks around. Since the logger is only needed in development, it should disappear. Let’s see why it doesn’t.

Project Setup

"redux-logger": "^3.0.6"

Usage:

import { createLogger } from 'redux-logger';

const logMiddlewares = process.env.NODE_ENV === 'development'
 ? [createLogger({ collapsed: true })]
 : [];

const middleWares = [...logMiddlewares];

const store = createStore(
 createRootReducer,
 compose(applyMiddleware(...middleWares))
);

Looking into redux-logger

"main": "dist/redux-logger.js" points at the distribution build. That’s fine—main can reference either CommonJS or ES modules.
dist/redux-logger.js is a UMD bundle that works in CommonJS and AMD environments. Webpack cannot tree-shake UMD output.

Given the UMD build, it’s expected that tree shaking fails.

Trying redux-logger 4.0 Beta

"redux-logger": "4.0.0"

A beta release on npm ships ES modules, so I tried upgrading. Packaging still retained the logger because tree shaking also requires the sideEffects flag.

On the plus side, the import now resolves to an ES module:

Bundle size at this stage:

Adding sideEffects

To confirm the fix, I republished the package with "sideEffects": false in package.json, then analyzed the build again.

"redux-logger": "npm:@stacker/redux-logger@4.0.1"

Final Result

With an ES module build and sideEffects declared, Webpack finally drops redux-logger from production bundles.

Reference

https://webpack.js.org/guides/tree-shaking/

Implementing SQL Autocompletion in Monaco Editor

Sun, 08 Sep 2024 17:34:41 +0800

Recently, I used Monaco editor to implement an SQL editor. To improve the user experience, code auto-completion was necessary. After some research, I found a solution, so I’m marking it down here.

Built-in Autocompletion?

YES, Monaco supports some built-in languages by default, such as JavaScript, TypeScript, CSS, JSON, and HTML. You can achieve code autocompletion for languages with built-in support simply by setting the editor language to JavaScript`.

However, for languages like SQL that do not have built-in support, setting the editor language to SQL only enables syntax highlighting.

monaco.editor.create(editorElRef.current, {
 ...
 language: 'sql',
 ...
 autoClosingBrackets: 'always',
 autoClosingOvertype: 'always',
 autoClosingQuotes: 'always',
 })

Custom Autocompletion?

For languages like SQL, if you want autocompletion, you must rely on custom autocompletion.

Through research, I found that you can register completion logic for the corresponding language using the monaco.languages.registerCompletionItemProvider method.

The registerCompletionItemProvider method allows you to define a list of completion options for the user under different input contexts. This method also supports asynchronous returns, making requesting completion from the backend feasible.

registerCompletionItemProvider vs registerInlineCompletionsProvider

Upon closely examining the API, you will notice two methods related to completion. Generally, we need to implement registerCompletionItemProvider, but what’s the difference between the two?

registerCompletionItemProvider presents a list of completion options in a dropdown, as shown in the image at the beginning of the article. In contrast, registerInlineCompletionsProvider displays completion suggestions directly after the cursor.

In the context of ZSH, this is similar to the difference between autosuggestion and autocompletion.

Example

If you want to fetch autocompletion suggestions from a backend service, you can implement asynchronous logic within provideCompletionItems. Here’s an example of requesting autocompletion data from an API:

monaco.languages.registerCompletionItemProvider('sql', {
 triggerCharacters: [' '],
 provideCompletionItems: async (model, position) => {
 const wordInfo = model.getWordUntilPosition(position);
 const range = {
 startLineNumber: position.lineNumber,
 endLineNumber: position.lineNumber,
 startColumn: wordInfo.startColumn,
 endColumn: wordInfo.endColumn
 };

 const suggestions = await fetch('/api/getSqlSuggestions', {
 method: 'POST',
 body: JSON.stringify({word: wordInfo.word})
 }).then(res => res.json());

 return {
 suggestions: suggestions.map(s => ({
 label: s.label,
 kind: monaco.languages.CompletionItemKind.Keyword,
 insertText: s.insertText,
 range: range
 }))
 };
 }
});

At the end

Following the above methods, you now understand how to implement SQL code autocompletion in Monaco-editor. Extending this method further, it’s possible to implement SQL code autocompletion through AI services since the autocompletion registration method provided by Monaco supports asynchronous returns.

How Module Import Style Affects Bundle Size

Sun, 25 Aug 2024 22:45:22 +0800

We recently discussed the impact of module import styles on bundle size in an internal CR. I think this is quite important, so I’m marking it down here.

Taking a component library as an example, you’ll see lib and es folders in the package. In development, we need to pay attention to how we import modules—different import styles can cause huge differences in bundle size.

Example

Let’s start with an example. The screenshot below shows that importing from the es directory and importing from the package root have the same bundle size, but importing from lib is very different.

Analysis

Webpack has tree-shaking. When JavaScript uses ES module syntax and is built in production mode, tree-shaking is enabled.
For the component library mentioned above, when we use es imports, it enables tree-shaking. Tools like Webpack will then perform on-demand bundling instead of full bundling.
The package.json of the component library shows both main and module fields declared:
```
 "main": "lib/index.js",
 "module": "es/index.js",
```

Final Thoughts

Frontend bundle size has always been an important issue, with solutions like CDN, on-demand loading, on-demand bundling, and GZIP. The import style issue discussed above is just one aspect of this problem.

Setting Environment Variables during SSH2 Connection

Tue, 20 Aug 2024 23:11:21 +0800

Can environment variables be set when connecting to a server using the Node.js SSH2 client? After investigation, it was found that it is possible. Just marking it here.

Setting Environment Variables

The code is as follows:

this.conn.shell({
 env: {
 X_LOGIN_IP: '128.1.1.123',
 X_ENVIRONMENT_VARIABLE: "desiredvalue"
 }, term: 'xterm-256color', // term: 'dumb',
 cols: connectOpts.cols, rows: connectOpts.rows,
 }, (err, s) => {
 if (err) {
 console.log('ssh shell error', err);
 throw err;
 }
})

Limitations

This environment variable setting is restricted by whether the /etc/ssh/sshd_config allows setting specific rule variables. Different systems have different defaults for the allowed environment variable settings.

If you need to allow specific variables, the setting directive is AcceptEnv. The example below supports setting environment variables with the X_ prefix.

Default Supported Environment Variables

As mentioned earlier, different systems have different default settings.

Ubuntu defaults to AcceptEnv LANG LC_*
Debian defaults to AcceptEnv LANG LC_*
CentOS9 does not have AcceptEnv set by default, meaning no environment variables can be set.

At the end

That’s all you need to know about setting environment variables on the client side.

Monitor Network Disconnection in WEB

Mon, 12 Aug 2024 23:57:13 +0800

Recently, I received a front-end issue about garbled text caused by the user’s network disconnection and recovery. After investigation, I found that the issue was caused by the WEB’s lack of monitoring and handling of network changes. Here are some methods to mark.

Monitor Network Changes

Monitor network changes through the online/offline events. For example, the offline event is triggered when Wi-Fi is turned off, and the online event is triggered when it is turned on.

window.addEventListener('online', () => {
 console.log('Network is online');
});
window.addEventListener('offline', () => {
 console.log('Network is offline');
});

Check Network Status

The following method can be used to check the network status in real time.

navigator.onLine // true/false

Simulate Network Disconnection in Chrome

Now that we understand how to monitor network changes and check the network status, how can we simulate a network disconnection? Fortunately, in Chrome, you can directly set the page to offline mode without changing the entire device’s network status.

Will WebSocket Connection Disconnect when Offline?

The WebSocket connection will not be immediately disconnected when the browser is offline. Moreover, when the network is restored, the data in the WebSocket will continue to be sent to the backend.

At the end

Understanding network changes and how to check network status can help better handle issues caused by network disconnection.

ShellCheck Explained (Simple Guide)

Wed, 07 Aug 2024 19:03:20 +0800

I recently had to evaluate ShellCheck for work and found it quite useful. ShellCheck detects—and often fixes—syntax issues in shell scripts, so I’m jotting down my notes here.

Installation

ShellCheck is cross-platform, supports multiple operating systems, and many apps integrate it, so you have plenty of ways to use it.

Use it directly in the browser: ShellCheck Web
Visual Studio Code extension: ShellCheck
JetBrains IDEs include the Shell Script plugin; no extra install needed, though in my testing it doesn’t expose the full ShellCheck feature set.
Command-line installation
1. macOS: brew install shellcheck
2. EPEL-based distros
```
sudo yum -y install epel-release
sudo yum install ShellCheck
```

See the official instructions for the full list of installation methods.

Shell Support

ShellCheck’s static analysis doesn’t cover every shell:

Supported: bash, sh, ksh, and zsh.
Not supported: fish, tcsh, and csh.
zsh and ksh support only works where they are compatible with bash.

Features

Whether you run it manually or automatically, ShellCheck’s job is to highlight syntax mistakes in your shell scripts.

Examples

Web Support?

I also looked into running ShellCheck entirely in the browser.

The official web demo sends your script to the server and runs ShellCheck there.
Full client-side execution isn’t officially supported right now, but converting the Haskell codebase to WASM might work—no firm conclusion yet.

Final Thoughts

If you write shell scripts regularly, install the plugin in your editor—it can save you from many avoidable syntax errors.

Wave Terminal Explained (Beginner's Guide)

Sun, 21 Jul 2024 23:34:47 +0800

Due to work needs, I have used many terminals, such as iTerm2, Warp, Tabby, Hyper, etc.

Recently, I researched Wave Terminal and found some highlights, so I’ll introduce it here.

Platform

Wave is a local terminal, not web-based, currently supporting.

Mac (M series also supported)
Linux
Windows WSL (Windows is also supported!)

For the Mac version, it’s about 224MB, which is acceptable.

Free and Open Source

Wave is an open-source and free terminal. It has similarities with Warp, such as block mode display, and is therefore also known as an open-source free Warp alternative.

Usage

Here’s how to use it. First, Wave doesn’t require a login, which is a 👍 point.

Connection

To log in to a remote machine, first create a connection.

After creating, you can try to connect. If prompted to install remote scripts, click install, and once the connection is successful, you’re good to go.

Regarding connection configuration, the path to delete connection configurations is too cumbersome. Currently, you need to: select connection - delete - confirm deletion.

Workspace

In Wave, click on a workspace, then click Create New Tab, and choose the terminal connection to log in to the target machine. You can also customize the theme color of the session tab.

Workspace here is a form of session grouping. In practice, it can be divided into production/development/testing, etc., to avoid operational errors.

Command History

Wave records all commands executed in the terminal, including the command content, terminal connection, execution time, and more.

In addition to searching commands on the history page, you can also summon history reminders in actual terminal sessions with hotkeys for quick access.

The history is recorded in the local App database at $HOME/.waveterm/waveterm.db.

Commands in the history can be summoned and executed in any terminal session. You can choose commands from the history of the current machine or any command from across machines.

File Edit

Wave is weak in file-related operations. The only support is to input codeedit filename in the terminal to invoke file editing. You can set it to split-screen or block display mode.
It does not support the lrzsz command for file upload/download, nor does it provide visual file management.

Others

The above are the core functions of Wave. Besides, Wave also provides some common features, such as AI and command completion.

Wave AI supports local AI models and cloud models (only supports OpenAI).

Usage:

Right-side AI chat entrance
/chat command in terminal sessions
AI icon in command blocks

Regarding command completion, I find it quite useless at the moment, so I won’t introduce it.

OK, that’s all for Wave’s basic functions. Now for my personal view.

Advantages and disadvantages

disadvantages

As stated in the Wave open-source project’s issues, there are many problems in actual use, such as ineffective connection configuration deletion, ineffective configuration editing, and failure to install remote shell on remote machines, etc. You will encounter many issues in actual use. However, since the Wave open-source project started on Jun 5, 2022, we need to give it more time to develop. Its version number is not yet v1.0. Since it’s an open-source project, you can contribute as well, be it through issues or PRs.

Advantages

The workspace organization is very innovative.
The terminal supports input commands to operate features, such as /chat for AI Q&A, and/codeedit for file editing.

At the end

Wave is still very immature. For users who frequently use terminals, I do not recommend using them because the issues are so many that they can hinder usage.
For infrequent users who can tolerate the issues, you can use it. After all, it is an open-source free terminal with Warp’s block display feature.

Accessing Google Cloud VMs from Your Local Terminal

Fri, 12 Jul 2024 23:42:23 +0800

I recently spent some time exploring Google’s Identity-Aware Proxy (IAP) and experimented with different ways to manage Google Cloud VMs from my local machine. Here’s a summary of the setup process for future reference.

1. Getting Started

To use GCP, you’ll need:

A Gmail account.
A Payment Method: You cannot create instances without a valid credit card on file.
- Note: Be careful with free credits. Even if your console shows a balance, these credits have an expiration date. Once they expire, you will be charged real money for any active resources.
- I used a standard Visa card, and the verification was straightforward.

2. Creating an Instance

GCP bills Compute Engine (VM) instances per second. However, since the rates are in USD, costs can escalate quickly if you aren’t careful. If you are just testing, remember to Delete (not just stop) your instance as soon as you are done.

Configuration Tip: After creation, you can edit the instance to disable its public IP for better security. You can also enable detailed logging, but keep in mind that log storage itself is a billable service.

3. Connecting to Your VM

GCP provides several browser-based connection methods, such as Cloud Shell and the integrated Web SSH client. However, for a better development experience, you’ll want to connect from your local terminal.

Method A: With a Public IP

If your instance has a public IP address and you’ve allowed SSH traffic (port 22) in the firewall rules, you can use standard SSH.

Method B: Without a Public IP (via IAP)

IAP (Identity-Aware Proxy) allows you to connect to VMs that do not have external IP addresses by tunneling through Google’s infrastructure.

Configure IAP Permissions: In the GCP Console, go to the IAP settings and grant the “IAP-secured Tunnel User” role to your Google account for the specific resource.
Firewall Rules: Ensure you have a firewall rule that allows ingress traffic from the IP range 35.235.240.0/20 on port 22. This is the range Google uses for IAP tunneling.

Install the Google Cloud SDK (gcloud CLI):

# Example for Linux/macOS
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz
tar -xf google-cloud-cli-linux-x86_64.tar.gz
./google-cloud-sdk/install.sh

Initialize the CLI:
```
gcloud init
```
Follow the prompts to log in via your browser and select your project and default region.

Connect via Tunnel: Once configured, use the following command to SSH into your private VM:

gcloud compute ssh <INSTANCE_NAME> \
 --zone "<ZONE>" \
 --tunnel-through-iap \
 --project "<PROJECT_ID>"

Final Thoughts

Connecting via IAP is a much more secure way to manage your cloud infrastructure, as it eliminates the need to expose port 22 to the entire internet. It takes a few minutes to set up, but the security benefits are well worth it. Happy tunneling!

Customizing Source Map Generation in Webpack

Sun, 30 Jun 2024 16:43:02 +0800

For production web releases, we enable Source Maps to trace errors back to source code via our RUM platform. Not every bundle needs a Source Map though. How can we customize which files get one?

Enable Source Maps

In Webpack, a simple configuration looks like this:

{
 ...
 devtool: 'source-map',
 ...
}

The downside is that every JS file will get a Source Map. Suppose you want to exclude certain files, e.g., lazily loaded third‑party modules like Monaco Editor. Webpack supports customizing Source Map generation.

Customize Source Maps

Make sure to disable devtool: 'source-map' (set it to false), otherwise the plugin config below won’t take effect.

 devtool: false,
 plugins: [
 new webpack.SourceMapDevToolPlugin({
 filename: '[file].map[query]',
 exclude: [/monaco_/],
 })
 ]

With this configuration, files whose names contain monaco_ will be excluded from Source Map generation.

Note: when bundling JS with content hashes in filenames, enabling Source Maps adds a //# sourceMappingURL=xxx.4ea8e146beed0e49c7c5.js.map comment at the end of the JS file, which changes the file content—and thus its content hash.

Final Thoughts

Done.

Feasibility of Specifying a Startup File When Opening an SSH2 Session

Sat, 29 Jun 2024 23:51:19 +0800

While reading the inshellisense code, I noticed it controls loading a startup file from a specific directory when spawning a local shell. That made me wonder: can an SSH2 web terminal session do something similar? Here’s a quick feasibility discussion.

inshellisense’s approach

Taking bash as an example:

shellArgs = ["--init-file", path.join(shellFolderPath, "shellIntegration.bash")];

this.#pty = pty.spawn(shellTarget, shellArgs ?? [], {
 name: "xterm-256color",
 cols,
 rows,
 cwd: process.cwd(),
 env: { ...convertToPtyEnv(shell, underTest, login), ...env },
 });

This works by passing shell-specific arguments as the second parameter to spawn; for bash, there is an --init-file option.

SSH2

https://github.com/mscdex/ssh2?tab=readme-ov-file#client-methods

There is no analogous parameter in the SSH2 connect method, so you can’t pass a startup file that way.

Two possible workarounds:

In an interactive session, run source to load your integration script. Downside: it will produce visible echo/output artifacts.
```
stream.write('');
```
Modify the shell’s startup file (e.g., .bashrc) to load your script by default. This avoids echo issues on subsequent connections.
```
conn.exec('');
```

Final Thoughts

Done.

OpenCloudOS SSH exec errors

Wed, 12 Jun 2024 23:04:12 +0800

WebShell SSH login to OpenCloudOS 9 disconnects immediately. After some investigation I found the root cause - here’s a summary.

WebShell uses nodejs-ssh2 to implement terminal login:

SSH connect opens an interactive shell for login.
After successful login, the underlying SSH connection is reused to open exec channels to run commands. Here, four commands were executed concurrently.

Error logs

With debug logs enabled, you’ll see something like this:

...
Inbound: CHANNEL_DATA (r:0, 57)
Inbound: CHANNEL_OPEN_CONFIRMATION (r:1, s:1)
Outbound: Sending CHANNEL_REQUEST (r:1, exec: env)
Inbound: CHANNEL_OPEN_CONFIRMATION (r:2, s:2)
Outbound: Sending CHANNEL_REQUEST (r:2, exec: curl https://1991421.cn)
Inbound: CHANNEL_OPEN_CONFIRMATION (r:3, s:3)
Outbound: Sending CHANNEL_REQUEST (r:3, exec: pwd)
Inbound: CHANNEL_OPEN_CONFIRMATION (r:4, s:4)
Outbound: Sending CHANNEL_REQUEST (r:4, exec: id)
Socket ended
Socket closed
/Users/alanhe/GitHub/express-demo/node_modules/ssh2/lib/client.js:1836
 cb(had_err !== true ? had_err : new Error('Unable to exec')); ^

As you can see, the connection drops directly, leading to the final error “Unable to exec”.

Analysis

If I disable command execution or keep only one command, it works.
The machine had 1 vCPU and 1 GB RAM. Upgrading to something like 8 GB removed the error.
Reinstalling OpenCloudOS 8 with the same config worked fine.
OpenCloudOS 9 uses OpenSSH v9.3, while OpenCloudOS 8 uses v8.x. Testing other images like Fedora 40 with OpenSSH v9.6 worked fine.

Therefore, I suspect v9 has some limit that causes the connection to drop when too many exec channels are opened. This does not appear to be a general OpenSSH 9.x compatibility issue.

Check server-side OpenSSH version

ssh -V

Fixes

Ideally OpenCloudOS 9 should fix this SSH issue - other systems don’t exhibit it.
Until the specific limit is identified, disable or avoid concurrent execs to work around it.

Final Thoughts

While I haven’t pinpointed exactly where the OS enforces this limit, the cause is clear enough. Running commands in parallel isn’t inherently wrong and shouldn’t be a problem, but don’t open too many channels - settings like MaxSessions will still cap things.

tar: Ignoring unknown extended header keyword

Tue, 11 Jun 2024 19:34:32 +0800

After creating a tar archive on macOS and extracting on CentOS/Linux, you may see: tar: Ignoring unknown extended header keyword LIBARCHIVE.xattr.com.apple.metadata:kMDItemTextContentLanguage. This is due to differences in macOS tar. Notes below.

Problem

On macOS, create the archive:

tar -czvf ../xxxx.tar.gz --exclude='.DS_Store' xxxx/*

On CentOS, extract:

tar -C xx/lib -xz

You’ll see output like:

tar: Ignoring unknown extended header keyword LIBARCHIVE.xattr.com.apple.metadata:kMDItemTextContentLanguage

Why

macOS uses BSD tar and writes xattr headers. CentOS commonly uses GNU tar.
The message is informational; extraction still works.

Fix

Install GNU tar on macOS: brew install gnu-tar, then create with gtar -czvf ../xxxx.tar.gz --exclude='.DS_Store' xxxx/*.

References

https://stackoverflow.com/questions/51655657/tar-ignoring-unknown-extended-header-keyword-libarchive-xattr-security-selinux

Detect CPU Architecture in Shell Scripts

Tue, 11 Jun 2024 18:27:47 +0800

While writing an installer for Code Server, I needed to identify the machine’s CPU architecture to fetch the right tarball.

Code Server Packages

Different architectures require different builds:

Script

uname reports the architecture:

arch() {
 uname_m=$(uname -m)
 case $uname_m in
 aarch64) echo arm64 ;;
 x86_64) echo amd64 ;;
 *) echo "$uname_m" ;;
 esac
}

ARCH=${ARCH:-$(arch)}

Once you know the architecture, downloading the matching package is trivial.

Cloud Server Architectures

Cloud providers (e.g., Tencent Cloud) display CPU architecture when you provision instances, so you can choose what you need up front:

Final Notes

That’s it—simple and effective.

Enable Autosuggestions in Your Shell

Mon, 10 Jun 2024 23:30:15 +0800

Some terminals show ghosted command suggestions as you type. Press → to accept them instantly—that feature is called autosuggestion.

Autosuggestion vs. Autocompletion

They’re different concepts.

Autosuggestion leverages history or heuristics to display a full command after the cursor. Press one key to accept it.
Autocompletion uses command metadata to offer options when you press a trigger key (usually Tab). It doesn’t fill the entire command—just the current argument—and often produces multiple candidates.

Both can coexist without conflict.

Enabling Autosuggestions

Each shell handles it differently.

Bash

No official community solution yet. Some terminals, like Warp, implement their own.

Zsh

Install via Oh My Zsh:

# Install Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Enable the zsh-autosuggestions plugin
plugins=(
 ...
 zsh-autosuggestions
)

Fish

Fish ships with autosuggestions enabled—no extra configuration required.

Final Thoughts

Turn on autosuggestions. Many commands repeat; accepting suggestions saves time and effort.

FileSaver Source Code Analysis

Sat, 08 Jun 2024 15:03:32 +0800

Web file download can use the mature library FileSaver.js, which is only 2KB after compression, so introducing it won’t be much of a size burden on the site. At the same time, we also need to understand the implementation of this package. Here we’ll organize the implementation logic.

saveAs API

First look at the parameters of the API method. You can see that you can directly pass in file data or URL.

FileSaver saveAs(Blob/File/Url, optional DOMString filename, optional Object { autoBom })

Processing Flow

Manipulate DOM to create an anchor element. Since the anchor element has no content set, it won’t appear on the current page.
Set the download attribute of the anchor element, with the value being the specified filename.
Set the rel value of the anchor element to noopener, which benefits performance and security.
Determine if the save storage is a string
1. If it’s a string, it will be treated as a URL. Then, based on whether it’s cross-origin, decide whether to use the anchor tag for direct download and save. If cross-origin, the download attribute won’t work, so XHR must be used to download data and then save as blob. If not cross-origin, the anchor tag can directly hang the URL and download to ensure download and save.
2. If it’s not a URL, the blob data is directly used as the href of the anchor element, and a.click() is triggered.

Download File Instead of Opening File

When we directly download files via URL, we’ll find that the browser will open the file by default. If we want to change this behavior, there are several ways:

For same-origin file downloads, just set the download attribute in the anchor tag method. The browser will treat it as setting Content-Disposition:attachment, so it will download as an attachment.
For non-same-origin file downloads, the download attribute won’t work, so you need to asynchronously download the file to get blob data, then construct an anchor tag to save, or have the server return with Content-Disposition:attachment set.

Prevent Memory Leaks

You can notice that after the anchor element’s href is bound to objectURL, it will use setTimeout and then execute click download, followed by delayed execution of URL.revokeObjectURL(a.href). This is mainly done to worry about memory leaks when files are too large, requiring manual memory cleanup.
Since the anchor element is not appended to document.body, there’s no manual deletion of the anchor element, so revoke is used here. If the anchor element were bound to document.body, this could actually be solved by deleting the element.

Final Thoughts

Done.

Security Component Scanning and Handling in Node Projects

Sun, 02 Jun 2024 12:37:04 +0800

The company has jobs that scan R&D projects daily. For Node projects, they promptly alert about component vulnerabilities in packages. When necessary, we need to handle them promptly, as security is no small matter. Here’s a summary of the approach.

Component vulnerabilities generally refer to npm package versions that have records in open-source vulnerability databases, meaning the community has already informed that this version has vulnerabilities, so it’s recommended to upgrade to certain versions.

When receiving such notifications, what needs to be done is to upgrade as soon as possible. Of course, actual operations can be divided into several situations:

Direct dependencies If the package is a direct dependency, then simply upgrade directly. Just note that if it’s a major version update, consider whether there are usage changes. If so, you need to adjust the calling approach. Of course, more importantly, you need to verify. If the impact is significant, reduce the release speed - safety first.
Indirect dependencies If the package is an indirect dependency, it’s a bit more troublesome. Priority is to find the direct dependency and upgrade it. If the direct dependency package doesn’t have a new version, you can use resolution to directly control the package version. Of course, here you also need to determine whether the version upgrade is a major version update and what the risk is for the fix release.

npm ls pkg

Here’s a small tip: using npm ls can quickly determine a package’s dependency tree structure in the project. Based on the version information provided in security reports, you can quickly determine whether it’s a direct or indirect dependency. Even if it’s indirect, you can clearly know which package introduced that version.

npm-check

Whether using npm-check or the built-in interactive update checking in yarn/pnpm, they are excellent ways to query version upgrade information. I recommend using them.

Final Thoughts

done. Security is no small matter. It’s recommended to carefully review each exposed security vulnerability, not just update a version number.

Ping Requests in the Browser Network Panel

Fri, 31 May 2024 00:14:27 +0800

Ping requests pop up in Chrome DevTools all the time. I wanted to know what triggers them and what they actually do, so here’s the breakdown.

`navigator.sendBeacon`

A little digging shows that those ping entries come from navigator.sendBeacon. The call can carry data, and under the hood it still issues an HTTP POST, so the server should treat it exactly like any other POST.

The browser sends the request asynchronously via navigator, not from the page’s single-threaded JavaScript context. Because of that, closing or navigating away from the page doesn’t interrupt it.

Example

When a page unloads, you can use sendBeacon to tell the server the user has closed the tab. With XHR or fetch, the page might disappear before the request ever leaves the browser, but sendBeacon finishes reliably.

Of course there are edge cases—if the browser crashes or the computer powers off, nothing gets sent.

Cross-Browser Display Differences

sendBeacon appears differently depending on the browser.

Chrome labels it as ping.
Safari labels it as beacon.
Firefox also labels it as beacon.

One annoyance in Chrome is that you can’t filter directly by the ping type in the Network tab—you have to choose “Other” or filter by URL.

How to Fire a Ping Request

Here’s a basic example:

navigator.sendBeacon('/beacon', new Blob([JSON.stringify({
 type: 'hello'
})], {type: 'application/json'}));

Use Cases

The behavior makes it ideal for analytics beacons, especially when you need to send data as the page is closing.

Analytics libraries in the wild often rely on sendBeacon for this exact purpose.

Final Thoughts

That’s everything I’ve gathered so far.

login shell

Wed, 15 May 2024 21:26:32 +0800

A WebShell user recently reported that logging into a Debian terminal wasn’t loading ~/.profile. After digging around, I found they were dropped into an interactive non-login shell, so the login-only configs never ran.

A login shell loads ~/.bash_profile, .profile, and /etc/profile. A non-login shell skips those but does source ~/.bashrc.

Profile Load Order

/etc/profile: the shell reads the global configuration first.
~/.bash_profile, ~/.bash_login, and ~/.profile (in that order): it stops at the first file that exists and is readable. If ~/.bash_profile is present, the shell doesn’t process the others; otherwise it falls back to the next.

File Contents Cleared When Writing via Stream

Sat, 27 Apr 2024 16:40:58 +0800

The ssh2-sftp-client provides a put method, which can accept a readable stream to continuously write data to a remote file. Recently encountered an issue where if the program terminates when the write stream just started, the file contents are cleared. Here we analyze the cause.

In the put method, localSrc can be a readable stream. remotePath is the file path on the remote server.

 async put(localSrc, remotePath, options) {
 try {
 if (typeof localSrc === 'string') {
 const localCheck = haveLocalAccess(localSrc);
 if (!localCheck.status) {
 throw this.fmtError(
 `Bad path: ${localSrc} ${localCheck.details}`,
 'put',
 localCheck.code,
 );
 }
 }
 return await this._put(localSrc, remotePath, options);
 } catch (e) {
 throw e.custom ? e : this.fmtError(`Re-thrown: ${e.message}`, 'put', e.code);
 }
 }

Based on the remote file path, sftp creates a writable stream, writeStreamOptions sets some configuration for the writable stream. The readable stream continuously reads and writes into the SFTP writable stream.

 _put(lPath, rPath, opts, addListeners = true) {
 let listeners, wtr, rdr;
 return new Promise((resolve, reject) => {
 if (addListeners) {
 listeners = addTempListeners(this, '_put', reject);
 }
 opts = {
 readStreamOptions: { ...opts?.readStreamOptions, autoClose: true },
 writeStreamOptions: { ...opts?.writeStreamOptions, autoClose: true },
 pipeOptions: { ...opts?.pipeOptions, end: true },
 };
 if (haveConnection(this, '_put', reject)) {
 wtr = this.sftp.createWriteStream(rPath, opts.writeStreamOptions);
 ...
 if (lPath instanceof Buffer) {
 this.debugMsg('put source is a buffer');
 wtr.end(lPath);
 } else {
 rdr =
 typeof lPath === 'string'
 ? fs.createReadStream(lPath, opts.readStreamOptions)
 : lPath;
 ...
 rdr.pipe(wtr, opts.pipeOptions);
 }
 }
 }).finally(() => {
 if (addListeners) {
 removeTempListeners(this, listeners, '_put');
 }
 });
 }

The SFTP writable stream is based on Node.js writable stream with inheritance modifications. If flag is not set, it defaults to w.

Check NodeJS official documentation: 'w': Open file for writing. The file is created (if it does not exist) or truncated (if it exists).

Now we can know the content is cleared because of this ‘w’. But how does SFTP get affected by this flag? Let’s continue.

function WriteStream(sftp, path, options) {
 ...
 WritableStream.call(this, options);

 this.path = path;
 this.flags = options.flags === undefined ? 'w' : options.flags;
 this.mode = options.mode === undefined ? 0o666 : options.mode;

 this.start = options.start;
 this.autoClose = options.autoClose === undefined ? true : options.autoClose;
 this.pos = 0;
 this.bytesWritten = 0;
 this.isClosed = false;

 this.handle = options.handle === undefined ? null : options.handle;
 this.sftp = sftp;
 this._opening = false;

 if (this.start !== undefined) {
 checkPosition(this.start, 'start');

 this.pos = this.start;
 }

 if (options.encoding)
 this.setDefaultEncoding(options.encoding);

 // Node v6.x only
 this.on('finish', function() {
 if (this._writableState.finalCalled)
 return;
 if (this.autoClose)
 this.destroy();
 });

 if (!Buffer.isBuffer(this.handle))
 this.open();
}

The first step of the write stream is to open the stream, and the flags parameter is passed during opening. In the sftp open method, stringToFlags(flags_) converts the stream’s flag into the SFTP protocol’s file opening flag value.

WriteStream.prototype.open = function() {
 if (this._opening)
 return;

 this._opening = true;

 this.sftp.open(this.path, this.flags, this.mode, (er, handle) => {
 this._opening = false;

 if (er) {
 this.emit('error', er);
 if (this.autoClose)
 this.destroy();
 return;
 }

 this.handle = handle;

 const tryAgain = (err) => {
 if (err) {
 // Try chmod() for sftp servers that may not support fchmod() for
 // whatever reason
 this.sftp.chmod(this.path, this.mode, (err_) => tryAgain());
 return;
 }

 // SFTPv3 requires absolute offsets, no matter the open flag used
 if (this.flags[0] === 'a') {
 const tryStat = (err, st) => {
 if (err) {
 // Try stat() for sftp servers that may not support fstat() for
 // whatever reason
 this.sftp.stat(this.path, (err_, st_) => {
 if (err_) {
 this.destroy();
 this.emit('error', err);
 return;
 }
 tryStat(null, st_);
 });
 return;
 }

 this.pos = st.size;
 this.emit('open', handle);
 this.emit('ready');
 };

 this.sftp.fstat(handle, tryStat);
 return;
 }

 this.emit('open', handle);
 this.emit('ready');
 };

 this.sftp.fchmod(handle, this.mode, tryAgain);
 });
}

 open(path, flags_, attrs, cb) {
 if (this.server)
 throw new Error('Client-only method called in server mode');

 if (typeof attrs === 'function') {
 cb = attrs;
 attrs = undefined;
 }

 const flags = (typeof flags_ === 'number' ? flags_ : stringToFlags(flags_));
 if (flags === null)
 throw new Error(`Unknown flags string: ${flags_}`);

 let attrsFlags = 0;
 let attrsLen = 0;
 if (typeof attrs === 'string' || typeof attrs === 'number')
 attrs = { mode: attrs };
 if (typeof attrs === 'object' && attrs !== null) {
 attrs = attrsToBytes(attrs);
 attrsFlags = attrs.flags;
 attrsLen = attrs.nb;
 }

 /*
 uint32 id
 string filename
 uint32 pflags
 ATTRS attrs
 */
 const pathLen = Buffer.byteLength(path);
 let p = 9;
 const buf = Buffer.allocUnsafe(4 + 1 + 4 + 4 + pathLen + 4 + 4 + attrsLen);

 writeUInt32BE(buf, buf.length - 4, 0);
 buf[4] = REQUEST.OPEN;
 const reqid = this._writeReqid = (this._writeReqid + 1) & MAX_REQID;
 writeUInt32BE(buf, reqid, 5);

 writeUInt32BE(buf, pathLen, p);
 buf.utf8Write(path, p += 4, pathLen);
 writeUInt32BE(buf, flags, p += pathLen);
 writeUInt32BE(buf, attrsFlags, p += 4);
 if (attrsLen) {
 p += 4;

 if (attrsLen === ATTRS_BUF.length)
 buf.set(ATTRS_BUF, p);
 else
 bufferCopy(ATTRS_BUF, buf, 0, attrsLen, p);

 p += attrsLen;
 }
 this._requests[reqid] = { cb };

 const isBuffered = sendOrBuffer(this, buf);
 this._debug && this._debug(
 `SFTP: Outbound: ${isBuffered ? 'Buffered' : 'Sending'} OPEN`
 );
 }

const stringFlagMap = {
 'r': OPEN_MODE.READ,
 'r+': OPEN_MODE.READ | OPEN_MODE.WRITE,
 'w': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.WRITE,
 'wx': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.WRITE | OPEN_MODE.EXCL,
 'xw': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.WRITE | OPEN_MODE.EXCL,
 'w+': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE,
 'wx+': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE
 | OPEN_MODE.EXCL,
 'xw+': OPEN_MODE.TRUNC | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE
 | OPEN_MODE.EXCL,
 'a': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.WRITE,
 'ax': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.WRITE | OPEN_MODE.EXCL,
 'xa': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.WRITE | OPEN_MODE.EXCL,
 'a+': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE,
 'ax+': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE
 | OPEN_MODE.EXCL,
 'xa+': OPEN_MODE.APPEND | OPEN_MODE.CREAT | OPEN_MODE.READ | OPEN_MODE.WRITE
 | OPEN_MODE.EXCL
};

Now we understand why it becomes empty: when uploading a file, if the original file exists, it actually truncates first.

So how to avoid this problem?

The solution is to first upload to a temporary directory when using sftp upload, then mv rename to the original file for safety.

parseInt

Mon, 22 Apr 2024 23:37:56 +0800

Today I saw a parseInt question on our company’s internal platform, and the result was surprising. The root cause was unclear understanding of parseInt execution, so I’m documenting it here.

Problem

parseInt('0xf',16)
// 15

parseInt('0xf')
// 15

parseInt(0xf,16)
// 21

parseInt(15,16)
// 21

Explanation

The first parameter of parseInt starts from the first non-whitespace character. For non-string values, it performs ToString conversion, so parseInt(15,16) is essentially parseInt(‘15’,16).
parseInt(‘0xf’,16) - JavaScript recognizes the string as a hexadecimal number, and the radix is also hexadecimal, so it directly parses to 15. parseInt(‘0xf’) doesn’t pass a radix, but based on the 0x prefix in the string, it’s still recognized as hexadecimal, so it’s still 15.

Interview Question

Understanding the processing logic, let’s analyze this code:

['1', '2', '3'].map(parseInt)

The callback logic for the above program is as follows:

parseInt(1,0); // 1

parseInt(2,1); // NaN

parseInt(3,2); // NaN

radix 0 is equivalent to base 10. radix 1 results in NaN. Base 2 cannot have 3, so it results in NaN.

Personally, I don’t think memorizing these processing logic has much value. The real valuable points are:

Pay attention to automatic type conversion - there are many such issues in JavaScript.
Be careful with callback writing like map(parseInt) to avoid accidentally passing the index and causing unexpected results.

Serverless via Tencent Cloud Functions Explained (Simple Guide)

Sat, 20 Apr 2024 22:48:20 +0800

I’ve used Tencent Cloud Functions a few times now. They’re basically Tencent’s serverless offering. Documenting the scenarios helped me internalize what “serverless” really means.

Use case 1: lightweight middleware for a mini program

A WeChat mini program needed a small middle tier—mostly proxying calls to a larger backend and performing simple DB lookups. Spinning up my own server felt wasteful, so I deployed a cloud function instead. Zero ops overhead.

Use case 2: sandboxed AI scripting

Users can write scripts to customize AI chat behavior. Inputs/outputs are standardized, but the actual logic runs on our platform. I first considered Web Workers, but domestic AI providers often block cross-origin requests. Running scripts inside the main backend introduces security risk. Cloud Functions offered a sandboxed environment with server-side network access—perfect.

Use case 3: quick proxy service

I needed a small proxy. Buying a server means dealing with hardware specs, domains, and maintenance. With Cloud Functions I just upload the proxy code. No domain needed, scaling is automatic, and logging is configurable with minimal effort.

So…what is serverless?

Re-reading the definition after real-world use makes it click:

Serverless is a cloud-native development model that lets developers build and run applications without managing servers. Servers still exist, but the cloud provider handles maintenance, updates, scaling, and other undifferentiated heavy lifting. Developers package code, deploy it, and let the provider’s elasticity do the rest.

Final Thoughts

Buying a VPS puts you at the machine-granularity level—you manage everything. Serverless moves the abstraction down to individual functions. With Cloud Functions you focus entirely on application logic and ignore infrastructure.

References

https://aws.amazon.com/cn/campaigns/serverless/

How to Use SSE in AI Chat (Step-by-Step Guide)

Sat, 13 Apr 2024 14:54:45 +0800

ChatGPT has been popular for a year now。It has also driven the use of SSE.

Here, I summarize my understanding of it.

Advantages of SSE

Uses the standard HTTP protocol, and not WebSocket. Relative to WebSocket, it has a smaller resource overhead.
SSE transmits text data with simple overhead.

How to Use

EventSource

const evtSource = new EventSource("sse.php");
evtSource.onmessage = (e) => {
 console.log(`message: ${e.data}`);
};

Fetch

fetch('/api/openai/stream', {
 method: 'post',
 headers: {
 'Content-Type': 'application/json;charset=utf-8',
 },
 body: JSON.stringify({
 messages
 })
 }).then(res => {
 const reader = res.body.getReader();
 let buffer = '';
 const readChunk = () => {
 reader.read()
 .then(({
 value,
 done
 }) => {
 if (done) {
 console.log('Stream finished');
 return;
 }

 const chunkString = new TextDecoder().decode(value);
 buffer += chunkString;

 let position;
 while ((position = buffer.indexOf('\n\n')) !== -1) {
 const completeMessage = buffer.slice(0, position);
 buffer = buffer.slice(position + 2);
 completeMessage.split('\n').forEach(line => {
 if (line.startsWith('data:')) {
 const jsonText = line.slice(5).trim();
 if (jsonText === '[DONE]') {
 console.log('done');
 return;
 }
 try {
 const dataObject = JSON.parse(jsonText);
 console.log(dataObject);
 } catch (error) {
 console.error('JSON parse error:', error, jsonText);
 }
 }
 });
 }
 readChunk();
 })
 .catch(error => {
 console.error(error);
 });
 };
 readChunk();
 })

Fetch vs EventSource

Both have roughly the same compatibility.
A disadvantage of EventSource is that it cannot send a request body, so it typically requires setting up a request to send messages first, then initiating EventSource. Fetch, like XHR, can carry a request body. Thus, I think Fetch is the better choice.

ChatGPT’s Effect

ChatGPT has long supported stream returns, which give users the effect of a typewriter. Here is how GPT does it:

ChatGPT uses Fetch, send request body, and the return type is text/event-stream; charset=utf-8, meaning the server continuously returns response chunk until it ends.

You can find requests can be found in the network, and the request url is https://chat.openai.com/backend-api/conversation

done.

attachCustomKeyEventHandler in xterm.js

Sat, 13 Apr 2024 11:48:29 +0800

To handle special key behavior in xterm.js, use attachCustomKeyEventHandler. Here’s how it works.

Source Walkthrough

/**
 * Attaches a custom key event handler which is run before keys are
 * processed, giving consumers of xterm.js ultimate control as to what keys
 * should be processed by the terminal and what keys should not.
 * @param customKeyEventHandler The custom KeyboardEvent handler to attach.
 * This is a function that takes a KeyboardEvent, allowing consumers to stop
 * propagation and/or prevent the default action. The function returns
 * whether the event should be processed by xterm.js.
 *
 * @example A custom keymap that overrides the backspace key
 * ```ts
 * const keymap = [
 * { "key": "Backspace", "shiftKey": false, "mapCode": 8 },
 * { "key": "Backspace", "shiftKey": true, "mapCode": 127 }
 * ];
 * term.attachCustomKeyEventHandler(ev => {
 * if (ev.type === 'keydown') {
 * for (let i in keymap) {
 * if (keymap[i].key == ev.key && keymap[i].shiftKey == ev.shiftKey) {
 * socket.send(String.fromCharCode(keymap[i].mapCode));
 * return false;
 * }
 * }
 * }
 * });
 * ```
 */
attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;

Source location

 protected _keyDown(event: KeyboardEvent): boolean | undefined {
 this._keyDownHandled = false;
 this._keyDownSeen = true;

 if (this._customKeyEventHandler && this._customKeyEventHandler(event) === false) {
 return false;
 }
 ...
 }
 protected _keyUp(ev: KeyboardEvent): void {
 this._keyDownSeen = false;

 if (this._customKeyEventHandler && this._customKeyEventHandler(ev) === false) {
 return;
 }
 ...
 }
 protected _keyPress(ev: KeyboardEvent): boolean {
 let key;

 this._keyPressHandled = false;

 if (this._keyDownHandled) {
 return false;
 }

 if (this._customKeyEventHandler && this._customKeyEventHandler(ev) === false) {
 return false;
 }
 ...
 }

Source location

From the above we can see:

The callback provided to attachCustomKeyEventHandler runs before xterm.js processes keys. It fires on keydown/keyup/keypress. Returning void or true has the same effect; only returning false prevents xterm.js from further processing the key event.

Example

Suppose I want `Ctrl + `` in xterm.js to trigger a special action (e.g., invoke AI). Do this:

term.attachCustomKeyEventHandler((event)=>{
 if (event.type==='keydown'&&'`' === event.key && event.ctrlKey) {
 // dosomething
 return false;
 }
});

If you still want xterm.js to process the key after your handler, return void or true.

Done.

Loading ES Modules in Node.js Projects

Wed, 10 Apr 2024 08:24:01 +0800

Node.js supports ES module import. You can load ES modules through import, but there are some conditions. If not met, it will still throw errors.

Note: import in Node.js differs from the browser side.

Import Local JS Modules

Declare type:module in the package.json of the folder where the js file is located
File extension should be mjs

Import URL

Executing import(url) in Node throws error ERR_UNSUPPORTED_ESM_URL_SCHEME

Error code explanation:

import with URL schemes other than file and data is unsupported.

From this, we can know that dynamic import in Node.js doesn’t support URLs. However, for example, Deno does support URLs, but Deno doesn’t consider CommonJS and doesn’t have this historical baggage.

What is Shebang? A Guide for Scripting

Tue, 02 Apr 2024 23:38:50 +0800

You’ve probably seen shell scripts starting with #!/bin/sh. For a long time, I noticed that some scripts ran fine without it, while others failed. It wasn’t until I started developing Alfred Workflows that I realized this line has a specific name and purpose: it’s called a Shebang.

What is a Shebang?

The Syntax: A Shebang consists of the characters #!. For it to work, these must be the very first two characters on the first line of the file.
The Mechanism: When a Unix-like operating system (like macOS or Linux) encounters a file with a Shebang, the program loader parses the rest of the line as an interpreter directive. It then executes that interpreter and passes the script’s file path as an argument.
Execution vs. Interpretation: Without a Shebang, a script cannot be executed directly (e.g., ./script.sh). However, it can still be run if you manually pass it to an interpreter (e.g., bash script.sh).

Common Examples

#!/bin/sh: Executes the script using sh (Bourne shell or a compatible replacement).
#!/bin/bash: Specifically uses the bash shell, which often contains features not found in standard sh.
#!/usr/bin/env node: Executes the script using Node.js. By using /usr/bin/env, the system looks for node in the user’s current $PATH, which is more portable than hardcoding an absolute path like /usr/local/bin/node.

Node.js Script Example

Consider this simple Node.js script:

#!/usr/bin/env node

console.log(
 JSON.stringify({
 response: "Hello from Node!",
 environment: process.env.USER
 })
);

If you save this as test.js and give it execution permissions (chmod +x test.js), you can run it directly in your terminal with ./test.js. If you were to remove the first line, the system wouldn’t know which program to use to run the code, and the execution would fail unless you typed node test.js.

Final Thoughts

Using a Shebang is a best practice for writing portable scripts. It ensures that your scripts run correctly regardless of how they are invoked or which default shell the user is running.

References

Shebang (Unix) - Wikipedia

Reading Large Files with FileReader

Sun, 31 Mar 2024 22:15:36 +0800

The frontend can read file content with FileReader, but reading large files (1-3 GB) causes noticeable jank. Here are the optimizations.

Cause of jank

If you read the entire file at once, all content is loaded into browser memory, which causes jank.

Solution

Slice the file and read chunks asynchronously.

const chunkSize = 1 * 1024 * 1024; // 1MB
 function readChunk(file, start, chunkSize) {
 const reader = new FileReader();
 return new Promise(resolve => {
 reader.onload = (evt) => {
 // console.log(evt.target.result);
 resolve(evt.target.result);
 };
 reader.readAsArrayBuffer(file.slice(start, Math.min(start + chunkSize, file.size)));
 })
 }

Comparison

Using 2.3 GB data as an example:

Using FileReader.readAsArrayBuffer to read in 1 MB chunks, the time cost is below
Using FileReader.readAsArrayBuffer to read the full file, it never finishes

Using 1.98 GB data as an example:

Chunked reading

Full read

Conclusion

Chunked reading saves performance and reads specific parts faster, though total time is not necessarily shorter. The larger the file, the bigger the gap.
Reading files larger than 2 GB in one shot can be problematic in browsers.

Extension

When handling binary files on the frontend, you often run into Blob and ArrayBuffer. If you only need to slice data, Blob is recommended. Blob is just a view of the original data and does not load it, so for uploads you can slice the file and send chunks directly to the server. But if you need to read or modify file contents in the frontend, ArrayBuffer is recommended.

Common PowerShell Commands

Sun, 31 Mar 2024 11:38:26 +0800

Recently, WebShell needed to support file management under PowerShell. To perform file-related operations, it’s necessary to understand the relevant commands. Here’s the summary.

Compress Folder

Compress-Archive -Path '${formatted}' -DestinationPath '${zipTempPath}'

Copy File/Folder

Copy-Item -Path '${filePath}' -Destination '${dirPath}' -Recurse -Force

Move File/Folder

Move-Item -Path '${filePath}' -Destination '${targetPath}' -Force

Extract ZIP Archive

Expand-Archive -Path '${path}.zip' -DestinationPath '${destinationPath}';Remove-Item -Path '${path}.zip' -Force

Delete File/Folder

Remove-Item -Path '${formatted}' -Recurse -Force

Create Folder

New-Item -Path '${formatted}' -ItemType Directory

Rename

Rename-Item -Path '${formatted}' -NewName '${newName}'

Multiple Command Execution

If need to execute multiple commands, unlike using && in Linux, PowerShell requires ;.

Move-Item -Path '${path}' -Destination '${path}.zip';Expand-Archive -Path '${path}.zip' -DestinationPath '${destinationPath}';Remove-Item -Path '${path}.zip' -Force

Common Issues

w2: Cannot load file C:\Program Files\node js\w2.ps1 because running scripts is disabled on this system.

# Run PowerShell as administrator

# Check the current PowerShell script execution policy
get-ExecutionPolicy
# Set PowerShell's execution policy to RemoteSigned
set-executionpolicy remotesigned

Path Contains Square Brackets []

If the path contains [], for example, executing Move-Item doesn’t throw an error but the execution is unsuccessful. The reason is that [] in the path is treated as regex, regardless of whether it’s a single or double quote. There are two solutions:

Escape []

For example:

Move-Item -Path 'C:\\Windows\\Temp\\`[漫威`] xxx.jar_1717312576427' -Destination 'C:\\Windows\\system32\\config\\systemprofile\\`[漫威`] xxx.jar' -Force

Change -Path to -LiteralPath

Move-Item -LiteralPath 'C:\\Windows\\system32\\config\\systemprofile\\123 456\\[漫威] xxx.jar' -Destination 'C:\\Windows\\system32\\config\\systemprofile\\789\\[漫威] xxx.jar' -Force

Final Thoughts

When executing Windows commands, you can choose between PowerShell and CMD. According to Microsoft’s recommendation, using PowerShell is advised, as CMD has entered the maintenance phase.

Documentation

https://stackoverflow.com/questions/21008180/copy-file-with-square-brackets-in-the-filename-and-use-wildcard

Writing a Welcome Message in xterm.js

Fri, 29 Mar 2024 09:41:29 +0800

Terminals often display a welcome message on login. How do you change it? While building a WebShell recently, I considered how to implement this.

Server‑side configuration

The most direct way is server configuration — for example, add echo 'hello world' to bashrc so it prints after WebShell login.

Server‑side drawbacks:

Adding a welcome line affects all terminal logins, not just WebShell.
It requires modifying server config (e.g., editing bashrc), which is heavier.

xterm.js client‑side approach

Alternatively, implement it on the client with xterm.js. After the terminal connects, run:

term.write("\x1B[34;43mmy github is https://github.com/alanhe421 my github is https://github.com/alanhe421 my github is https://github.com/alanhe421 my github is https://github.com/alanhe421\x1B[0m"

 + '\r\n', () => {
 webshell.sendData('resize', {
 rows: term.rows,
 cols: term.cols,
 });
 });

Explanation:

term.write writes directly to the terminal emulator; it is not echoed back from the server.
Since the server didn’t send this content, it doesn’t know the terminal size. Send rows/cols to avoid misaligned output in subsequent interactions.

Terminal URL Scheme Support

Thu, 21 Mar 2024 23:45:19 +0800

Both macOS and Windows ship with terminal apps. If they support URL schemes, you can start an SSH session from a hyperlink. Here’s what works today.

URL Schemes

macOS

ssh://<username>@<host>:<port>

Click to test

By default this opens Terminal, but you can remap it to iTerm2 or another terminal app via settings.

Windows

No built-in support. You can configure PuTTY or other tools to handle ssh:// (e.g., https://gist.github.com/sbiffi/11256316).

Windows does have other built-in schemes, such as launching the Store to a product page: test link. Also note that Windows 11 ships with Windows Terminal preinstalled; older versions require manual installation.

Final Thoughts

It’d be great if Windows added native terminal URL handling—macOS has a clear edge here.

Submitting PRs to GitHub Open Source Projects

Sun, 17 Mar 2024 12:28:32 +0800

Working on your own projects on GitHub is relatively simple, but how to collaborate and contribute to open source projects is more interesting. Here I’m documenting the experience I’ve accumulated contributing to open source projects like inshellisense.

Using the inshellisense project as an example

Fork the open source project, microsoft/inshellisense => alanhg/inshellisense
Create a new branch, such as fix/file-template, for development
- Update unit tests if available, ensure tests pass
- Don’t use the main branch directly because the main branch is used to sync project updates, avoiding situations where the original project gets new commits during development
- Creating a new branch also allows better use of branch names to indicate whether the changes are features, fixes, etc.
Commit to the upstream repository alanhg/inshellisense
If the open source project microsoft/inshellisense has updates, pull the updates using Sync fork
Rebase the fix/file-template branch with the main branch to ensure it’s up to date
Push again to the upstream repository alanhg/inshellisense
Initiate a Pull Request, describe the changes in detail, and wait for merging
- If there are any issues during PR review, provide active feedback and resolve them
Once successfully merged, celebrate 🎉
You can delete the fix/file-template branch, switch to the main branch, and if there are new contributions to make, repeat step 5 for operation

Debugging Local Packages with Pnpm and Vite: Common Issues and Solutions

Sun, 03 Mar 2024 23:37:54 +0800

When developing with Pnpm + Vite, during local package debugging, Vite may still load the old version of the package. This article analyzes and resolves this issue.

Local Package Debugging Steps

Since the package manager is pnpm, the corresponding debugging package mounting steps are as follows:

Execute pnpm link --global in the local package
Execute pnpm link pkgname --global in the target project

After performing these steps, accessing the web browser will reproduce the issue of incorrect package versions.

Let’s first analyze the situation in vite/pnpm

.vite

When Vite builds a project, it creates a .vite folder under node_modules

The .vite cache requires changes in any of the following conditions:

Package manager lockfile content, e.g. package-lock.json, yarn.lock, pnpm-lock.yaml or bun.lockb.
Patches folder modification time.
Relevant fields in your vite.config.js, if present.
NODE_ENV value.

To force a refresh in Vite, you need to use --force or delete the .vite directory. For more details, see the official documentation

When executing pnpm link, you’ll notice that the lock file doesn’t change, so the .vite cache won’t be updated.

.pnpm Directory

Packages in node_modules are soft-linked to the .pnpm folder. When executing pnpm link:

The lock file won’t change
The corresponding package in node_modules will be soft-linked to the globally linked package

Problem Analysis

In summary, the issue is that after pnpm link, the lock file doesn’t get updated. Although the package dependency links change (meaning the content changes), Vite is unaware of this. Therefore, the Vite cache needs to be manually refreshed. Manually deleting the .vite directory and restarting Vite will show that the correct content is loaded.

SourceMap

SourceMap is designed to facilitate debugging with source code, such as being able to search for source files in Chrome Network. The reason it can be retrieved is that when the browser has Network open, it attempts to load the corresponding map file based on the sourcemap address noted in the code file. The map file records the location of the source files, and then the source code files are loaded. If you can’t retrieve source code files in Chrome, you can check whether the map files and source files are being loaded successfully with the correct paths.

SourceMap Not Working When Debugging Webpack Packages in Vite

The reason is that the sourcemap generated by Webpack uses the webpack protocol for source files, which Vite doesn’t support. One solution is to switch to Vite for building.

![image-20240305231617186](/Users/alanhe/Library/Mobile Documents/com~~apple~~CloudDocs/Typora/image-20240305231617186.png)

{"version":3,"file":"index.js","mappings":"AAAA","sources":["webpack://laputarenderer/webpack/universalModuleDefinition"],"sourcesContent":["(function webpackUniversalModuleDefinition(root, factory) {\n\tif(typeof exports === 'object' && typeof module === 'object')\n\t\tmodule.exports = factory(require(\"react\"));\n\telse if(typeof define === 'function' && define.amd)\n\t\tdefine([\"react\"], factory);\n\telse if(typeof exports === 'object')\n\t\texports[\"laputarenderer\"] = factory(require(\"react\"));\n\telse\n\t\troot[\"laputarenderer\"] = factory(root[\"React\"]);\n})(self, (__WEBPACK_EXTERNAL_MODULE__12__) => {\nreturn "],"names":[],"sourceRoot":""}

Final Thoughts

Debugging local packages with Pnpm and Vite can be challenging due to caching mechanisms. The key insight is understanding that Vite’s dependency pre-bundling relies on lockfile changes to invalidate its cache. When using pnpm link, the lockfile remains unchanged, causing Vite to continue using cached versions of packages. The solution is to manually clear the Vite cache by deleting the .vite directory or using the --force flag when restarting the development server. This approach ensures that your local package changes are properly reflected during development.

JavaScript String trim() Method

Sat, 02 Mar 2024 22:25:08 +0800

String objects have a trim method, but trim doesn’t just handle leading and trailing spaces. I recently discovered I had a misconception about this when using it, so I’m making a note here.

According to the MDN introduction, trim handles whitespace + line terminators at the beginning and end:

A new string representing str stripped of whitespace from both its beginning and end. Whitespace is defined as white space characters plus line terminators.

Space is just one type of white space. So what specific characters are included?

White space


Code point	Name	Abbreviation	Description	Escape sequence
U+0009	Character tabulation		Horizontal tabulation	\t
U+000B	Line tabulation		Vertical tabulation	\v
U+000C	Form feed		Page breaking control character (Wikipedia).	\f
U+0020	Space		Normal space
U+00A0	No-break space		Normal space, but no point at which a line may break
U+FEFF	Zero-width no-break space		When not at the start of a script, the BOM marker is a normal whitespace character.
Others	Other Unicode space characters		Characters in the “Space_Separator” general category

Line terminators


Code point	Name	Abbreviation	Description	Escape sequence
U+000A	Line Feed		New line character in UNIX systems.	\n
U+000D	Carriage Return		New line character in Commodore and early Mac systems.	\r
U+2028	Line Separator		Wikipedia
U+2029	Paragraph Separator		Wikipedia

So strings containing any of the above characters at the beginning or end will have them removed after trim().

Examples

Let’s test a few characters:

console.log('\r123\r'.trim().length) // 3
console.log('\n123\n'.trim().length) // 3
console.log(' \n123\n'.trim().length) // 3

Handling Only Spaces

console.log(' \n123\n'.replace(/^\x20+|\x20+$/g,'').length)

Conclusion

I discovered this issue because in my program, a string was assigned the value \r, and after str.trim() it became an empty string, which didn’t meet expectations. This prompted me to revisit the trim logic and realize my understanding was incorrect.

How to Use HTTP3 (Step-by-Step Guide)

Sat, 02 Mar 2024 16:57:17 +0800

Recently switched my blog server from Nginx to Caddy, and since Caddy supports HTTP3, I decided to try upgrading to HTTP3.

Note: On June 6, 2022, Robin Mark, a member of the IETF QUIC and HTTP working groups, announced on Twitter that after 5 years, HTTP/3 has finally been standardized as RFC 9114, making it the third major version of the HTTP hypertext transfer protocol.

Configuration

Caddy

{
 servers {
 protocols h1 h2 h2c h3
 }
}

Execute the command to check port status: netstat -tulpn | grep caddy

UDP ports do not require listening

Port Opening

Ensure the firewall allows port 443/UDP

Client/Browser/Chrome

In addition to server-side support, the client also needs to ensure it’s enabled. For Chrome, newer versions like v122.0.6261.69 have QUIC support enabled by default.

To confirm the enabled status, check: chrome://flags/#enable-quic

Testing if a Site Supports HTTP3

https://http3check.net/

Execute the command:

docker run --rm ymuski/curl-http3 curl -IL --http3 https://1991421.cn

Final Thoughts

HTTP3 represents a significant advancement in web protocols, offering improved performance and reliability over previous HTTP versions. The transition from TCP to QUIC as the underlying transport protocol brings benefits like reduced connection establishment time, improved multiplexing, and better performance on lossy networks. While adoption is still growing, enabling HTTP3 on your server can provide a better experience for users with compatible browsers and clients.

$TERM Explained (Simple Guide)

Sun, 25 Feb 2024 10:15:03 +0800

While building a WebShell I kept seeing scripts reference $TERM. Here’s a quick primer on what it does and why it matters.

What Is $TERM?

$TERM is an environment variable in Unix-like shells that defines the terminal type. It tells programs what capabilities (colors, cursor control, etc.) to expect.

Common values include:

xterm
xterm-color
xterm-256color
vt220
vt100
dumb
linux

Interactive SSH sessions usually report xterm-256color; non-interactive sessions often report dumb or nothing at all, which is why those sessions lack color.

Setting the Value

You can set $TERM in shell startup files (~/.bashrc, ~/.bash_profile, etc.).
SSH clients set it when opening sessions. For instance, the ssh2 client library lets you configure pseudo-TTY settings.

Quick Test

On Ubuntu, changing $TERM in .bashrc to vt100 removes color; xterm-256color restores it.

Takeaway

You usually don’t need to set $TERM manually—terminal emulators handle it. But now you know what it does if you ever need to override it.

References

How to Use GitHub Copilot CLI (Step-by-Step Guide)

Thu, 08 Feb 2024 23:09:45 +0800

Copilot CLI is now in public beta. I hadn’t tried it before, but now I’ve given it a shot. Here’s how to use it and my thoughts on it.

Current CLI version: version 0.5.4-beta (2024-01-04)

Requirements

Like GitHub Copilot, requires a paid subscription

Installation

# Install GitHub CLI
brew install gh

# Update GitHub CLI
brew upgrade gh

# Login to GitHub
gh auth login

# Install copilot
gh extension install github/gh-copilot

After the above installation, you can use it normally

Usage

Currently, the CLI functionality is quite simple:

Explain commands
```
gh copilot explain "git push"
```
Suggest commands
```
gh copilot suggest "install git"
```

Currently, you cannot set custom prompts, so the returned results will be in English, but command prompts can be described in Chinese since the underlying OpenAI supports multiple languages

That’s all there is to the CLI functionality. Looking forward to continued CLI updates, such as supporting system prompts or supporting chat rather than being limited to commands.

https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli

Great Plugins for Hexo

Thu, 08 Feb 2024 10:43:35 +0800

I’m still using Hexo for my blog. The following are the hexo plugins I used.

Note: The configuration file is _config.yml

hexo-abbrlink

permalink: :year/:month/:day/:abbrlink/

hexo-algoliasearch

Article search and free quota are enough for me.

# https://github.com/LouisBarranqueiro/hexo-algoliasearch
algolia:
 appId:
 applicationID:
 apiKey:
 adminApiKey:
 chunkSize: 5000
 indexName: my_blog
 fields:
 - content:strip:truncate,0,200
 - title
 - permalink
 - tags

hexo-excerpt

Automatic excerpt

# https://github.com/chekun/hexo-excerpt
excerpt:
 depth: 5
 excerpt_excludes: ['img']
 more_excludes: []
 hideWholePostExcerpts: true

hexo-generator-archive

Archive page generation

# https://github.com/hexojs/hexo-generator-archive
archive_generator:
 enabled: true
 per_page: 10
 yearly: true
 monthly: false
 daily: false
 order_by: -date

hexo-generator-feed

Generate feed.xml subscription link, serving RSS

# https://github.com/hexojs/hexo-generator-feed
feed:
 type: atom
 path: atom.xml
 limit: 20
 hub:
 content:
 content_limit: 140
 content_limit_delim: ' '

hexo-generator-sitemap

Generate site XML, it’s useful for SEO

# Generate sitemap.
# https://github.com/hexojs/hexo-generator-sitemap
sitemap:
 path: sitemap.xml

hexo-generator-tag

Generate tag label page

# https://github.com/hexojs/hexo-generator-tag
tag_generator:
 per_page: 10
 order_by: -date

hexo-symbols-count-time

Generate article statistics, such as word count, estimated reading time, etc.

# @see https://github.com/theme-next/hexo-symbols-count-time
symbols_count_time:
 symbols: true
 time: true
 total_symbols: true
 total_time: true
 exclude_codeblock: false
 awl: 2
 wpm: 300

hexo-theme-next

Site theme, I prefer theme-next, mainly because it has quite rich configurations

# https://github.com/next-theme/hexo-theme-next
theme: next

Write at the end

Hexo is still in an active state, don’t worry about it.
The main focus of blog maintenance is still on content, currently, Hexo is enough.

An Introduction to the ssh2 Package

Sun, 14 Jan 2024 10:31:13 +0800

When building a WebShell, the ssh2 package often comes in handy. Here’s a brief guide to using it.

Note: The ssh2 module is a Node.js client implementation of the OpenSSH protocol.

Common APIs

Client
1. connect — establish a connection
Supports password/key/keyboard-interactive auth. Once connected, you can perform basic operations.

If connection fails, enable debug logs to troubleshoot. In general, if your local terminal can connect, ssh2 can as well—they are both OpenSSH clients.
1. con.shell
Open an interactive shell, just like a normal terminal session with continuous input/output. You can disconnect in various ways (disconnect, idle timeout, typing exit, etc.).
1. con.exec
Execute a single command (e.g., cd). After execution completes, the stream ends (stream.end).
httpAgent

The agent enables tunneling into internal networks. For example, if the target machine hosts a web service on 127.0.0.1:80, you can reach it through an SSH-established agent.
sftp

For file operations, I recommend the ssh2-sftp-client package built on top of ssh2.
Server

Create an SSH server.

When using ssh2, you’ll come across the concept of Channels — here’s a note on that.

Channel

A connect call establishes a single SSH connection, which runs over TCP. Since TCP supports multiplexing, ssh2 can run different operations over the same SSH connection.

Interactive shell, SFTP, and exec commands each open a separate channel; they are isolated from one another. For example, if you sudo in an interactive shell, SFTP/exec channels are unaware. You can choose to reuse one SSH connection (multiple channels) or not — using different Client instances creates separate connections.

On the target machine, you can check SSH connection counts with netstat -an | grep ':22'.

Some Questions

Is cwd controllable?

OpenSSH does not support this, so ssh2 doesn’t either. You cannot open a .shell session in a specified CWD directly. The only workaround is to send stream.write(\cd /var/www\n`)` after starting the shell.

The downside is that your input will be echoed.

Final Thoughts

That’s it for the ssh2 basics.

References

Introducing xterm-headless

Mon, 25 Dec 2023 22:47:35 +0800

In addition to browser components/addons, the official xterm.js repo also provides a headless component. So what is xterm‑headless?

While browsing inshellisense recently I noticed it uses xterm‑headless. After digging in, the role of the headless component became clear. Notes below.

headless nodejs support

From the official docs, headless is for Node.js usage. In other words, the server can instantiate a terminal client component and operate on it.

Notes

There are no official Node‑side addons yet, but custom ones are possible — just don’t depend on DOM APIs.

Usage

Usage mirrors the browser side — instantiate xterm.Terminal directly.

Use cases

Knowing the server can also host xterm.js, where does it shine?

For example: with an ssh2 connection on the server, data exchanged with the target host is a stream. Typically, we forward it to the client and write it into xterm.js, which structures it. With server‑side headless support, we can also feed the data into a server‑resident terminal. If the user closes the browser, the server session keeps running and can continue to write data to the “virtual” terminal — essentially a remote/sentinel mode.

inshellisense

Back to inshellisense (IS): it uses headless to write terminal data into a virtual terminal so it can compute cursor positions, extract terminal info, etc. See the source.

Final Thoughts

Headless is quite useful — the server can fully instantiate an xterm instance.

How to Use Tampermonkey (Step-by-Step Guide)

Sat, 23 Dec 2023 23:16:35 +0800

I’ve been using Tampermonkey scripts more this year. Here’s a summary of my current usage.

Purpose

Tampermonkey is used to enhance web pages, such as supporting video playback at multiple speeds, modifying page styles, automating some operations, etc.

Common scripts

JD Review

Right-click - automatic commenting to earn a little Jingdou.
CITIC Bank Repayment

After entering the China CITIC Bank page, automatically go to my loan page, statistics on current interest ratio and other information. The bank webpage doesn’t show this information, but these are the most important.
Video Speed Control

Some web pages don’t offer video playback at multiple speeds, so the script adds a right-click menu for speed switching.
Text Selection Support
Work Customization Scripts
- For example, when loading a certain webpage, automatically perform some option operations.

Tampermonkey setup

Enable Sync Service

If using multiple devices, it’s recommended to enable sync service.

Note: First, set the configuration mode to Advanced. If the run button in Userscript is grayed out, click save first.

Common issues

Formatting code

The plugin itself doesn’t provide code formatting tools, it’s recommended to use VSCode or other editors.

Final Thoughts

If you frequently use certain web pages but are unsatisfied, consider whether they can be enhanced with Tampermonkey.

Tampermonkey official documentation

The inspect Command in Node

Wed, 20 Dec 2023 23:53:19 +0800

When using WebStorm/Visual Studio Code, for scripts defined in package.json, we can directly click debug to start the script. Why does this allow debugging? Here’s a coarse-grained explanation.

Debugging in IDE

For example, the original script is "start": "node app.js", When we need to debug this Node service, clicking the debug button shows the following print information:

/Users/alanhe/.nvm/versions/node/v18.16.1/bin/npm run start

> express-demo@0.0.1 start
> node app.js

Debugger listening on ws://127.0.0.1:63206/3fc8664c-10d9-4f99-8ed8-04efd382d9ae
For help, see: https://nodejs.org/en/docs/inspector
Debugger attached.
Example app listening on port http://127.0.0.1:8000!

You can see an additional ws request, which is the service debugging connection. This essentially means it’s the inspector under Node.js.

What does the IDE do here? It actually adds the inspect parameter settings.

inspect in Node

The above debug is equivalent to the following command:

node --inspect=127.0.0.1:63206 app.js

Therefore, even without using IDE debug, it’s possible to do this. However, when we directly use this command, it won’t hit IDE breakpoints yet. We still need to configure it in the IDE.

For WebStorm, you need to start Attach to Node.js/Chrome. For VSC, it’s Debug:Attach to Node Process.

After attaching, you can normally debug breakpoints in the IDE.

Detailed explanation of inspect click here
The default inspect configuration is 127.0.0.1:9229

Final Thoughts

The reason for being confused about this issue is that when inspect is manually configured in the script, and then debug operation is performed in the IDE, you’ll find that breakpoints can’t be hit. The reason is that with manual inspect, the IDE cannot automatically capture the corresponding process, so it doesn’t work.

Common npm Packages for Frontend Development

Wed, 20 Dec 2023 23:04:11 +0800

Here’s a list of npm packages commonly used by frontend developers

local-web-server

Run ws to start a web server instantly
whistle

Proxy service
chalk

Colorize console output
readline

Terminal interactive input

Ways to Open a New Page in JavaScript

Wed, 20 Dec 2023 22:54:05 +0800

Frontend code often needs to open new pages. Here is a summary of methods and issues encountered.

Methods

Anchor tag
window.open

window gives finer control, such as width and height. For anchor tags, you need to create a DOM element and decide whether it is visible. Anchor tags are generally preferred because they represent user-driven interactions.

Behavior in PWA

A PWA is just a presentation mode for web pages. If you open a new page in a PWA, the behavior differs:

Anchor tags open in the traditional browser UI.
window.open follows the PWA display mode. For example, if the PWA uses standalone, the new window also uses standalone.

In my opinion, in PWAs you should use location.href rather than opening a new tab. Try to keep an app-like experience.

guacamole-common-js

Sun, 10 Dec 2023 22:24:47 +0800

Recently encountered an issue where after the remote desktop is started, switching to other tab pages causes input events to fail.

var keyboard = new Guacamole.Keyboard(document);

keyboard.onkeydown = function(keysym) {
// Do something ...
};

keyboard.onkeyup = function(keysym) {
// Do something ...
};

The code is roughly as shown above.

Cause

Guacamole.Keyboard captures events and prevents bubbling, so as long as it’s not destroyed, it will continue to capture all keyboard events on the webpage.

Solution

Save the keyboard.onkeydown/onkeyup bound events elsewhere, set keyboard.onkeydown=null, keyboard.onkeyup=null. Then restore them when needed.
Set the binding element for new Guacamole.Keyboard to the RDP desktop element

https://guacamole.apache.org/doc/gug/guacamole-common-js.html#keyboard

Final Thoughts

This issue demonstrates the importance of understanding how Guacamole’s keyboard event handling works. The solution involves either temporarily disabling the keyboard event handlers or binding them to a more specific element to prevent them from capturing events across the entire document when not needed.

Online Failure - Hidden Timer Issues

Sat, 09 Dec 2023 19:45:51 +0800

Recently encountered a serious issue online where our server was frantically sending heartbeat requests to another SDK service provider. After investigation, it turned out to be caused by an overlooked point related to timers, so marking it here.

Problem Situation

The current situation is that one service IP made over 4000 requests per minute. Actually, under normal circumstances, it should only report once every 5 minutes.

Analysis

The entire troubleshooting process was relatively simple/clear

After confirming, the heartbeat request is automatically triggered by the SDK itself when initializing instance objects. Our logic has no heartbeat setup or heartbeat calling logic, so it must be an initialization logic problem
- The SDK class constructor has setInterval logic
Querying the program revealed there are currently 4 places initializing instance objects, with 1 place initializing at service startup, and the other 3 triggered during API calls. So if API calls are frequent enough, it would bring N timers
Checking production logs, the increased frequency of related API calls also correlates with data time points monitored by another service

OK, after identifying the problem, the solution was also clear - remove the logic of instantiating SDK objects during API calls. According to our actual situation, we should maintain a singleton and initialize it at service startup.

After fixing, re-monitoring showed it’s back to normal.

Summary

When JS functions finish executing, they destroy related objects but do not destroy timers. Therefore, when calling logic that starts timers, you must pay attention to cleanup logic.
As above, calling certain functions that contain hidden timer logic can be a pitfall. This needs extra attention.

Implementing Input Autocomplete Visuals

Sat, 25 Nov 2023 17:28:50 +0800

While building a WebShell UI I needed an input box that shows autocomplete suggestions inline. The logic was straightforward, but the visual treatment required a small trick.

In the screenshot, typing h reveals ello as the completion. The suffix must appear in a different color.

Browsers don’t let you color arbitrary substrings inside an <input> with pure CSS. That means we need a DOM + JavaScript workaround.

Approach

Insert a <div> before the input that displays the full completion string. Give it the desired completion color.
Absolutely position the div so its text overlaps the input text exactly.
Keep the input on top using stacking context so the user can still place the caret and type normally.

Notes

The higher z-index on the input prevents the completion layer from intercepting the cursor or mouse selection.
The completion div should contain the full string (e.g., hello). Match the font size, weight, letter-spacing, etc., so the overlay aligns perfectly with the input.

Demo

https://github.com/alanhe421/express-demo/blob/master/test/input-completion/index.html

Copy/Paste Support in WebShell

Thu, 23 Nov 2023 23:27:19 +0800

I recently ran into issues with copy/paste support in WebShell. Here’s a summary.

Browser Clipboard Permissions

When clipboard permissions are disabled, using the Clipboard API throws errors. Some users’ browsers restrict clipboard access for security. Can WebShell still support copy/paste? Yes—browsers also have default copy and paste hotkeys.

Browser Copy/Paste

On Windows, copy is Ctrl+C, paste is Ctrl+V.

On macOS, copy is Cmd+C, paste is Cmd+V.

These hotkeys are fixed; pressing them triggers the corresponding default behavior.

However, page logic can intercept and prevent the default behavior, which can cause issues—for example, with xterm.js on Windows.

Ctrl+C/Ctrl+V in xterm.js

xterm.js listens for and handles key events, which can prevent these hotkeys from working. How to fix this?

Use attachCustomKeyEventHandler to handle hotkeys and return false so the default behavior continues.

customKeyEventHandler – The custom KeyboardEvent handler to attach. This is a function that takes a KeyboardEvent, allowing consumers to stop propagation and/or prevent the default action. The function returns whether the event should be processed by xterm.js.


attachCustomKeyEventHandler(customKeyEventHandler: (event: KeyboardEvent) => boolean): void;

Browser hotkeys can’t fully replace the Clipboard API. When clipboard is unavailable, can we still implement copy/paste?

The answer is: partially.

document.execCommand(‘copy’)

The document’s execCommand method supports copy. In testing, even without Clipboard API, you can dynamically copy specific text to the clipboard.

Paste isn’t supported (IE reportedly supports it). Note that this API is deprecated and considered legacy. Still, as a fallback for copy, it’s a reasonable option.

Final Thoughts

That’s pretty much it for copy/paste.

In summary, when Clipboard API access is unavailable, you can still rely on the browser’s default hotkeys for basic text copy/paste—just make sure you don’t block the default behavior.

done.

References

How to Use Mousetrap (Step-by-Step Guide)

Sun, 19 Nov 2023 11:42:09 +0800

For web hotkey listening and handling, you can use mousetrap.js. This library is no longer maintained, but it’s still very useful and recommended.

Here’s an introduction to its usage.

Features

Supports single/combined keys/Gmail-style/Konami Code key bindings

Gmail-style means like g i, where consecutive key inputs can execute an action. The advantage of this hotkey style is that it easily avoids browser/plugin hotkeys
Konami Code is somewhat like in Contra where specific key combinations trigger 30 lives. Personally, I think this type of key binding is quite suitable for web easter eggs if necessary

In addition to basic hotkey binding features, Mousetrap also has some extensions to solve specific needs

Pause/unpause

Stop and resume this Mousetrap’s bindings
Record

Hotkey recording, useful when implementing custom web hotkeys
Bind dictionary

Supports dictionary format for binding multiple hotkeys at once.

Usage

The Mousetrap constructor parameter is the element to bind hotkey listening to. If not provided, it defaults to document
```
let mousetrap = new Mousetrap(window);
```
bind
```
mousetrap.bind(['command+k','g i'], function(e,combokey) { highlight(combokey); });
```
Note: The second parameter of the callback is the key combination, such as command+k or g i
unbind
```
 mousetrap.unbind(['command+k']);
```
Note: The keys for unbind are the same as for bind, so they can also be arrays/strings
trigger
```
 mousetrap.trigger(['g i']);
```
stopCallback
```
 mousetrap.stopCallback = function () {
 return false;
 };
```
Controls callback prevention logic. By default, hotkey bindings are not triggered in input/textarea/editable situations. As shown above, it triggers in all request situations
reset()
```
 mousetrap.reset();
```
Reset means delete all bindings
addKeycodes
```
 Mousetrap.addKeycodes({
 144: 'numlock'
 });
```
Add keycode mappings, usually don’t need to change. This is because the library is aging, and the entire implementation uses keycode instead of key. Currently MDN no longer recommends using KeyCode

record

mousetrap.record(function(sequence) {
 alert('You pressed: ' + sequence.join(' '));
 });

Note: The record timeout is fixed at 1s and does not support continuous recording

Mousetrap Issues

The record timeout is hardcoded to 1s. Currently, you need to modify the source code to extend it as a parameter, or change the value to solve this
```
 function _restartRecordTimer() {
 clearTimeout(_recordTimer);
 _recordTimer = setTimeout(_finishRecording, 1000);
 }
```

Mousetrap uses event bubbling. If you want to use event capturing, you also need to modify the source code to extend support

 function _addEvent(object, type, callback) {
 if (object.addEventListener) {
 object.addEventListener(type, callback, false);
 return;
 }

 object.attachEvent('on' + type, callback);
 }

The record plugin import and packaging will encounter errors because i is undefined in the for loop, which causes errors in strict mode packaging.
```
 ```js
for (i = 0; i < modifiers.length; ++i) {
_recordKey(modifiers[i]);
}
```
```

Final Thoughts

If you need to implement hotkey binding in WEB, you can still consider using Mousetrap

Command Palette in WebShell

Sat, 18 Nov 2023 20:02:35 +0800

The WebShell command palette feature recently launched. Here are the design notes and considerations.

Problem Statement

Why build this?

As WebShell’s features grow, user “action paths” get longer. Example: logging into a machine without a command palette might require:

Click Connections
Focus the search input
Select a connection config
Click Login

This path is long. The command palette offers an interaction similar to Alfred/Raycast on macOS: keep your hands on the keyboard to execute actions quickly.

With a command palette:

Use a hotkey to open the palette
Use the input + arrow keys to choose a connection
Press Enter to log in

The number of steps may be similar, but you never leave the keyboard, improving flow.

Design

At its core, the palette displays a list of actions. Let’s define a CommandAction. Each menu item is a CommandAction.

CommandAction

 {
 uid: string;
 icon?: React.ReactNode;
 title: string;
 match?: string[];
 render?: (item?: CommandAction) => React.ReactNode;
 hotkey?: GlobalAction;
 action: ({ setQuery }: { setQuery: (q: string) => void }) => void;
 actionMap?: {
 [comboKey: string]: ({ close, shaking }) => void
 };
 windowDontCloseOnAction?: boolean;
 preCheck?: () => React.ReactNode;
 variables?: {
 [index: string]: any;
 },
};

Some design notes:

uid uniquely identifies a command for things like history ordering.
match follows Alfred’s idea: matching only on title can be limiting. For example, a “search” keyword might match Google. With match, you can add extra keywords to improve recall quality.
action defines the Enter behavior. As the palette grows, Enter alone may not be enough. Add modifier+Enter combos via actionMap to expand functionality. Think of action as the enter entry in actionMap.
hotkey shows the command’s shortcut.
variables holds contextual variables when the command is highlighted/executed.

CommandAction List

Where does the list come from? Some are static (declared in code), others are generated dynamically via JS, e.g., fetched from the backend. The palette renders whatever list it receives.

For the full list, filtering is straightforward:

Fuzzy-match against title. If the UI is Chinese, supporting pinyin search improves UX.
- Keep the full list in memory and filter on the query.
For match, use exact matches. If it were fuzzy too, recall might be too broad and reduce quality.

Multi-level CommandAction Lists

As the palette grows, one level isn’t enough. For example, you might want to pick a specific SSH profile within the palette and press Enter to connect. Hence, multi-level support.

How to link levels?

Method 1

Maintain a ScriptCommandsMap: key = trigger keyword, value = a function that generates the list. The trigger keyword is not the user’s filter text; it’s the activation keyword. The top level could be empty; a second-level list might use a keyword like connect. When the user types connect, the palette resolves the function and renders the generated list.

Method 2

Add a type to CommandAction. If it’s a subcommand, pressing Enter shouldn’t close the palette; instead, the action returns a list to display next.

I currently use Method 1, but may switch to Method 2 to avoid a large central map and let each command handle its own logic, improving maintainability.

Some terminal products offer similar features:

xterminal: single-level only
warp: supports multi-level (e.g., sessions listing)

How to Use the keyboard.lock API (Step-by-Step Guide)

Sun, 12 Nov 2023 15:30:13 +0800

I have been working on custom hotkeys for WebShell. The issue is that web hotkeys are limited by the browser and operating system, so some hotkeys cannot be captured, such as command t.

After some research, I found that navigator.keyboard.lock can solve this limitation. Here are some notes and takeaways from using it.

Hotkeys That Cannot Be Intercepted

Taking macOS as an example, the following hotkeys cannot be intercepted in real tests. That is, at the JS layer we cannot capture these keys and therefore cannot prevent the default behavior.

⌘ N Create new window
⌘ T Create new Tab
⌘ W Close Tab
⌘ ⇧ [ Previous Tab
⌘ ⇧ ] Next Tab

This seems unsolvable, but with the lock API, these may become possible to handle.

Lock API

lock can be called without parameters to lock all keys.
lock can take parameters to lock specific keys, and it does not support locking modifier keys.

navigator.keyboard.lock(["KeyW", "KeyA", "KeyS", "KeyD"]);

Currently only supported in fullscreen mode. In non-fullscreen mode, lock does not throw errors but also does not work.

System keyboard lock is only available when the document is in fullscreen mode, and only from a secure origin.

See https://github.com/WICG/keyboard-lock/blob/gh-pages/explainer.md

Compatibility: Chrome/Edge/Opera are supported, Firefox/Safari are not.

See https://caniuse.com/mdn-api_keyboard_lock

Examples

In PWA

In PWA, even without fullscreen, navigator.keyboard.lock can still capture keys. But the behavior is not consistent across OSes. So even for PWA, it is recommended to use hotkeys in fullscreen for the best experience.

Final Thoughts

The lock API addresses the pain point of web hotkeys being restricted. Unfortunately, several mainstream browsers still do not fully support it. Looking forward to the day it is widely supported.

Displaying Images in WebShell

Sun, 05 Nov 2023 23:11:51 +0800

Can a terminal display images? Yes. Here’s a summary of how to display images in xterm.js.

Result

Implementation

Server side

Using a Mac as the target server for installing libraries:

# sixel protocol
brew install libsixel

# imgcat can also be installed via iTerm2’s Shell integration package
brew install eddieantonio/eddieantonio/imgcat

WebShell

Frontend setup is straightforward: load @xterm/addon-image.

Note: @xterm/addon-image is an official xterm addon.

npm install --save @xterm/addon-image

 const customSettings = {
 enableSizeReports: true, // whether to enable CSI t reports (see below)
 pixelLimit: 16777216, // max. pixel size of a single image
 sixelSupport: true, // enable sixel support
 sixelScrolling: true, // whether to scroll on image output
 sixelPaletteLimit: 256, // initial sixel palette size
 sixelSizeLimit: 25000000, // size limit of a single sixel sequence
 storageLimit: 128, // FIFO storage limit in MB
 showPlaceholder: true, // whether to show a placeholder for evicted images
 iipSupport: true, // enable iTerm IIP support
 iipSizeLimit: 20000000 // size limit of a single IIP sequence
 }
 const imageAddon = new ImageAddon.ImageAddon(customSettings);

 term.loadAddon(imageAddon);

When the image addon isn’t loaded

If WebShell doesn’t load the ImageAddon, the output looks like this. The image data is wrapped in escape sequences, so it won’t render in the terminal by default.

Final Thoughts

With this, WebShell can display images in the terminal. As for the actual value of showing images in a terminal—that depends on your design and use cases.

References

How to Use CSS :has() Function (Step-by-Step Guide)

Wed, 01 Nov 2023 10:13:08 +0800

Recently while developing WebShell, I encountered a requirement to dynamically adjust styles - when the terminal enables split-screen mode with editor appearing on the top, the terminal at the bottom needs style adjustments, specifically adjusting the minimum height. Considering implementing this with CSS.

Analysis

The :has() function can use CSS selectors to determine whether a certain element exists after or within child descendants. Therefore, using :has() can capture the editor element in split-screen situations, then normally use + to get sibling elements, and actually adjust styles. Of course, JS can also implement this, but CSS implementation is simpler.

Example

 <style>
 .terminal {
 width: 100%;
 min-height: 200px;
 background-color: #4bd58d;
 }
 .editor{
 width: 100%;
 height: 100px;
 background-color: #003dfd;
 }

 .editor:has(+.terminal) +.terminal{
 background-color: #ff0000;
 }
 </style>

Compatibility

When using CSS functions, compatibility should always be considered. The :has() function is currently not supported in Firefox. However, since this functionality is just an enhancement here, compatibility doesn’t need to be considered. If compatibility is needed, consider implementing with JS.

Final Thoughts

CSS functions can to some extent avoid implementation through JS, so they can be utilized more in development. Of course, compatibility also needs to be considered, as compatibility is a major challenge in frontend development.

Installing and Switching Shells

Tue, 31 Oct 2023 10:27:11 +0800

While adding shell hooks to a web shell project, I hit a few quirks. Here’s a cheat sheet for installing various shells and switching between them, using Ubuntu as the example OS.

Bash

chsh -s $(which bash)
# Version
bash --version

Zsh

sudo apt install zsh
chsh -s $(which zsh)
# Version
zsh --version

Fish

sudo apt install fish
sudo chsh -s $(which fish)

Tcsh

sudo apt install tcsh
chsh -s $(which tcsh)

Notable Differences

In Bash and Zsh, printf "PreExecMarker;$1"; doesn’t escape arguments, so placeholders like date +%Y can trigger errors. Fish and Tcsh automatically escape arguments and avoid the issue.

Fix it by specifying the format explicitly:
```
printf "PreExecMarker;%s" "date +%Y"
```

Implementing SFTP File Management in WebShell

Sun, 24 Sep 2023 16:44:40 +0800

After enabling web-based terminal access via WebShell, users also need visual file management: upload/download, permission changes, inline editing, etc. Here’s a summary of the implementation.

ssh2 + ssh2-sftp-client

After solving the terminal connection with ssh2, use ssh2-sftp-client to perform file operations:

list to fetch file lists
- Returns file type, name, owner uid, group gid, size, atime, mtime
- For symlinks, type is l; hard links appear as -
get/put for streaming upload/download
rename to rename files
delete to delete files
stat to get file info
mkdir to create directories
rename to rename files

These cover the basics, but there are additional concerns.

Issues

Check whether the current user has permissions

First determine the current user’s uid/gid. Use ssh2.exec to run id to obtain them. Then compare with the file’s uid/gid from list/stat to infer permissions.

User list

The GUI needs to change file ownership. Since list/stat provides uid/gid, you only need a user list. For example:

# Output format:
# root,0
grep /bin/bash /etc/passwd | awk -F: '{print $1 "," $3}'

Hidden files in lists

To hide dotfiles, pass a filter (regex in older versions) when listing:
```
conn.list(path, /^[^.]/);
```
Note: SFTP doesn’t support server-side filtering; ssh2 still fetches all entries and filters client-side. In ssh2-sftp-client v9, list switched from regex to a callback filter, which still works for this.
Use the terminal session’s current working directory as the default open path

Strictly speaking this is terminal-side, not SFTP. But it greatly improves UX. Implement via terminal hooks: after each command, run pwd and send the result to the client. The client parses and caches the path; when opening SFTP, pass it as the initial path.
```
source /usr/local/bash-precmd/bash-preexec.sh
preexec() { printf "\x1B]1337;PreExec;Timestamp=$(date +%s);\x7"; }

precmd() { printf "\x1B]1337;PostExec;Exit=$?;CurrentDir=$(pwd);Timestamp=$(date +%s);CurrentUser=$USER;\x7"; }
```

Beyond SFTP, there are other cases such as kubectl.

kubectl

If managing containers via kubectl, SFTP won’t work. You’ll need to execute commands and parse the results.

Use ls and friends to list files. Note that commands differ across container OSes and may need branching.
```
ls -l --time-style=full-iso /
```
- Add -A to hide dotfiles
- --time-style=full-iso stabilizes time format regardless of system locale
Avoid stat for file properties since output can be localized (e.g., “directory” differs by locale). Prefer ls with -d so the result is a single entry for the target file/dir. Also note that unlike ls -l, there’s no first-line summary.
```
ls -ld --time-style=full-iso /
```

Final Thoughts

The above outlines the main path; real-world implementations are more complex, but the key points are here.
After WebShell shipped file management, long-term observations showed it became the No.1 used feature—clearly very important.

Integrating AI into WebShell

Sat, 16 Sep 2023 23:43:22 +0800

AI is empowering many products. WebShell now integrates AI services as well.

Here is what I’ve built with AI so far and some TODOs.

Prompt engineering

If the AI service supports a system prompt, you can set it like this:

You are a Shell expert. I want to know how to complete tasks in the terminal or command line. I will ask shell-related questions and you return solutions. If asked who you are, reply with I am the WebShell AI assistant. If asked non-shell questions, reply with Not shell-related, I don't know.
If the AI service doesn’t support system prompts, craft a user prompt instead:

You are a Shell expert. I want to know how to complete tasks in the terminal or command line. I will ask shell-related questions and you return solutions. If asked who you are, reply with I am the WebShell AI assistant. If asked non-shell questions, reply with Not shell-related, I don't know. My question is: {{userPrompt}}

User prompt engineering can play a role similar to a system prompt.
Prompt language matters

Due to how LLMs work, the same prompt can yield different results depending on parameters like temperature. Language (Chinese vs English) also affects results. For domestic AI services, I use Chinese prompts.

Conversation context handling

Don’t send unlimited history. For example, keep the last 5 messages (2 turns + the latest user prompt). This ensures an odd number of messages.
A “turn” is one user + one assistant message. If a user asked something and then stopped the response before the assistant replied, don’t include that orphaned user message in the next context - keep 1:1 pairing.

Token costs

AI usage is typically billed by tokens; both requests and responses consume tokens.
To reduce costs, some APIs (e.g., OpenAI’s) support max token limits via max_tokens. Some domestic APIs like Hunyuan/Wenxin don’t yet.
Streaming vs non-streaming: in streaming mode, canceling the stream can interrupt generation on some providers, reducing tokens. Not all providers stop generation promptly.

Streaming

Benefits:

Better UX: the model starts returning tokens as soon as they’re generated, so users see partial content sooner. Total completion time is similar to non-streaming.
Potentially lower token usage if generation stops quickly after canceling (provider-dependent).

TODO

Fine-tuning

Prompt engineering can shape answers but is often insufficient. Fine-tuning helps steer answers for a class of queries by shifting output probabilities based on many examples.

I haven’t done fine-tuning for WebShell yet - leaving this as a placeholder.

Resources

https://community.openai.com/t/chatgpts-stop-generating-function-how-to-implement/235121/7

Final Thoughts

The AI service I use doesn’t support system prompts yet, so I’m composing user prompts, with imperfect results.

Developing Mini Programs with Taro

Sat, 09 Sep 2023 00:07:44 +0800

Introduction

Taro is a cross-platform development framework that allows you to write code once and compile it to run on multiple platforms including WeChat Mini Programs, Alipay Mini Programs, Baidu Smart Programs, ByteDance Mini Programs, QQ Mini Programs, and H5, React Native, and other platforms.

Why Choose Taro

Advantages

Write Once, Run Everywhere: Single codebase for multiple platforms
React-like Syntax: Familiar development experience for React developers
Component-based Development: Reusable components across platforms
Rich Ecosystem: Comprehensive toolchain and plugin system
TypeScript Support: Built-in TypeScript support
Performance Optimization: Optimized compilation and runtime

Supported Platforms

Mini Programs: WeChat, Alipay, Baidu, ByteDance, QQ, Kuaishou
Mobile Apps: React Native (iOS/Android)
Web: H5, Progressive Web Apps
Desktop: Electron (experimental)

Getting Started

Installation

# Install Taro CLI globally
npm install -g @tarojs/cli

# Create new project
taro init myApp

# Choose template
# ❯ TypeScript
# JavaScript
# Vue
# Vue3

Project Structure

myApp/
├── src/
│ ├── pages/ # Page components
│ │ └── index/
│ │ ├── index.tsx
│ │ ├── index.config.ts
│ │ └── index.scss
│ ├── components/ # Reusable components
│ ├── utils/ # Utility functions
│ ├── services/ # API services
│ ├── app.tsx # App entry
│ ├── app.config.ts # App configuration
│ └── app.scss # Global styles
├── config/ # Build configuration
├── package.json
└── project.config.json

Basic Configuration

// app.config.ts
export default defineAppConfig({
 pages: [
 'pages/index/index',
 'pages/profile/profile'
 ],
 window: {
 backgroundTextStyle: 'light',
 navigationBarBackgroundColor: '#fff',
 navigationBarTitleText: 'My Taro App',
 navigationBarTextStyle: 'black'
 },
 tabBar: {
 color: '#666',
 selectedColor: '#b4282d',
 backgroundColor: '#fafafa',
 borderStyle: 'black',
 list: [
 {
 pagePath: 'pages/index/index',
 text: 'Home',
 iconPath: 'assets/home.png',
 selectedIconPath: 'assets/home-active.png'
 },
 {
 pagePath: 'pages/profile/profile',
 text: 'Profile',
 iconPath: 'assets/profile.png',
 selectedIconPath: 'assets/profile-active.png'
 }
 ]
 }
});

Component Development

Functional Components

import { View, Text, Button } from '@tarojs/components';
import { useState } from 'react';
import Taro from '@tarojs/taro';

const Counter: React.FC = () => {
 const [count, setCount] = useState(0);

 const increment = () => {
 setCount(count + 1);
 };

 const showToast = () => {
 Taro.showToast({
 title: `Count: ${count}`,
 icon: 'none'
 });
 };

 return (
 <View className="counter">
 <Text className="count-text">Count: {count}</Text>
 <Button onClick={increment}>Increment</Button>
 <Button onClick={showToast}>Show Toast</Button>
 </View>
 );
};

export default Counter;

Class Components

import { Component } from 'react';
import { View, Text, Input } from '@tarojs/components';
import Taro from '@tarojs/taro';

interface State {
 inputValue: string;
 todos: string[];
}

class TodoList extends Component<{}, State> {
 state: State = {
 inputValue: '',
 todos: []
 };

 componentDidMount() {
 console.log('Component mounted');
 }

 handleInputChange = (e) => {
 this.setState({
 inputValue: e.detail.value
 });
 };

 addTodo = () => {
 const { inputValue, todos } = this.state;
 if (inputValue.trim()) {
 this.setState({
 todos: [...todos, inputValue],
 inputValue: ''
 });
 }
 };

 render() {
 const { inputValue, todos } = this.state;

 return (
 <View className="todo-list">
 <View className="input-section">
 <Input
 value={inputValue}
 onInput={this.handleInputChange}
 placeholder="Enter todo..."
 />
 <Button onClick={this.addTodo}>Add</Button>
 </View>

 <View className="todos">
 {todos.map((todo, index) => (
 <View key={index} className="todo-item">
 <Text>{todo}</Text>
 </View>
 ))}
 </View>
 </View>
 );
 }
}

export default TodoList;

Platform APIs

import Taro from '@tarojs/taro';

// Navigate to new page
const navigateToDetail = () => {
 Taro.navigateTo({
 url: '/pages/detail/detail?id=123'
 });
};

// Redirect to page
const redirectToLogin = () => {
 Taro.redirectTo({
 url: '/pages/login/login'
 });
};

// Navigate back
const goBack = () => {
 Taro.navigateBack({
 delta: 1
 });
};

// Switch tab
const switchToProfile = () => {
 Taro.switchTab({
 url: '/pages/profile/profile'
 });
};

Storage

import Taro from '@tarojs/taro';

// Set storage
const saveUserData = async (userData) => {
 try {
 await Taro.setStorage({
 key: 'userData',
 data: userData
 });
 console.log('Data saved successfully');
 } catch (error) {
 console.error('Failed to save data:', error);
 }
};

// Get storage
const getUserData = async () => {
 try {
 const result = await Taro.getStorage({
 key: 'userData'
 });
 return result.data;
 } catch (error) {
 console.error('Failed to get data:', error);
 return null;
 }
};

// Remove storage
const clearUserData = async () => {
 try {
 await Taro.removeStorage({
 key: 'userData'
 });
 console.log('Data cleared');
 } catch (error) {
 console.error('Failed to clear data:', error);
 }
};

Network Requests

import Taro from '@tarojs/taro';

// GET request
const fetchUserList = async () => {
 try {
 const response = await Taro.request({
 url: 'https://api.example.com/users',
 method: 'GET',
 header: {
 'Content-Type': 'application/json'
 }
 });

 if (response.statusCode === 200) {
 return response.data;
 } else {
 throw new Error('Request failed');
 }
 } catch (error) {
 console.error('Network error:', error);
 Taro.showToast({
 title: 'Network error',
 icon: 'none'
 });
 }
};

// POST request
const createUser = async (userData) => {
 try {
 const response = await Taro.request({
 url: 'https://api.example.com/users',
 method: 'POST',
 data: userData,
 header: {
 'Content-Type': 'application/json'
 }
 });

 return response.data;
 } catch (error) {
 console.error('Failed to create user:', error);
 throw error;
 }
};

// File upload
const uploadImage = async (filePath) => {
 try {
 const response = await Taro.uploadFile({
 url: 'https://api.example.com/upload',
 filePath: filePath,
 name: 'file',
 formData: {
 userId: '123'
 }
 });

 return JSON.parse(response.data);
 } catch (error) {
 console.error('Upload failed:', error);
 throw error;
 }
};

State Management

Using Redux

npm install @reduxjs/toolkit react-redux

// store/index.ts
import { configureStore } from '@reduxjs/toolkit';
import counterSlice from './counterSlice';

const store = configureStore({
 reducer: {
 counter: counterSlice,
 },
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

export default store;

// store/counterSlice.ts
import { createSlice, PayloadAction } from '@reduxjs/toolkit';

interface CounterState {
 value: number;
}

const initialState: CounterState = {
 value: 0,
};

export const counterSlice = createSlice({
 name: 'counter',
 initialState,
 reducers: {
 increment: (state) => {
 state.value += 1;
 },
 decrement: (state) => {
 state.value -= 1;
 },
 incrementByAmount: (state, action: PayloadAction<number>) => {
 state.value += action.payload;
 },
 },
});

export const { increment, decrement, incrementByAmount } = counterSlice.actions;
export default counterSlice.reducer;

// app.tsx
import { Component, PropsWithChildren } from 'react';
import { Provider } from 'react-redux';
import store from './store';

class App extends Component<PropsWithChildren> {
 render() {
 return (
 <Provider store={store}>
 {this.props.children}
 </Provider>
 );
 }
}

export default App;

// Using Redux in components
import { useSelector, useDispatch } from 'react-redux';
import { RootState } from '../store';
import { increment, decrement } from '../store/counterSlice';

const Counter: React.FC = () => {
 const count = useSelector((state: RootState) => state.counter.value);
 const dispatch = useDispatch();

 return (
 <View>
 <Text>Count: {count}</Text>
 <Button onClick={() => dispatch(increment())}>+</Button>
 <Button onClick={() => dispatch(decrement())}>-</Button>
 </View>
 );
};

Platform-Specific Development

Conditional Compilation

import Taro from '@tarojs/taro';

const MyComponent: React.FC = () => {
 const handleClick = () => {
 // #ifdef WEAPP
 // WeChat Mini Program specific code
 wx.showModal({
 title: 'WeChat',
 content: 'This is WeChat Mini Program'
 });
 // #endif

 // #ifdef ALIPAY
 // Alipay Mini Program specific code
 my.alert({
 title: 'Alipay',
 content: 'This is Alipay Mini Program'
 });
 // #endif

 // #ifdef H5
 // H5 specific code
 alert('This is H5');
 // #endif
 };

 return (
 <View>
 <Button onClick={handleClick}>Platform Test</Button>

 {/* Conditional rendering */}
 {process.env.TARO_ENV === 'weapp' && (
 <Text>WeChat Mini Program only</Text>
 )}

 {process.env.TARO_ENV === 'h5' && (
 <Text>H5 only</Text>
 )}
 </View>
 );
};

Platform-Specific Styles

// Common styles
.container {
 padding: 20px;

 // WeChat Mini Program
 /* #ifdef WEAPP */
 background-color: #f0f0f0;
 /* #endif */

 // H5
 /* #ifdef H5 */
 background-color: #ffffff;
 max-width: 750px;
 margin: 0 auto;
 /* #endif */

 // Alipay Mini Program
 /* #ifdef ALIPAY */
 background-color: #1677ff;
 /* #endif */
}

Custom Components

Creating Reusable Components

// components/Card/index.tsx
import { View, Text } from '@tarojs/components';
import { ReactNode } from 'react';
import './index.scss';

interface CardProps {
 title?: string;
 children: ReactNode;
 onClick?: () => void;
}

const Card: React.FC<CardProps> = ({ title, children, onClick }) => {
 return (
 <View className="card" onClick={onClick}>
 {title && <View className="card-title">{title}</View>}
 <View className="card-content">{children}</View>
 </View>
 );
};

export default Card;

// components/Card/index.scss
.card {
 background: #fff;
 border-radius: 8px;
 box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
 margin-bottom: 16px;
 overflow: hidden;

 &-title {
 padding: 16px;
 font-size: 18px;
 font-weight: 600;
 border-bottom: 1px solid #f0f0f0;
 }

 &-content {
 padding: 16px;
 }
}

Component with Hooks

import { useState, useEffect } from 'react';
import { View, Text } from '@tarojs/components';
import Taro from '@tarojs/taro';

interface User {
 id: number;
 name: string;
 email: string;
}

const UserProfile: React.FC<{ userId: number }> = ({ userId }) => {
 const [user, setUser] = useState<User | null>(null);
 const [loading, setLoading] = useState(true);

 useEffect(() => {
 const fetchUser = async () => {
 try {
 setLoading(true);
 const response = await Taro.request({
 url: `https://api.example.com/users/${userId}`,
 method: 'GET'
 });

 if (response.statusCode === 200) {
 setUser(response.data);
 }
 } catch (error) {
 console.error('Failed to fetch user:', error);
 Taro.showToast({
 title: 'Failed to load user',
 icon: 'none'
 });
 } finally {
 setLoading(false);
 }
 };

 if (userId) {
 fetchUser();
 }
 }, [userId]);

 if (loading) {
 return <Text>Loading...</Text>;
 }

 if (!user) {
 return <Text>User not found</Text>;
 }

 return (
 <View className="user-profile">
 <Text className="user-name">{user.name}</Text>
 <Text className="user-email">{user.email}</Text>
 </View>
 );
};

export default UserProfile;

Performance Optimization

Code Splitting

import { lazy, Suspense } from 'react';
import { View, Text } from '@tarojs/components';

// Lazy load heavy components
const HeavyComponent = lazy(() => import('./HeavyComponent'));

const MyPage: React.FC = () => {
 return (
 <View>
 <Text>Page Content</Text>

 <Suspense fallback={<Text>Loading...</Text>}>
 <HeavyComponent />
 </Suspense>
 </View>
 );
};

Memoization

import { memo, useMemo, useCallback } from 'react';
import { View, Text, Button } from '@tarojs/components';

interface ItemProps {
 item: {
 id: number;
 name: string;
 price: number;
 };
 onSelect: (id: number) => void;
}

const ExpensiveItem = memo<ItemProps>(({ item, onSelect }) => {
 const formattedPrice = useMemo(() => {
 // Expensive calculation
 return `$${item.price.toFixed(2)}`;
 }, [item.price]);

 const handleSelect = useCallback(() => {
 onSelect(item.id);
 }, [item.id, onSelect]);

 return (
 <View className="item">
 <Text>{item.name}</Text>
 <Text>{formattedPrice}</Text>
 <Button onClick={handleSelect}>Select</Button>
 </View>
 );
});

export default ExpensiveItem;

Testing

Unit Testing with Jest

npm install --save-dev @types/jest jest ts-jest

// jest.config.js
module.exports = {
 preset: 'ts-jest',
 testEnvironment: 'jsdom',
 moduleNameMapping: {
 '^@/(.*)$': '<rootDir>/src/$1'
 },
 setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts']
};

// __tests__/Counter.test.tsx
import { render, fireEvent } from '@testing-library/react';
import Counter from '../Counter';

describe('Counter Component', () => {
 test('renders initial count', () => {
 const { getByText } = render(<Counter />);
 expect(getByText('Count: 0')).toBeInTheDocument();
 });

 test('increments count when button clicked', () => {
 const { getByText } = render(<Counter />);
 const button = getByText('Increment');

 fireEvent.click(button);
 expect(getByText('Count: 1')).toBeInTheDocument();
 });
});

Deployment

Build for Different Platforms

# Build for WeChat Mini Program
npm run build:weapp

# Build for Alipay Mini Program 
npm run build:alipay

# Build for H5
npm run build:h5

# Build for React Native
npm run build:rn

WeChat Mini Program Deployment

# Development build
npm run dev:weapp

# Production build
npm run build:weapp

# Open WeChat Developer Tools
# Import the dist folder as project

H5 Deployment

// config/prod.js
module.exports = {
 env: {
 NODE_ENV: '"production"'
 },
 defineConstants: {
 API_BASE_URL: '"https://api.production.com"'
 },
 h5: {
 publicPath: '/myapp/',
 staticDirectory: 'static',
 router: {
 mode: 'browser' // or 'hash'
 }
 }
};

Best Practices

1. Component Design

// Good - Single responsibility
const UserAvatar: React.FC<{
 src: string;
 size?: 'small' | 'medium' | 'large';
 onClick?: () => void;
}> = ({ src, size = 'medium', onClick }) => {
 const className = `avatar avatar-${size}`;

 return (
 <Image
 className={className}
 src={src}
 onClick={onClick}
 />
 );
};

// Good - Composition over inheritance
const UserCard: React.FC<{ user: User }> = ({ user }) => {
 return (
 <Card title="User Profile">
 <UserAvatar src={user.avatar} size="large" />
 <Text>{user.name}</Text>
 <Text>{user.email}</Text>
 </Card>
 );
};

2. Error Handling

import { useState, useEffect } from 'react';
import Taro from '@tarojs/taro';

const useApiData = <T>(url: string) => {
 const [data, setData] = useState<T | null>(null);
 const [loading, setLoading] = useState(true);
 const [error, setError] = useState<string | null>(null);

 useEffect(() => {
 const fetchData = async () => {
 try {
 setLoading(true);
 setError(null);

 const response = await Taro.request({ url });

 if (response.statusCode === 200) {
 setData(response.data);
 } else {
 throw new Error(`HTTP ${response.statusCode}`);
 }
 } catch (err) {
 setError(err instanceof Error ? err.message : 'Unknown error');
 } finally {
 setLoading(false);
 }
 };

 fetchData();
 }, [url]);

 return { data, loading, error };
};

3. Type Safety

// Define types for better development experience
interface ApiResponse<T> {
 code: number;
 message: string;
 data: T;
}

interface User {
 id: number;
 name: string;
 email: string;
 avatar?: string;
}

interface PageProps {
 userId: string;
}

const UserDetailPage: React.FC = () => {
 const { userId } = Taro.getCurrentInstance().router?.params as PageProps;
 const { data: user, loading, error } = useApiData<User>(
 `/api/users/${userId}`
 );

 // Type-safe component logic
};

Conclusion

Taro provides a powerful solution for cross-platform mini program development. Key benefits include:

Code Reusability: Write once, deploy everywhere
Familiar Syntax: React-like development experience
Rich Ecosystem: Comprehensive tooling and community support
Performance: Optimized compilation and runtime
Type Safety: Built-in TypeScript support

While Taro handles most platform differences automatically, understanding platform-specific features and limitations is crucial for building robust applications. Start with simple components and gradually explore advanced features as your application grows.

Recently, I had a mini program development project. Since I’ve been using React as my main technology for the past few years, after weighing the options, I decided to use Taro because it supports React for development. Here, I’ve accumulated some experience and summarized it for future reference.

Get Started


npm i -g @tarojs/cli

taro init

# If you plan to use taro-ui in the future, you need to select Sass because taro-ui uses Sass.

UI Component Libraries

taro-ui I also researched other options. Considering the convenience of maintenance and use, I ultimately chose taro-ui.

Some Libraries

For form state management, you can use react-hook-form
For state management, you can use redux
For network requests, you can use axios
For QR code generation, you can use taro-code

The time-style Parameter in Linux ls

Tue, 05 Sep 2023 21:40:18 +0800

While building WebShell, I needed a reliable way to get file lists and metadata from ls. Here’s a note.

Command

ls -Al --time-style=full-iso

The output looks like:

total 190600
-rw-r--r-- 1 root root 1781 2023-07-24 09:56:56.520113036 +0800 cosfs.sh
drwxrwxrw- 3 root root 4096 2023-06-05 16:32:39.466006640 +0800 dir1
drwxrwxrw- 2 root root 4096 2023-05-27 20:46:06.219707419 +0800 dir2
lrwxrwxrwx 1 root root 4 2023-09-05 21:45:49.401943527 +0800 dir3 -> dir1
drwxr-xr-x 3 root root 4096 2023-05-06 06:57:38.000000000 +0800 docs
drwxr-xr-x 484 root root 20480 2023-05-06 15:42:58.494411265 +0800 node_modules
drwxr-xr-x 4 root root 4096 2023-08-29 11:07:33.162370076 +0800 .orca_term
-rw-r--r-- 1 root root 195132152 2023-06-14 19:04:12.167000570 +0800 test 2.zip

From this output, you can parse:

Permissions
Owner
Group
File size
ISO time with timezone
File name (and symlink target if ->)

Limitations / compatibility

time-style is not supported on all Linux distributions, and Unix-like systems may not support it either.

Examples:

Alpine Linux does not support it and has no built-in equivalent.
Unix-like systems such as FreeBSD do not support it.

Workarounds

Install coreutils. On FreeBSD: pkg install coreutils. On Alpine: apk add coreutils.
Avoid time-style and combine stat instead. The downside is worse performance due to extra commands.

Final Thoughts

Linux has many distributions. Be careful about compatibility, which depends on command versions and Linux/Unix standards.

Terminal Search in WebShell

Mon, 21 Aug 2023 11:58:25 +0800

install

npm i xterm-addon-search

const searchAddon = new SearchAddon();

term.loadAddon(searchAddon);

Notes

On the alternate screen (e.g., within vi), search results may be inaccurate, since the content loaded by vi isn’t necessarily the full file. For commands like cat, terminal-level search works fine. On the alternate screen, prefer the editor’s built-in search.

Determine whether the terminal is in normal or alternate screen with:

term.buffer.active.type === 'normal'

To listen for changes, use term.onBufferChange.

How to Use monaco-editor (Step-by-Step Guide)

Sun, 09 Jul 2023 13:38:31 +0800

Installation

npm i react-monaco-editor monaco-editor

npm i monaco-editor-webpack-plugin -D

Webpack Bundling

 new MonacoWebpackPlugin({
 // available options are documented at https://github.com/microsoft/monaco-editor/blob/main/webpack-plugin/README.md#options
 languages: ['shell', 'json', 'xml', 'yaml', 'sql', 'dockerfile', 'bat', 'ini', 'markdown', 'javascript'],
 filename: '/monaco-editor/[name].worker.[contenthash].js',
 publicPath: '',
 features: ['coreCommands'],
 globalAPI: false,
 }),

Note: the filename config only affects the main file. The dynamically loaded language module filenames are not affected by this setting. The workaround is as follows.

output:{
 chunkFilename: ({ chunk }) => {
 const regex = /((?<=esm_)vs_(basic-languages|language)_.+)/;
 const language = chunk.id.match(regex);
 return language ? `vendor/monaco-${language[1]}.[chunkhash].js` : 'vendor/[name].[chunkhash].js';
 },
 },
 ...

 optimization: {
 chunkIds: 'named',
 ...
 }

References

https://github.com/microsoft/monaco-editor/discussions/3769

How to Use xterm-addon-web-links (Step-by-Step Guide)

Thu, 06 Jul 2023 23:31:24 +0800

The xterm-addon-web-links plugin can be used to implement link recognition and clicking in xterm.js terminal content. Configuration is straightforward, but there are some detail issues. Marking them down here.

Keeping Focus on Original Tab

 term.loadAddon(new WebLinksAddon.WebLinksAddon(
 (event, uri) => {
 if (isMac ? event.metaKey : event.ctrlKey) {
 window.open(uri);
 }
 }));

Browsers have two behaviors for link clicks:

LeftClick directly opens a new tab with focus on the new page
MetaKey+LeftClick opens a new tab but keeps focus on the original page
- ⌘ on Mac
- Ctrl on Windows

Since my requirement is to not lose focus when clicking links, I can only add metaKey judgment in the click event to ensure focus doesn’t get lost when users trigger clicks.

Can Ctrl be Used Instead of Meta on Mac?

Ctrl+LeftClick on Mac behaves equivalent to RightClick (right-click menu), so it’s not possible.

Providing Tooltips on Hover

If users don’t know about ⌘+LeftClick for link clicking, we can provide tooltip information when hovering over detected links.

{
 hover: (event, text, location) => {
 console.log(event, text, location);
 }
 }

The second parameter of WebLinksAddon is a configuration parameter that includes a hover callback function. You can get cursor position information from the event, so you can use the position information to create tooltips or similar displays.

Conclusion

That’s it!

AntiDebug Implementation

Sat, 24 Jun 2023 13:52:24 +0800

Recently while using Wenxin Yiyan (Baidu’s AI), I opened the developer tools and found that it entered a breakpoint in an anonymous function. When clicking to continue execution, the page directly turned into a blank tab. This is clearly an anti-debugging measure. Here I’ll analyze this implementation technique.

Analysis

Examining the call stack at the breakpoint revealed setInterval.
The tag for the anonymous function is displayed as VM, so the anonymous function containing the breakpoint is code generated by eval or new Function.
After the breakpoint executes, it runs window.location.replace(“about:blank”);. I couldn’t determine exactly how it detects entering a breakpoint because the code is obfuscated, but one approach is to use time difference detection. When entering a debugger, the logic execution will be significantly delayed, so calculating a time difference can determine if developer tools are open.

Example

 (function () {
 setInterval(() => {
 const startTime = performance.now();
 eval('(function() { debugger;})()');
 const stopTime = performance.now();
 if ((stopTime - startTime) > 1000) {
 window.location.replace("about:blank");
 }
 }, 400)
 })()

Xinghua’s Approach

I looked at Xinghua (iFlytek’s AI) and found they also implemented anti-crawling measures, but with a different approach. Xinghua uses the fact that opening developer tools compresses the webpage’s height or width, and detects this difference to make a determination. However, this approach has a drawback - if the developer tools are opened in a separate window, this detection becomes ineffective.

const widthThreshold = window.outerWidth - window.innerWidth > threshold;
const heightThreshold = window.outerHeight - window.innerHeight > threshold;
const orientation = widthThreshold ? 'vertical' : 'horizontal';

Counter-AntiDebug

Having roughly analyzed the implementation methods, the corresponding solutions are quite simple. For Xinghua’s approach, as mentioned earlier, simply using developer tools in a separate window breaks their detection.

For Baidu’s method which uses timers, we can simply override the timer implementation. Using Tampermonkey is recommended:

 window.setInterval = function(callback, delay) {
 // Here, we simply don't call the original setInterval function, thus blocking all timers
 console.log('Blocked a setInterval call with delay ' + delay);
 };

Never Pause Here

Conclusion

From a purely technical perspective, AntiDebug is interesting - for example, understanding the trigger mechanism of debuggers, learning HACK techniques to detect when developer tools are open, and how to break AntiDebug implementations.
Setting aside the technical aspects, why are “self-developed” AIs like Baidu and Xinghua afraid of frontend debugging? What are they 100% nervous about?

https://x-c3ll.github.io/posts/javascript-antidebugging/

Upgrade Blog Theme: 2.0

Sat, 03 Jun 2023 13:39:23 +0800

I recently did a second round of blog upgrades to keep technical debt from piling up and becoming painful later.

Quick notes on what changed.

Upgrade the Hexo Framework

# Check and update Hexo, hexo-cli, and related packages
npm-check -u

Hexo 7 is still in RC, and the NexT theme depends on 6.x right now, so I’m holding off on a major upgrade.

Upgrade the NexT Theme

I used to delete the folder and copy in the new version. Now I install it as an NPM package instead — much easier.

npm install hexo-theme-next

This bump moves from 7.8.0 to 8.17.0.

The release includes a breaking change: move source/_data/next.yml to the project root and rename it _config.next.yml.

There are two repos: next-theme/hexo-theme-next and iissnan/hexo-theme-next. Use next-theme/hexo-theme-next; that’s the one publishing to npm.

Enable AddToAny

AddThis has shut down, so I switched the sharing service over to AddToAny.

That wraps this round of upgrades.

Deploy a Personal chatgpt-telegram-bot

Wed, 26 Apr 2023 23:18:44 +0800

ChatGPT usage can be unstable. To avoid downtime impacting work, I set up a private Telegram bot as a backup. After some research, I chose to deploy the excellent chatgpt-telegram-bot.

Setup steps

In Telegram, talk to @BotFather to create a bot.
In Telegram, talk to @useridinfobot to get your user ID (not your display name).
Choose a HK or overseas server and pull the image.
```
docker pull n3d1117/chatgpt-telegram-bot:latest
```

Create a .env file and set environment variables. Reference: https://github.com/n3d1117/chatgpt-telegram-bot/blob/main/.env.example

The four main settings:

# Your OpenAI API key
OPENAI_API_KEY=XXX

# Your Telegram bot token obtained using @BotFather
TELEGRAM_BOT_TOKEN=XXX

# Telegram user ID of admins, or - to assign no admin
ADMIN_USER_IDS=ADMIN_1_USER_ID,ADMIN_2_USER_ID

# Comma separated list of telegram user IDs, or * to allow all
ALLOWED_TELEGRAM_USER_IDS=USER_ID_1,USER_ID_2

Start the container

docker run -d --name "chatgpt-telegram-bot" --env-file ./.env n3d1117/chatgpt-telegram-bot:latest

Now you can talk to your bot in Telegram.

Auto‑restart on config changes

With a plain docker run container, updating the .env file won’t auto‑reload the container. To recreate it on changes, I used inotify-tools (CentOS 7 example below):

sudo yum -y install inotify-tools
Create watch_env.sh

#!/bin/sh
while true; do
 inotifywait -e modify .env
 echo ".env file has been modified. Restarting the container..."
 docker stop chatgpt-telegram-bot
 docker rm chatgpt-telegram-bot
 docker run -d --name "chatgpt-telegram-bot" --env-file /root/chatgpt-telegram-bot/.env n3d1117/chatgpt-telegram-bot:latest
done

Create watch-env.service

sudo vi /etc/systemd/system/watch-env.service

Service configuration:

[Unit]
Description=Watch and restart Docker container on .env file changes

[Service]
Type=simple
ExecStart=/bin/bash /root/chatgpt-telegram-bot/watch_env.sh
Restart=always
User=root

[Install]
WantedBy=multi-user.target

Enable and start the service

sudo systemctl daemon-reload

sudo systemctl enable watch-env.service

sudo systemctl start watch-env.service

GPT‑4

After getting access approval, set OPENAI_MODEL=gpt-4 in .env.

Apply here: https://openai.com/waitlist/gpt-4-api

Final Thoughts

That’s it — a personal bot is up. It’s paid, but relatively stable. Hoping to get API access for GPT‑4 soon to make it even better.

Reading the ssh2 HTTPAgent Source Code

Wed, 19 Apr 2023 23:24:21 +0800

The ssh2 package ships HTTP agents that intercept requests and forward them through an SSH connection. I recently needed a custom agent, so I dug through the implementation.

The agent lives in lib/http-agents.js:

const { Agent: HttpAgent } = require('http');
const { Agent: HttpsAgent } = require('https');

for (const ctor of [HttpAgent, HttpsAgent]) {
 // ...
 exports[ctor === HttpAgent ? 'SSHTTPAgent' : 'SSHTTPSAgent'] = SSHAgent;
}

A loop adapts Node’s built-in Agent constructors and exports derived classes.

Node’s Agent signature:

new Agent([options])

ssh2’s agent accepts two arguments because it also needs SSH configuration:

constructor(connectCfg, agentOptions) {
 super(agentOptions);

 this._connectCfg = connectCfg;
 this._defaultSrcIP = (agentOptions && agentOptions.srcIP) || 'localhost';
}

connectCfg holds SSH connection parameters.
agentOptions is passed to Node’s Agent. ssh2 adds srcIP, controlling the source IP for the TCP socket.

createConnection(options, cb) is invoked by the pooling mechanism to obtain a TCP socket. The agent:

Creates an SSH Client and connects using connectCfg.
On ready, calls forwardOut to open a TCP stream.
Calls cb(null, decorateStream(stream, ctor, options)); so the stream exposes the methods expected by HTTP(S) consumers.

Error-handling highlights:

If the TCP communication errors, the error is passed to cb and the SSH client closes.
If the TCP connection closes, the SSH client closes; no error is passed to cb because the closure is expected.

When creating the local endpoint, a port must be bound. If localPort isn’t supplied, it defaults to 0, letting the OS choose an ephemeral port (not literally port 0):

const srcPort = (options && options.localPort) || 0;

Implementing an Editor Proxy in WebShell

Wed, 05 Apr 2023 13:16:34 +0800

I added an editor feature to WebShell last year. It’s finally stable now. Here’s a summary.

Research

Few terminal products ship an editor; most only provide SFTP.
Google

Architecture

Implementation

Key steps:

On the server, SSH into the target machine and install/run code-server
Use SSH port forwarding to expose the internal code-server service
Run a proxy server to receive browser requests and forward them to the user’s machine, reaching code-server

Final Thoughts

done!

Frontend Image Compression in WebShell

Wed, 05 Apr 2023 11:57:39 +0800

I recently researched frontend image compression and summed it up here.

MIME

media type

<input type="file" id="selectImg" accept="image/*"/>

For example, to restrict an upload picker so non-image files can’t be selected, use image/*.
This restriction can be bypassed on Windows, so add stricter MIME checks in the submit logic/back end as well.

 if (!file.type.startsWith('image/')) {
 e.target.value = '';
 return;
 }

Compression methods

Dimensions

Reduce file size by lowering the pixel dimensions.
Quality

Lower quality by trading off detail and fidelity.

Format comparison

Compatibility

JPEG 2000 by the JPEG group, the oldest of the JPEG successors, available in Safari
WebP by Google, available in all browsers
HEIC by the MPEG group, based on HEVC and available in iOS
- Unsupported by all major browsers
AVIF by the Alliance for Open Media (AOM), available in Chrome and Firefox
JPEG XL by the JPEG group, the next-generation codec
WebP2 by Google, an experimental successor to WebP

Is frontend compression feasible?

canvas

Compressor.js

 new Compressor(selectedImg, {
 strict: true,
 quality: 0.6,
 maxHeight: 2160,
 maxWidth: 3840,
 convertSize: 2000000,
 mimeType: 'auto',
 success(result) {

 },
 error(err) {
 console.log(err.message);
 },
 });

Gracefully fallback images

HTML

<picture>
 <source srcset="111.avif" type="image/avif">
 <source srcset="111.webp" type="image/webp">
 <img src="111.png">
</picture>

CSS background-image

There’s no great pure-CSS option today. Use JS to detect AVIF/WebP support and choose the right image at runtime.

function isAvifSupported() {
 return new Promise(resolve => {
 var image = new Image();

 image.onload = function() {
 resolve(true);
 };
 image.onerror = function() {
 resolve(false);
 };

 image.src = "data:image/avif;base64,AAAAIGZ0eXBhdmlmAAAAAGF2aWZtaWYxbWlhZk1BMUIAAADybWV0YQAAAAAAAAAoaGRscgAAAAAAAAAAcGljdAAAAAAAAAAAAAAAAGxpYmF2aWYAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAABGgAAAB0AAAAoaWluZgAAAAAAAQAAABppbmZlAgAAAAABAABhdjAxQ29sb3IAAAAAamlwcnAAAABLaXBjbwAAABRpc3BlAAAAAAAAAAIAAAACAAAAEHBpeGkAAAAAAwgICAAAAAxhdjFDgQ0MAAAAABNjb2xybmNseAACAAIAAYAAAAAXaXBtYQAAAAAAAAABAAEEAQKDBAAAACVtZGF0EgAKCBgANogQEAwgMg8f8D///8WfhwB8+ErK42A=";
 });
}

Beware: some @supports checks can be misleading. On macOS Big Sur + Safari 16, it “matched” but AVIF wasn’t actually supported, causing black screens.

Final Thoughts

Takeaways:

Use AVIF/WebP when compatible; fall back as needed.
Frontend can pre‑compress non‑animated formats when appropriate.

References

https://cloudinary.com/blog/time_for_next_gen_codecs_to_dethrone_jpeg

Custom Terminal Background Images in WebShell

Mon, 06 Mar 2023 23:50:40 +0800

WebShell recently added support for custom background images. Here’s the overall approach.

Architecture

As the diagram shows, the implementation is roughly:

xterm.js supports transparent backgrounds; set the terminal background to transparent.
Add a sibling DOM element in front of the terminal and apply a background image to it via CSS. This becomes the visual “bottom layer” beneath the terminal, with opacity controlling transparency.
Set the terminal’s parent element to a solid color without transparency.

With the above, you get a custom terminal background image with adjustable transparency.

Demo

Link

Adding a PWA Shortcut to the Desktop

Mon, 27 Feb 2023 21:51:19 +0800

We wanted users to “install” the WebShell as a desktop app. The plan: implement PWA support and leverage the add-to-home-screen experience.

PWA Configuration

`manifest.webmanifest`

Sample: https://github.com/alanhe421/express-demo/blob/781c83b468e6214cf90fa61c66a94249b81125b3/static/xterm.webmanifest

display
- minimal-ui
- standalone
name / short_name / display
- Changing name shows an update prompt after a browser restart; display applies immediately without a prompt.
description
- Shows on Windows when you hover over the shortcut—keep it short.
- Updating the manifest doesn’t refresh existing shortcuts; users must reinstall.
theme_color

Update it dynamically via <meta name="theme-color" content="#0066ff"/> if needed.

icons
- Provide 192px/512px sizes; include maskable variants.
screenshots
- Recommended sizes: 400x822 (narrow) and 1280x676 (wide).
- Use PNG; WebP didn’t work in our tests.

Register the Service Worker

Example: https://github.com/alanhe421/express-demo/blob/c129ffabc49757302bf3350c607c4dec71a1f29f/static/js/sw.js

Debugging

Chrome incognito disables install prompts and Service Worker logging.

Compatibility

Most modern browsers support PWAs (Firefox, Safari, etc.), though install support varies. Desktop installation works on recent Edge/Chrome releases for Windows and macOS.

Listen for beforeinstallprompt; if it fires, installation is available.

 window.addEventListener('beforeinstallprompt', (e) => {
 // Non-null means installation is available; null means unsupported or already installed.
 window.deferredPrompt = e;
 });

Some Chrome users still reported no prompt—likely due to browser settings. The approach above plus beforeinstallprompt gets us most of the way there.

Update: Safari on macOS Sonoma now shows installation prompts.

Common Questions

Detecting standalone launch:

 function isStandalone() {
 if (window.matchMedia('(display-mode: standalone)').matches || ('standalone' in navigator && (navigator.standalone === true))) {
 return true;
 }
 return false;
 }

Detect whether the app is already installed
- beforeinstallprompt won’t fire if it’s unsupported (Firefox), prerequisites aren’t met, or it’s already installed. There’s no perfect detection.
Programmatically open the installed app from the webpage? No API yet.
Multiple launches
- Each “Open with” click opens another window; PWAs are still browser tabs under the hood.

Custom install prompt

You can add your own UI and trigger the browser’s prompt manually:

 installApp.addEventListener('click', async () => {
 if (deferredPrompt !== null) {
 deferredPrompt.prompt();
 const {outcome} = await deferredPrompt.userChoice;
 if (outcome === 'accepted') {
 window.deferredPrompt = null;
 }
 }
 });

Splash screens? Not configurable beyond what the browser provides—simulate it with your own loading animation.
Incognito mode won’t trigger beforeinstallprompt, though Service Workers still run.
HTTPS is mandatory for PWAs.

Example Sites

Examples that support desktop install:

Closing Thoughts

This setup focuses on one PWA feature—adding a desktop entry point.

References

OpenAI Implementation for Generating Shell Commands from Descriptions

Fri, 27 Jan 2023 22:48:25 +0800

Recently researched the feasibility of using OpenAI to implement this requirement, here’s a summary

Competitive Product Research

iTerm2 recently launched this feature in 3.5.0 beta, but being a beta version, the experience is quite limited. The general implementation approach is to construct context based on user input descriptions and make requests to OpenAI. iTerm2 uses the text-davinci-003 model (GPT model). After obtaining multiple results, it displays all of them rather than just selecting the first one.
Fig also introduced AI functionality, but the AI component is not directly open-sourced, so specific details are uncertain. However, through discussions in the open-source community, we know it still uses OpenAI Codex behind the scenes. In terms of user experience, after submitting a description, it only displays one result.
zsh_codex for zsh uses OpenAI and selects the code-davinci-002 model (Codex model). Taking zsh_codex implementation as an example, after obtaining multiple results, it only displays the first one.

From the above, we can see that all use OpenAI, with the main differences being the selected algorithm model configurations and how returned results are handled, which affects the user experience.

Validation

Demo can be found here

Actual testing shows that using GPT/Codex to generate shell commands works as expected.

However, there are differences in model/configuration between the two models. Here are some points to note:

Model-Prompt

GPT and Codex differ in how context is constructed. Codex requires explicit language environment specification, while GPT requires clear specific requirements.

Codex

#!/bin/bash\n\n# ${text}.\n

I want to write a command, the requirement is ${text}.\n

Include periods - as shown above, periods and line breaks are necessary
The temperature value (0-1) makes a significant difference - 0 means completely accurate, 1 means maximum possible answers (fuzzy). In the research section above, we found that iTerm2 configures it to 0, while zsh configures it to 0.5. The specific value should be determined based on the selected model and use case, this is just for reference.

Final Thoughts

In summary, with OpenAI, generating commands from descriptions is relatively easy to implement. In practical experience, this functionality can only serve as an assistant, as it’s difficult to accurately generate a command from a single natural language description. Therefore, providing command references to users while ensuring a smooth experience is acceptable.

https://help.openai.com/en/articles/5955598-is-api-usage-subject-to-any-rate-limits