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–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
jsonApiSerializer
✓ import jsonApiSerializer from 'fortune-json-api'
✗ const jsonApiSerializer = require('fortune-json-api')
The primary export is the default serializer function. This package is primarily CommonJS-first, so direct ESM `import` might require Node.js's ESM compatibility layers or bundler configuration. The `require` syntax is shown in all documentation examples.
jsonApiSerializer
✓ const jsonApiSerializer = require('fortune-json-api')
This is the idiomatic CommonJS import shown in the official documentation and examples. The serializer is a default export.
This example sets up a basic Fortune.js server with the JSON API serializer, creating an HTTP listener that serves a 'users' and 'posts' resource type over a `/api` prefix.
const http = require('http');
const fortune = require('fortune');
const fortuneHTTP = require('fortune-http');
const jsonApiSerializer = require('fortune-json-api');
// Define your Fortune.js record types
const store = fortune({
user: {
email: String,
name: String,
posts: [Array('post'), 'author']
},
post: {
title: String,
content: String,
author: ['user', 'posts']
}
});
const listener = fortuneHTTP(store, {
serializers: [
// The `options` object here is optional.
[ jsonApiSerializer, { prefix: '/api', jsonSpaces: 2 } ]
]
});
const server = http.createServer((request, response) =>
listener(request, response)
.catch(error => {
console.error('API Error:', error);
response.writeHead(500, { 'Content-Type': 'application/vnd.api+json' });
response.end(JSON.stringify({ errors: [{ status: '500', title: 'Internal Server Error', detail: error.message }] }));
})
);
const port = process.env.PORT ?? 8080;
server.listen(port, () => console.log(`JSON:API server listening on http://localhost:${port}/api`));
// Example: How to interact (e.g., in another file or via curl)
/*
curl -X POST -H "Content-Type: application/vnd.api+json" -d '{
"data": {
"type": "users",
"attributes": {
"email": "test@example.com",
"name": "Test User"
}
}
}' http://localhost:8080/api/users
curl http://localhost:8080/api/users
*/
Debug
Known issues
breakingPrior to Fortune.js v1.0.0-rc.13, the JSON API serializer was bundled directly within the `fortune` package. This changed to an external module, `fortune-json-api`, requiring explicit installation and import for any projects migrating from very old `fortune` versions (pre-1.0.0-rc.13) to newer ones.fixEnsure `fortune-json-api` is installed (`npm install fortune-json-api`) and explicitly imported via `require('fortune-json-api')` or `import jsonApiSerializer from 'fortune-json-api'`. affects: <1.0.0-rc.13 of fortune, all versions of fortune-json-api
gotchaThis library is tightly coupled with `fortune` and `fortune-http`. Mismatched major versions of these peer dependencies can lead to unexpected behavior or runtime errors. Always check the `fortune-json-api`'s `package.json` for compatible peer dependency ranges.fixEnsure that `fortune` and `fortune-http` packages are installed with versions compatible with `fortune-json-api` as specified in its `package.json` peer dependencies.
affects: >=1.0.0
gotchaThe `prefix` option, if set to a path starting with `/`, will rewrite URLs relative to that prefix. For example, a prefix of `/api` will make requests for `/api/users/1` map to the `users` resource with ID `1`. Misunderstanding this behavior can lead to incorrect routing or URL generation.fixCarefully configure the `prefix` option to match your desired API routing strategy. If you need to handle multiple API versions or non-prefixed routes, ensure your `fortune-http` setup correctly dispatches to the right serializer/listener.
affects: >=1.0.0
gotchaThis package is primarily designed for CommonJS (`require`) environments, and all official examples use this syntax. While it might work with ESM via bundlers or Node.js's compatibility layers, explicit ESM support (e.g., named exports, `.mjs` files) is not documented, which can lead to import errors in pure ESM projects.fixFor CommonJS projects, use `const jsonApiSerializer = require('fortune-json-api')`. For ESM projects, if you encounter import issues, consider using `import jsonApiSerializer from 'fortune-json-api'` and ensuring your build system or Node.js runtime correctly handles CJS default exports. affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: require is not defined
Attempting to use `require()` in an ES Module environment (e.g., in a `.mjs` file or when `"type": "module"` is set in `package.json`) without a transpilation step.
fixChange `const jsonApiSerializer = require('fortune-json-api')` to `import jsonApiSerializer from 'fortune-json-api'`. Ensure your Node.js version supports ESM or configure a bundler like Webpack/Rollup if targeting older environments. TypeError: (0 , fortune_json_api_1.default) is not a function
Incorrectly importing a CommonJS default export in an ES Module context, often due to a mismatch in how transpilers or Node.js handle default exports from CJS modules.
fixTry `import * as jsonApiModule from 'fortune-json-api'; const jsonApiSerializer = jsonApiModule.default;` or simplify to `import jsonApiSerializer from 'fortune-json-api'` if your environment supports it. Often, setting `esModuleInterop: true` in `tsconfig.json` for TypeScript projects can also resolve this.
Error: Invalid JSON API payload
The incoming HTTP request body does not conform to the JSON API specification's structure or content rules, leading to validation failure by the serializer.
fixVerify that your client-side requests adhere strictly to the JSON API specification, especially regarding the `data`, `type`, `id`, `attributes`, and `relationships` keys in the request body. Common mistakes include wrong `Content-Type` header (should be `application/vnd.api+json`) or missing `data` wrapper.
Cannot find module 'fortune' or Cannot find module 'fortune-http'
The required peer dependencies `fortune` or `fortune-http` are not installed or are not resolvable in the current project's `node_modules`.
fixInstall the missing packages: `npm install fortune fortune-http`.
Audit
Dependencies
fortunerequiredRequired as the core data layer and ORM replacement that this serializer integrates with.
fortune-httprequiredRequired to handle the HTTP layer and integrate the serializer into the request/response cycle.