Posts: Astro 7 Build Compatibility Fix Notes on Termux / Android

Published 2026-10-27 10:16 Updated 2026-10-27 10:17 1024 words 6 min read

kissablecho avatar

kissablecho

Kissablecho's personal blog — recording life, sharing technology, anime & white stockings enthusiast.

Documenting the complete process of fixing `pnpm build` for an Astro 7 project on Termux / Android (aarch64), covering the WASI fallback and `pnpm patch` workaround when Sätteri lacks Android native bindings, as well as the compatibility solution of reusing the linux-arm64 static binary when Pagefind has no Android build.

Translated by AI model deepseek-flash.

Source Language: Simplified Chinese, Target Language: english, Translation Time: 2026-10-27 10:20

.

AI translation is for reference only. Accuracy is not guaranteed, please refer to the original text.

Foreword

This article documents the actual steps taken to fix pnpm build errors and achieve a complete build for an Astro 7 project on Termux / Android.

The Astro 7 project itself uses unified() from @astrojs/markdown-remark as its Markdown processor, but its configuration schema imports @astrojs/markdown-satteri during the module loading stage. Sätteri has no Android native binding, so even though the project uses unified(), it still triggers loading of Sätteri's native binding.

Test Environment

ComponentVersion
Android14 / aarch64
Node.js25.8.1
pnpm11.0.9
Astro7.4.2
Pagefind1.5.2
Sätteri0.10.5

1. Sätteri Has No Android Native Binding

Symptom

Cannot find native binding. npm has a bug related to optional dependencies...
cause: Error: Cannot find module '@bruits/satteri-android-arm64'

astro check fails at the configuration loading stage, before content processing even begins.

Diagnosis

@astrojs/markdown-satteri depends on satteri. The optionalDependencies of satteri@0.10.5 are only:

@bruits/satteri-linux-x64-gnu
@bruits/satteri-linux-arm64-gnu
@bruits/satteri-linux-x64-musl
@bruits/satteri-linux-arm64-musl
@bruits/satteri-darwin-x64
@bruits/satteri-darwin-arm64
@bruits/satteri-win32-x64-msvc
@bruits/satteri-win32-arm64-msvc
@bruits/satteri-wasm32-wasi

There is no android-arm64 among them. However, satteri's binding loader includes an Android branch and a WASI fallback:

if (process.platform === 'android') {
  if (process.arch === 'arm64') {
    try { return require('./satteri_napi.android-arm64.node') } catch (e) { ... }
  }
}
...
if (!nativeBinding || forceWasi) {
  try {
    wasiBinding = require('@bruits/satteri-wasm32-wasi')
    nativeBinding = wasiBinding
  } catch (err) { ... }
}

Therefore, using the WASI package directly is sufficient; there is no need to compile an Android native module.

Fix

Install the WASI fallback:

pnpm add -D @bruits/satteri-wasm32-wasi@0.10.5

After installation, satteri can find the WASI binding, but reports a second error:

Error: UVWASI_EACCES, uvwasi_init

The cause is that WASI initialization uses / as the preopen:

const __rootDir = __nodePath.parse(process.cwd()).root
const __wasi = new __nodeWASI({
  version: 'preview1',
  env: process.env,
  preopens: {
    [__rootDir]: __rootDir,
  }
})

Android does not allow preopening the root directory, so change it to process.cwd():

pnpm patch @bruits/satteri-wasm32-wasi@0.10.5

Edit the temporary directory output by pnpm:

node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5/satteri_napi.wasi.cjs

-const __rootDir = __nodePath.parse(process.cwd()).root
+const __rootDir = process.cwd()

node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5/wasi-worker.mjs

-const __rootDir = parse(process.cwd()).root;
+const __rootDir = process.cwd();

Commit the patch:

pnpm patch-commit node_modules/.pnpm_patches/@bruits/satteri-wasm32-wasi@0.10.5

The following is ultimately generated in the repository:

patches/@bruits__satteri-wasm32-wasi@0.10.5.patch

Notes

pnpm patch-commit sometimes displays Already up to date, but the files in the installed node_modules are still the old ones. Do not try to solve this with pnpm install --force; just delete and reinstall:

rm -rf node_modules
pnpm install --frozen-lockfile

Verify that Sätteri can load:

node -e "
const { createRequire } = require('module');
const r = createRequire(process.cwd() + '/node_modules/.pnpm/satteri@0.10.5/node_modules/satteri/index.js');
const m = r('satteri');
console.log('satteri OK', Object.keys(m).length);
"

It outputs satteri OK 34, accompanied by an ExperimentalWarning: WASI is an experimental feature, which is normal.


2. Pagefind Lacks an Android Build (If Pagefind Is Used)

Symptom

astro build has already completed, but the postbuild stage fails:

$ pagefind --site dist
Failed to install either of [pagefind_extended, pagefind].
Most likely the platform android-arm64 is not yet a supported architecture.

Diagnosis

pagefind/lib/resolveBinary.js directly concatenates the package name based on process.platform:

const cpu = process.env.npm_config_arch || os.arch();
const platform = process.platform === "win32" ? "windows" : process.platform;

for (const execname of execnames) {
  const executable = platform === "windows" ? `${execname}.exe` : execname;
  try {
    return require.resolve(`@pagefind/${platform}-${cpu}/bin/${executable}`);
  } catch (e) {}
}

There is no @pagefind/android-arm64.

However, the pagefind_extended in @pagefind/linux-arm64 is an aarch64 binary statically linked against musl:

ELF 64-bit LSB executable, ARM aarch64, version 1 (SYSV),
statically linked, stripped

It can be executed directly on Termux, without proot / glibc-runner. Tested:

./package/bin/pagefind_extended --version
# pagefind 1.5.2

./package/bin/pagefind_extended --site dist
# Indexed 21 pages

Therefore, only two things need to be solved:

  1. Make pnpm install @pagefind/linux-arm64 on Android;
  2. Make the Pagefind wrapper look for linux-arm64 on Android instead of android-arm64.

Fix A: Make pnpm Install the linux-arm64 Optional Package

Add the following to pnpm-workspace.yaml:

supportedArchitectures:
  os:
    - current
    - linux
  cpu:
    - current
  libc:
    - current

This way, pnpm will also link in optional packages with os: ["linux"] and cpu: ["arm64"]. On Android arm64, the following will be installed:

node_modules/.pnpm/@pagefind+linux-arm64@1.5.2/

Side effect: pnpm 11.0.9 will also install the linux-arm64 gnu/musl variants of other packages (sharp, rolldown, biome, lightningcss, oxc, etc.), making node_modules about 680MB. This is an installation size issue and does not affect the packages actually loaded on Android.

Fix B: Make Pagefind Recognize Android

pnpm patch pagefind@1.5.2

Edit node_modules/.pnpm_patches/pagefind@1.5.2/lib/resolveBinary.js:

-const platform = process.platform === "win32" ? "windows" : process.platform;
+const platform =
+  process.platform === "win32"
+    ? "windows"
+    : process.platform === "android"
+      ? "linux"
+      : process.platform;

Commit:

pnpm patch-commit node_modules/.pnpm_patches/pagefind@1.5.2

Generate:

patches/pagefind@1.5.2.patch

This mapping does not change behavior on non-Android platforms.

Notes

Likewise, do not use pnpm install --force. Previously tested, it installs the optionalDependencies of all platforms (Windows, macOS, Linux x64/mips, etc.), directly filling up the disk.

When the patch does not take effect:

rm -rf node_modules
pnpm install --frozen-lockfile

Verify:

./node_modules/.bin/pagefind --version
# pagefind 1.5.2

./node_modules/.bin/pagefind --site dist
# Indexed 21 pages

3. Final Verification

pnpm build

Actual results:

astro check: 0 errors / 0 warnings
astro build: 48 page(s) built
pagefind:    Indexed 21 pages
pnpm test

Actual results:

tests 13
pass 13
fail 0

build assertions passed: 21 indexed pages, 20 default RSS items
pnpm lint
# Checked 79 files. No fixes applied.

Both pnpm dev --host 127.0.0.1 and pnpm preview --host 127.0.0.1 return HTTP 200. Astro 7's dev/preview run in the background; to stop them:

pnpm exec astro dev stop
pnpm exec astro preview stop

If you enjoyed this, leave a comment~