WebAssembly Node.js TypeScript Boilerplate

A modern, production-ready boilerplate for building Node.js applications with TypeScript and WebAssembly integration. This project demonstrates best practices for combining the performance of WebAssembly with the flexibility of Node.js and the type safety of TypeScript.
π Features
- WebAssembly Integration: Hand-crafted WebAssembly modules with TypeScript bindings
- Graceful Fallback: Automatic JavaScript fallback when WebAssembly is unavailable
- Mathematical Functions: Optimized implementations for:
- Addition and multiplication operations
- Fibonacci sequence calculation
- Performance Benchmarking: Built-in performance comparison between WebAssembly and JavaScript
- Type Safety: Full TypeScript support with strict type checking
- Modern Development: ES2020 target with modern JavaScript features
- Production Ready: Comprehensive error handling and logging
π Quick Start
Prerequisites
- Node.js v16 or higher
- npm or yarn package manager
- (Optional) WABT (WebAssembly Binary Toolkit) for custom WebAssembly modules
Installation
- Clone the repository:
git clone https://github.com/yuis-ice/wasm-boilerplate.git
cd wasm-boilerplate
- Install dependencies:
npm install
- Build the project:
npm run build
- Run the application:
npm start
Or build and run in one command:
npm run dev
π Project Structure
src/
βββ index.ts # Main application entry point
βββ wasmMath.ts # WebAssembly wrapper class with TypeScript bindings
βββ math.wat # WebAssembly module source (WAT format)
dist/ # Compiled output directory
βββ index.js # Compiled JavaScript
βββ wasmMath.js # Compiled WebAssembly wrapper
βββ math.wasm # Compiled WebAssembly binary (if WABT available)
.github/ # GitHub configuration
βββ ISSUE_TEMPLATE/ # Issue templates
βββ DISCUSSIONS.md # Discussions guidelines
βββ PULL_REQUEST_TEMPLATE.md
π οΈ Available Scripts
npm run build - Compile TypeScript and WebAssembly modules
npm run build:wasm - Compile WebAssembly modules only (requires WABT)
npm run build:full - Full build including WebAssembly compilation
npm start - Run the compiled application
npm run dev - Build and run in development mode
npm run clean - Clean the dist directory
π§ WebAssembly Integration
This project demonstrates how to integrate WebAssembly with Node.js and TypeScript:
WebAssembly Module
The WebAssembly module (math.wat) provides optimized mathematical functions:
add(a, b) - Addition of two integers
multiply(a, b) - Multiplication of two integers
fibonacci(n) - Calculate the nth Fibonacci number
TypeScript Wrapper
The WasmMath class provides a clean TypeScript interface to the WebAssembly module with:
- Type-safe method signatures
- Automatic initialization
- Graceful fallback to JavaScript implementation
- Error handling and validation
π Performance
The application includes built-in performance benchmarking to compare WebAssembly and JavaScript implementations. Generally, WebAssembly provides better performance for computation-intensive tasks, especially with larger datasets.
Example output:
--- Performance Test ---
WebAssembly fibonacci: 2.341ms
JavaScript fibonacci: 3.892ms
π¨ Development
Installing WABT (Optional)
For custom WebAssembly development, install the WebAssembly Binary Toolkit:
# Ubuntu/Debian
sudo apt update
sudo apt install wabt
# macOS (Homebrew)
brew install wabt
# or via npm
npm install -g wabt
Creating Custom WebAssembly Modules
- Write your module in WebAssembly Text format (
.wat)
- Compile using WABT:
wat2wasm module.wat -o module.wasm
- Load in TypeScript using the WebAssembly API
π€ Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Quick Contribution Steps
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Support
π·οΈ Keywords
nodejs typescript webassembly wasm boilerplate template performance mathematics
Made with β€οΈ by .fumiya.tsx