Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Spiceflow
✓ import { Spiceflow } from 'spiceflow'
✗ import Spiceflow from 'spiceflow'
Spiceflow is a named export, not a default export. Always use named import syntax.
json
✓ import { json } from 'spiceflow'
✗ import { json } from 'spiceflow/json'
The json helper is exported from the main package, not a subpath.
parseFormData
✓ import { parseFormData } from 'spiceflow'
✗ const { parseFormData } = require('spiceflow')
Spiceflow is ESM-only; using require() will fail. Use import instead.
Shows how to create a basic Spiceflow app with two routes, using the json helper for typed responses and Zod for optional schema validation.
import { Spiceflow, json } from 'spiceflow';
import { z } from 'zod';
const app = new Spiceflow()
.get('/hello', () => {
return json({ message: 'Hello, world!' })
})
.post('/echo', async ({ request }) => {
const body = await request.json();
return json(body, { status: 201 });
});
// Start the server (assumes Node.js or Bun)
app.listen(3000, () => {
console.log('Server running on http://localhost:3000');
});
Debug
Known issues
breakingSpiceflow v1.19.0-rsc.x is a pre-release and may contain breaking changes compared to v1.18.0 stable.fixPin to v1.18.0 for production stability until v1.19.0 is released as stable.
affects: >=1.19.0-rsc.0 <2.0.0
gotchaOn Cloudflare Workers, using require() will throw 'require is not defined'. This was fixed in v1.19.0-rsc.7.fixUpdate to v1.19.0-rsc.7 or later, or avoid using require() in worker environments.
affects: >=1.18.0 <1.19.0-rsc.7
gotchaThe json() helper throws a schema validation error if the returned data does not match the route's inferred response schema.fixEnsure all routes using json() return data that matches the response schema, or handle validation errors.
affects: >=1.19.0-rsc.1
deprecatedUsing Spiceflow without registering the app type via SpiceflowRegister will cause Link and other typed helpers to fall back to string parameters.fixRegister the app type with SpiceflowRegister to enable full type safety on client helpers.
affects: >=1.19.0-rsc.3
Errors
Common errors & fixes
require is not defined
Using CommonJS require() in an ESM-only package (e.g., Cloudflare Workers).
fixReplace require() with import statements. For Cloudflare Workers, ensure your build process outputs ESM.
TypeError: Cannot destructure property 'Spiceflow' of ...
Default import used instead of named import.
fixChange 'import Spiceflow from "spiceflow"' to 'import { Spiceflow } from "spiceflow"'. Module not found: Can't resolve 'spiceflow' in ...
Missing dependency or incorrect import path when using subpath exports that don't exist.
fixInstall spiceflow: 'npm install spiceflow'. Ensure you import from 'spiceflow' not 'spiceflow/subpath' unless the subpath is documented.
Audit
Dependencies
@modelcontextprotocol/sdkoptionalPeer dependency for MCP integration