@haxtheweb/haxcms-nodejs
v26.8.1
Published
HAXcms single and multisite nodejs server, api, and administration
Maintainers
Readme
HAXcms with nodejs backend
Start the server in any HAXsite or HAXcms instance

Run commands
npm install
npm startVisit http://localhost:3000 if it doesn't automatically open
API conformance testing
Run endpoint conformance checks against src/openapi/site-spec.yaml:
npm run test:api-conformanceThe runner creates an isolated runtime workspace, then bootstraps a real site via API before endpoint checks run.
- The first bootstrap step calls
createSiteand generates a runtime site name:haxcms-test-harness-{timestampStartOfTest}
- All conformance calls then run against that real site path.
- Optional runtime login override values:
HAXCMS_TEST_USERNAMEHAXCMS_TEST_PASSWORD
Runtime credential overrides are also supported in-process via globals:
globalThis.HAXCMS_RUNTIME_CREDENTIALS = { username, password }globalThis.HAXCMS_RUNTIME_USERNAMEglobalThis.HAXCMS_RUNTIME_PASSWORD
Current coverage snapshot
Current automated test coverage in this repository is the API conformance suite:
- Suite file:
test/api-conformance/site-spec.conformance.test.cjs - Script:
npm run test:api-conformance - Additional test scripts/suites are not currently wired in
package.json
The suite currently validates:
- Discovery/spec endpoints:
getSiteApiDiscovery,getSiteOpenApi,getSiteOpenApiJson,getSiteOpenApiYaml,getApiCatalog
- Site/content graph endpoints:
getSiteSummary,listEntityDescriptors,listSchemas,listItems,getItemByIdOrSlug,listContent,getContentByIdOrSlug,listTags,searchContent
- Component and metadata endpoints:
listCustomElements,getCustomElementByName,listBlocks,getBlockByName,getBlockUsage,listRegions,getRegionByName
- Theme/report/view/analytics endpoints:
listThemes,getActiveTheme,getThemeByName,listReports,getReportByName,getAnalyticsCapabilities,listViews,getViewById,getViewResults,listDisplaysAlias,getDisplayResultsAlias
- Secured file and revision endpoints:
listFiles,createFile,getFileByUuid,updateFileByUuid,deleteFileByUuid,listItemRevisions
Behavior coverage in the same suite includes:
- OpenAPI response/schema conformance checks
- Auth matrix checks for secured routes (no auth, bearer-only, invalid site token, valid site token)
- Boundary/error checks (missing required params, invalid ids/slugs, pagination/query bounds)
- Representation/header checks (
json,yaml,xml,md,htmlwhere supported) - End-to-end file lifecycle checks (create → list/find → get → update → delete)
Temporary known skip in the suite:
getApiCatalog returns linkset payload- Reason: runtime
/.well-known/api-catalogfixture behavior is still being finalized
- Reason: runtime
MCP and deployment profiles
- MCP policy defaults are controlled via
_config/config.json. - New installs include:
deploymentProfile:single-site,self-hosted-multi-site, orhaxiam-managedmcp.enabled: global MCP togglemcp.readOnly: write-protection toggle for future MCP write tools
- Default behavior:
haxiam-manageddefaults MCP to disabled unless explicitly enabled.- Other profiles default to MCP enabled with read-only mode on.
Get Help / Issues / Support
- Discord Channel - https://discord.gg/EKYJAjqGhf
- Unified issue queue - https://github.com/haxtheweb/issues/issues
- Using Merlin directly in any HAX spaces and type "Issue" to jump start a report!
Watch and Learn more about HAX here:
- Try Hax: https://hax.cloud
- HAXCellence https://haxtheweb.org/what-is-hax
- Youtube channel - https://www.youtube.com/@haxtheweb
Related links and tech

