mirror of
https://github.com/acamarata/solar-spa.git
synced 2026-07-01 03:14:31 +00:00
125 lines
4.2 KiB
Markdown
125 lines
4.2 KiB
Markdown
# Bundler Compatibility
|
|
|
|
solar-spa works out of the box in every tested environment. No special configuration is required.
|
|
|
|
## How it works
|
|
|
|
The WASM binary is inlined as base64 inside `wasm/spa-module.js` (compiled with Emscripten's `SINGLE_FILE` flag). There is no external `.wasm` file to resolve, fetch, or copy. The package is just JavaScript files, and every bundler knows how to handle JavaScript. See [WebAssembly in npm Packages](WebAssembly-in-npm-Packages) for a deeper discussion of why this approach works.
|
|
|
|
## Tested environments
|
|
|
|
### Node.js (18+)
|
|
|
|
Both ES module and CommonJS imports work:
|
|
|
|
```js
|
|
// ESM
|
|
import { spa } from 'solar-spa';
|
|
|
|
// CommonJS
|
|
const { spa } = require('solar-spa');
|
|
```
|
|
|
|
The `package.json` exports map routes `import` to `dist/index.mjs` and `require()` to `dist/index.cjs`. Full TypeScript declarations are provided for both formats.
|
|
|
|
### Webpack 5
|
|
|
|
No configuration needed. Webpack resolves the package through the exports map and bundles the JavaScript files normally. The base64-encoded WASM is just a string literal inside the bundle.
|
|
|
|
```js
|
|
// webpack project
|
|
import { spa } from 'solar-spa';
|
|
const result = await spa(new Date(), 40.7128, -74.006);
|
|
```
|
|
|
|
If your Webpack config includes rules for `.wasm` files, they will not interfere because solar-spa does not import or reference any `.wasm` files.
|
|
|
|
### Vite
|
|
|
|
Works without configuration. Vite handles the CJS-to-ESM interop through its pre-bundling step (esbuild), and the inlined WASM is transparent to the build pipeline.
|
|
|
|
```js
|
|
// vite project
|
|
import { spa } from 'solar-spa';
|
|
```
|
|
|
|
### Next.js (Pages Router)
|
|
|
|
Works in both API routes (server-side) and `getServerSideProps`. The WASM initializes on the server without filesystem access issues because the binary is inlined.
|
|
|
|
```js
|
|
// pages/api/sun.js
|
|
import { spa } from 'solar-spa';
|
|
|
|
export default async function handler(req, res) {
|
|
const result = await spa(new Date(), 40.7128, -74.006, { timezone: -4 });
|
|
res.json(result);
|
|
}
|
|
```
|
|
|
|
### Next.js (App Router)
|
|
|
|
Works in server components, route handlers, and middleware. The same inlining approach avoids the edge runtime file resolution problems that affect packages with separate `.wasm` files.
|
|
|
|
```js
|
|
// app/api/sun/route.js
|
|
import { spa } from 'solar-spa';
|
|
|
|
export async function GET() {
|
|
const result = await spa(new Date(), 40.7128, -74.006, { timezone: -4 });
|
|
return Response.json(result);
|
|
}
|
|
```
|
|
|
|
### Browser (direct)
|
|
|
|
If you are not using a bundler, use a CDN that provides ESM builds:
|
|
|
|
```html
|
|
<script type="module">
|
|
import { spa } from 'https://esm.sh/solar-spa';
|
|
const result = await spa(new Date(), 40.7128, -74.006);
|
|
console.log(result.zenith);
|
|
</script>
|
|
```
|
|
|
|
### Web Workers
|
|
|
|
The Emscripten output includes `worker` in its environment list. WASM initialization works inside a Web Worker without modification:
|
|
|
|
```js
|
|
// worker.js
|
|
import { spa } from 'solar-spa';
|
|
|
|
self.addEventListener('message', async (event) => {
|
|
const { date, lat, lon } = event.data;
|
|
const result = await spa(new Date(date), lat, lon);
|
|
self.postMessage(result);
|
|
});
|
|
```
|
|
|
|
## Common questions
|
|
|
|
### Do I need to configure `wasm` asset handling in my bundler?
|
|
|
|
No. There is no `.wasm` file in the package. The binary is a base64 string inside a `.js` file.
|
|
|
|
### Will this work with tree-shaking?
|
|
|
|
The package exports individual named functions. Bundlers that support tree-shaking will include only the functions you import. However, the WASM module is initialized as a whole, so the binary size is fixed regardless of which functions you use.
|
|
|
|
### Is there a browser-only build?
|
|
|
|
The same build works in both Node.js and browsers. The Emscripten output detects the environment at runtime (`ENVIRONMENT='node,web,worker'`).
|
|
|
|
### What about Content Security Policy (CSP)?
|
|
|
|
The WASM binary is decoded from base64 and compiled via `WebAssembly.instantiate()`. If your CSP restricts `wasm-eval` or `wasm-unsafe-eval`, you will need to add the appropriate directive. This is a general WASM requirement, not specific to this package.
|
|
|
|
### What is the minimum browser version?
|
|
|
|
Any browser that supports WebAssembly: Chrome 57+, Firefox 52+, Safari 11+, Edge 16+. This covers all browsers released since 2017.
|
|
|
|
---
|
|
|
|
[Home](Home) · [WebAssembly in npm Packages](WebAssembly-in-npm-Packages) · [Architecture](Architecture)
|