SQLite-WASM Prepare Script Overwrites Code with Official Release During Git Installation

Issue Overview: Prepare Script Triggers Unintended SQLite.org Release Download During Git-Based Installation

The SQLite-WASM package includes a prepare script in its package.json that downloads and extracts the latest official SQLite release from sqlite.org during installation when using Git-based sources. This behavior overwrites local code modifications or branch-specific changes when installing via npm or yarn from a Git repository. The core conflict arises from the interaction between npm/yarn lifecycle scripts and the SQLite-WASM build process:

1. Lifecycle Script Conventions: npm/yarn execute the prepare script automatically when installing packages from Git repositories to handle pre-publication tasks like compiling binaries or transpiling code.
2. SQLite-WASM Build Chain: The project’s prepare script invokes a custom build process that fetches the latest SQLite amalgamation from sqlite.org, bypassing the repository’s local source code.
3. Version Control Collision: Developers expecting to test forks or branches instead receive the latest stable SQLite release, creating discrepancies between the installed codebase and the Git commit referenced in lockfiles (e.g., yarn.lock).

This issue does not affect installations from the npm registry, where pre-packaged tarballs omit lifecycle scripts by default. The problem is isolated to Git-based workflows, where the prepare script executes post-installation. The overwrite mechanism invalidates local development efforts and complicates version pinning for downstream consumers relying on repository checkouts.

Root Causes: npm Lifecycle Script Misconfiguration and Build Process Assumptions

Three primary factors explain why the SQLite-WASM prepare script behaves counterintuitively during Git-based installations:

Cause 1: Lifecycle Script Timing in Git-Based Installs

npm/yarn treat Git-sourced packages as unpackaged source code, triggering prepare after cloning the repository but before finalizing the installation. This contrasts with registry-sourced installs, where prepare runs only during prepublish (when authors run npm publish). The SQLite-WASM maintainers likely intended prepare to run during official packaging but did not anticipate its execution in Git-based workflows.

Cause 2: Hardcoded Dependency on sqlite.org Artifacts

The prepare script delegates to bin/index.js, which programmatically downloads the latest SQLite amalgamation from sqlite.org. This design assumes the local repository lacks prebuilt binaries or that such binaries should always be refreshed from canonical sources. However, this violates expectations when installing from forks or branches where developers modify SQLite integration logic.

Cause 3: Maintainer Toolchain Disconnect

The SQLite team explicitly states they do not use Node.js internally, relying on external contributors for npm integration. This creates a blind spot for edge cases in npm/yarn’s script execution model, particularly around Git-based installs. The prepare script’s behavior reflects a packaging-time optimization (ensuring latest SQLite code) that inadvertently becomes destructive at install-time for Git users.

Resolution Strategy: Conditional Script Execution and Build Pipeline Adjustments

Step 1: Audit npm Lifecycle Script Dependencies

Examine the package.json scripts section to identify which tasks depend on external resources. The offending script chain is:

{
  "scripts": {
    "prepare": "npm run build",
    "build": "node bin/index.js"
  }
}

bin/index.js contains logic to download SQLite releases. Disentangling this from prepare requires conditional execution based on installation context.

Step 2: Isolate Git Install Behavior with Environment Variables

Modify the prepare script to skip SQLite.org downloads when installing from Git. npm/yarn set environment variables during installation:

• npm_config_from_git=true indicates Git-based installs.
• npm_package_resolved contains registry tarball URLs (absent in Git installs).

Rewrite the prepare script as:

{
  "scripts": {
    "prepare": "if [ -z \"$npm_config_from_git\" ]; then npm run build; else echo 'Skipping SQLite.org download for Git install'; fi"
  }
}

This skips the build script (and thus sqlite.org downloads) when installing from Git.

Step 3: Decouple SQLite Amalgamation Fetching from Build

Move the amalgamation download to a separate script (e.g., download-sqlite) invoked explicitly during packaging:

{
  "scripts": {
    "download-sqlite": "node bin/index.js --download",
    "build": "echo 'Build using local SQLite files'",
    "prepack": "npm run download-sqlite && npm run build"
  }
}

The prepack script runs before creating npm registry tarballs, ensuring official releases include the latest SQLite code. Git installs bypass prepack, preserving local modifications.

Step 4: Document Fork Maintenance Requirements

Update the project’s README.md to clarify that Git-based installations require manual SQLite amalgamation management. Contributors modifying SQLite integration must:

1. Run npm run download-sqlite to refresh amalgamation files.
2. Commit updated files to their fork if targeting SQLite version changes.

Step 5: Validate with Integration Tests

Add CI/CD checks to verify both registry and Git install behaviors:

• Registry Test: Ensure prepack downloads amalgamations and includes them in published packages.
• Git Test: Clone a test fork, install via npm install <fork-url>, and confirm no HTTP requests to sqlite.org occur.

Alternative Fix: .npmrc Configuration Overrides

Advanced users can disable prepare script execution globally or per-project via .npmrc:

# Global disable
ignore-scripts=true  
# Per-project disable
npm install --ignore-scripts https://github.com/grantcox/sqlite-wasm.git  

This bypasses the problematic script but requires manual intervention, making it a temporary workaround rather than a upstream solution.

This guide systematically addresses the conflict between npm/yarn lifecycle rules and SQLite-WASM’s build pipeline, ensuring Git-based installations respect local code while preserving official release integrity. By aligning script triggers with intended use cases and documenting contributor expectations, maintainers eliminate unintended overwrites without sacrificing build automation.