Local Development Workflow

This guide describes the recommended workflow for developing within the xPulse Ecosystem.

1. Prerequisites

• Node.js (v16+)
• The Monorepo is checked out.
• It is recommended to work within the _test_app to verify new features or fixes.

2. The Sync Mechanism

Since we work with actual node_modules (no symlinks to ensure maximum compatibility), changes in components/* must be mirrored into the node_modules of the test app.

Automatic Sync

When you start the test app, the sync is executed automatically:

1
cd _test_app
2
npm run dev

This runs node ../tools/sync-components.js in the background.

Manual Sync

You can trigger the sync manually at any time (from the project root):

1
node tools/sync-components.js

3. Development Mode (Live-Reload)

When the app is started with NODE_ENV=development, @xpulse/app automatically enables additional features:

1. Template-Cache Clearing: The @xpulse/template cache is cleared on every restart.
2. Watcher: The Node.js watcher monitors src/, xpulse.json, and src/templates/.
3. SSE-Live-Reload:
   • The server opens an SSE endpoint at /xpulse-watch.
   • A small script is automatically injected into every HTML response.
   • As soon as the server restarts (triggered by the watcher), the browser detects the disconnection and reloads the page automatically once the server is reachable again.

Running in Dev Mode

1
cd _test_app
2
# Uses the 'dev' script defined in package.json
3
npm run dev

Or manually:

1
NODE_ENV=development node --watch src --watch xpulse.json --watch src/templates src/index.js

4. Workflow Example: Changing a Component

1. Change code in components/xpulse-http/src/server.js.
2. Run node tools/sync-components.js (or restart the test app).
3. The changes are now available in _test_app/node_modules/@xpulse/http.
4. The test app's watcher notices the change (since node_modules are often ignored, it is recommended to "touch" the test app's index.js or use npm run dev if the watcher doesn't react).

5. Tips

• Logs: Use DEBUG=true for more detailed output during bootstrapping.
• Cache: If templates are not updated, check if NODE_ENV=development is set.