Skip to content

The VS Code of video editing, built for agents.

TypeScript

Update project and module documentation for npm package handling

konstantin-paulus05bbc303ea5b
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index 9af88d64..5b4b5197 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -421,9 +421,10 @@ export default function Project() {
mount, in dependency order.
- Solid is fully available while mounting: \`<For>\`, \`<Show>\`, \`createMemo\`, and
\`useTicker()\` for values that follow the playhead.
-- Any npm package can be imported without installing it: bare specifiers resolve
- from a CDN at runtime. Add one as a dev dependency (\`npm i -D three\`) only to
- get its types.
+- npm packages work as they normally do. The folder is a real npm package, so
+ \`npm i three\` in it is all it takes: anything in \`node_modules\` is resolved
+ and bundled, subpath imports included. A composition runs in a browser
+ context, so a package that needs Node APIs will not bundle.
Types are stripped at compile time and never checked, so typecheck the project
yourself with \`npx tsc --noEmit\`.
diff --git a/reference/jsx/module.md b/reference/jsx/module.md
index 2b2b0f0b..b8a986c3 100644
--- a/reference/jsx/module.md
+++ b/reference/jsx/module.md
@@ -20,27 +20,11 @@ The component receives no props; which document node each rendered root maps ont
Imports resolve by category:
- **Host modules** (marked external at compile time, resolved in-app so the project shares the editor's reactive runtime): `solid-js`, `solid-js/store`, `@diffusionstudio/jsx`. These must be the editor's own instance and never come from anywhere else.
-- **Userland packages** — any other bare specifier (`three`, `gsap`, `d3-scale`, …). These are **not installed and not bundled**: the CLI rewrites them to a CDN URL (default `https://esm.sh/<specifier>`, so `three/examples/jsm/loaders/GLTFLoader.js` becomes `https://esm.sh/three/examples/jsm/loaders/GLTFLoader.js`) and the renderer imports them natively at runtime. Any npm package works without a `node_modules`, so this works in a packaged app too. The package's own transitive deps are resolved by the CDN. Libraries must be browser-compatible (no Node builtins).
-- **Local and URL imports**: relative/absolute paths (`./helper`, local JSON) are resolved on disk and bundled as before; explicit `https://…` imports pass through to the renderer untouched.
+- **Userland packages** — any other bare specifier (`three`, `gsap`, `d3-scale`, …). A project folder is a real npm package, so these work as they normally do: install one (`npm i three`) and esbuild resolves it from the project's `node_modules` and bundles it into the compiled module, subpath imports and `exports` maps included. Nothing is installed for you and there is no CDN fallback — a specifier that does not resolve fails the compile with `Could not resolve "three"`, and the canvas keeps the last good render. Libraries must be browser-compatible (no Node builtins); sources under `node_modules` skip the JSX transform, so a package must ship compiled JavaScript rather than raw JSX.
+- **Local imports**: relative/absolute paths (`./helper`, local JSON) are resolved on disk and bundled. Static `https://…` imports are **not** supported — they survive bundling as a require the renderer cannot satisfy, and fail at mount.
- The module executes **inside the editor process**, unsandboxed. This is local tooling with a local trust model, the same trust as running the CLI itself. Only effects made through the JSX runtime are part of the document (and its undo history); anything else the module does is unsupported.
- Solid's control flow (`<For>`, `<Show>`, `<Index>`, `<Switch>`) and primitives (`createSignal`, `createMemo`, …) are fully available during mount. See [lifecycle.md](./lifecycle.md) for what happens after mount.
-### Import map (`dapi.config.json`)
-
-A `dapi.config.json` in the working directory pins versions or redirects userland specifiers — for reproducible mounts, a self-hosted mirror, or a local vendored copy. Exact keys match a specifier; a trailing-slash key maps its subpaths (longest prefix wins):
-
-```json
-{
- "cdnBase": "https://esm.sh",
- "imports": {
- "three": "https://esm.sh/[email protected]",
- "three/": "https://esm.sh/[email protected]/"
- }
-}
-```
-
-`cdnBase` overrides the default CDN for anything not in `imports`. The `DAPI_CDN_BASE` and `DAPI_IMPORT_MAP` (a JSON object) env vars override for one-offs. An unpinned specifier resolves to the CDN's latest.
-
## Types and tooling
`@diffusionstudio/jsx` ships the JSX namespace (which types the camelCase composition tags), for editor IntelliSense and typechecking in a project folder:
@@ -56,4 +40,4 @@ A `dapi.config.json` in the working directory pins versions or redirects userlan
The CLI does not typecheck; types are stripped at compile time. Run `tsc --noEmit` in the project folder for type safety.
-Userland packages resolve from a CDN at runtime, so they need no runtime install, but the editor still wants their type declarations. For IntelliSense on a library, install it (or its `@types/…`) as a **dev-only** dependency (`npm i -D three`); it is used purely for typechecking and never bundled or shipped.
+Installing a userland package gives it both its runtime code and its types. A package that ships no declarations of its own needs its `@types/…` alongside it (`npm i -D @types/three`). `@diffusionstudio/jsx` and `solid-js` are the exception: they are declared in the scaffolded `package.json` for types only, since the compiler always keeps them external and the running composition uses the app's own instance.