Fix ERR_UNKNOWN_FILE_EXTENSION error when running TypeScript files with ts-node in ESM mode

[Copilot]

Problem

When attempting to start the application with yarn start or yarn start-backend, the build fails with the following error:

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /opt/codexdocs/src/backend/app.ts
    at new NodeError (node:internal/errors:405:5)
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:136:11)
    ...

This error occurs because the project has "type": "module" in package.json, which enables ES modules mode in Node.js. When running TypeScript files with ts-node in ESM mode, Node.js doesn't recognize the .ts file extension without proper loader configuration.

Solution

This PR fixes the issue by configuring Node.js to use the ts-node ESM loader when executing TypeScript files:

1. nodemon.json - Added execMap configuration to tell nodemon how to execute .ts files:

   "execMap": {
     "ts": "node --loader ts-node/esm"
   }

2. package.json - Updated the build-static script to use the loader directly since it bypasses nodemon:

   "build-static": "node --loader ts-node/esm src/backend/app.ts build-static ..."

Testing

Verified that the following commands now work correctly:

• ✅ yarn start - Both backend server and frontend webpack build successfully
• ✅ yarn start-backend - Backend server starts on port 3000
• ✅ yarn build-static - Executes without errors (fails with expected config error, not file extension error)

The application now starts successfully and displays:

┌──────────────────────────────────┐
│ CodeX Docs server is running     │
│                                  │
│ Main page: http://localhost:3000 │
└──────────────────────────────────┘

Note: The ExperimentalWarning about --experimental-loader is expected behavior from Node.js and doesn't affect functionality. The test script (yarn test) already had proper loader configuration via ts-mocha and continues to work correctly.

Closes #[issue_number]

Original prompt

---

This section details on the original issue you should resolve

<issue_title>ERR_UNKNOWN_FILE_EXTENSION Installation / Build Error</issue_title>
<issue_description>I'm attempting to build and install on Ubuntu 22.04.5 LTS

root@www:/opt/codexdocs# uname -an
Linux www 5.15.0-156-generic #166-Ubuntu SMP Sat Aug 9 00:02:46 UTC 2025 x86_64 x86_64 x86_64 GNU/Linux

root@www:/opt/codexdocs# npm -v
10.8.2
root@www:/opt/codexdocs# node -v
v18.20.8

With 'yarn && yarn start' I get the following error:

[0] [nodemon] starting ts-node src/backend/app.ts -c docs-config.yaml -c docs-config.local.yaml
[0] TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /opt/codexdocs/src/backend/app.ts
[0] at new NodeError (node:internal/errors:405:5)
[0] at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:136:11)
[0] at defaultGetFormat (node:internal/modules/esm/get_format:182:36)
[0] at defaultLoad (node:internal/modules/esm/load:101:20)
[0] at nextLoad (node:internal/modules/esm/hooks:864:28)
[0] at load (/opt/codexdocs/node_modules/ts-node/dist/child/child-loader.js:19:122)
[0] at nextLoad (node:internal/modules/esm/hooks:864:28)
[0] at Hooks.load (node:internal/modules/esm/hooks:447:26)
[0] at MessagePort.handleMessage (node:internal/modules/esm/worker:196:24)
[0] at [nodejs.internal.kHybridDispatch] (node:internal/event_target:786:20) {
[0] code: 'ERR_UNKNOWN_FILE_EXTENSION'
[0] }
[0] [nodemon] app crashed - waiting for file changes before starting...</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #326

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.