HAXcms with nodejs backend

Start the server in any HAXsite or HAXcms instance

Run commands

npm install
npm start

Visit 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-conformance

The runner creates an isolated runtime workspace, then bootstraps a real site via API before endpoint checks run.

• The first bootstrap step calls createSite and 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_USERNAME
  • HAXCMS_TEST_PASSWORD

Runtime credential overrides are also supported in-process via globals:

• globalThis.HAXCMS_RUNTIME_CREDENTIALS = { username, password }
• globalThis.HAXCMS_RUNTIME_USERNAME
• globalThis.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, html where 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-catalog fixture behavior is still being finalized

MCP and deployment profiles

• MCP policy defaults are controlled via _config/config.json.
• New installs include:
  • deploymentProfile: single-site, self-hosted-multi-site, or haxiam-managed
  • mcp.enabled: global MCP toggle
  • mcp.readOnly: write-protection toggle for future MCP write tools
• Default behavior:
  • haxiam-managed defaults MCP to disabled unless explicitly enabled.
  • Other profiles default to MCP enabled with read-only mode on.

Get Help / Issues / Support

• Discord Channel - https://bit.ly/hax-discord
• 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

• NPM Package list
• HAXcms (NodeJS)
• HAXcms (PHP)
• Storybook docs
• HAX [dot] PSU
• HAX doc site
• HAX + 11ty