diff --git a/dev-docs/reference/LEARNINGS-RUNTIME.md b/dev-docs/reference/LEARNINGS-RUNTIME.md new file mode 100644 index 0000000..77c0bc7 --- /dev/null +++ b/dev-docs/reference/LEARNINGS-RUNTIME.md @@ -0,0 +1,472 @@ +# OpenNoodl Runtime Architecture - Deep Dive + +This document captures learnings about the Noodl runtime system, specifically how `noodl-runtime` and `noodl-viewer-react` work together to render Noodl projects. + +--- + +## Overview + +The Noodl runtime is split into two main packages: + +| Package | Purpose | +|---------|---------| +| `noodl-runtime` | Core node execution, data flow, graph processing | +| `noodl-viewer-react` | React-based rendering of visual nodes | + +The **editor** uses these packages to render the preview, and **deployed projects** use them directly in the browser. + +--- + +## How React is Loaded + +**Key Insight:** React is NOT an npm dependency of noodl-viewer-react. Instead, it's loaded as external UMD scripts. + +### Webpack Configuration +```javascript +// webpack-configs/webpack.common.js +module.exports = { + externals: { + react: 'React', + 'react-dom': 'ReactDOM' + } +}; +``` + +This means: +- `import React from 'react'` actually references `window.React` +- `import ReactDOM from 'react-dom'` references `window.ReactDOM` + +### Where React Bundles Live +``` +packages/noodl-viewer-react/static/shared/ +├── react.production.min.js # React UMD bundle +└── react-dom.production.min.js # ReactDOM UMD bundle +``` + +These are loaded via `