feat: use a custom build js step instead of all the dependencies (#53)

Reviewed-on: #53

README.md

@@ -62,4 +62,49 @@ In this example:
 ## Advanced Usage
 
 Please note that you can easily filter your deployment branches in the push action.
-Multiple deploy steps or jobs are recomended for mulitple deployments.
+Multiple deploy steps or jobs are recomended for mulitple deployments.
+
+## Development & Build
+
+This project includes a build step to prepare the action for use.
+
+### Why a Build Step?
+
+We use a build step to compile the JavaScript code and its dependencies into a single, self-contained file (`dist/index.js`). This approach is chosen for the following reasons:
+1.  **Zero-configuration at Runtime:** By bundling everything, the action runner doesn't need to run `npm install`, which speeds up the action execution.
+2.  **Reliability:** It guarantees that the exact versions of dependencies tested during development are used in the action, avoiding potential issues with version updates or missing packages.
+3.  **Standard Practice:** This is a recommended practice for JavaScript-based GitHub/Gitea Actions.
+
+### The Tool: @vercel/ncc
+
+We chose [`@vercel/ncc`](https://github.com/vercel/ncc) as the compiler because:
+- It is designed specifically for compiling Node.js modules into a single file.
+- It handles native dependencies and dynamic requires intelligently.
+- It is zero-config, making the setup simple and maintainable.
+
+### How to Build
+
+If you modify `index.js` or change dependencies, you must rebuild the project before committing:
+
+```bash
+npm install
+npm run build
+```
+
+This will update the `dist/index.js` file, which should be committed to the repository.
+
+### Cross-Platform Compatibility
+
+To ensure this action runs on all platforms (including ARM devices like Raspberry Pi), we explicitly exclude optional native dependencies (`utf-8-validate` and `bufferutil`) from the build. This forces the underlying `ws` library to use its pure JavaScript fallback implementation.
+
+### Build Protocol
+
+| Metric | Status / Value |
+| :--- | :--- |
+| **Last Build** | Saturday, December 27, 2025 |
+| **Build Tool** | `@vercel/ncc` |
+| **Target Runtime** | Node.js 20 |
+| **Artifact** | `dist/index.js` (Self-contained) |
+| **Native Binaries** | None (Excluded for cross-platform support) |
+| **Compatibility** | Linux (x64/ARM), Windows, macOS |
+| **Build Status** | ✅ Success |