@crossworks/app-build 0.300.140 → 0.400.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +13 -3
- package/src/app-libraries.metafile.test.ts +60 -0
- package/src/app-libraries.test.ts +128 -0
- package/src/app-libraries.ts +81 -0
- package/src/build-runtime.ts +27 -0
- package/src/build.test.ts +259 -0
- package/src/canvas-runtime.ts +248 -0
- package/src/css.ts +10 -0
- package/src/index.ts +373 -43
- package/src/runtime-exports.fixture.ts +1 -0
- package/src/runtime-imports.test.ts +25 -0
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Builds the CANVAS runtime: the vendored, pinned, offline library set a
|
|
3
|
+
* Present canvas imports (docs/proposals/canvas-files.md section 6.1). Served
|
|
4
|
+
* by the brain from `/canvas-runtime/`, never from a CDN: some boxes block
|
|
5
|
+
* egress, a CDN would widen the frame CSP to third-party script hosts, and
|
|
6
|
+
* versions would drift.
|
|
7
|
+
*
|
|
8
|
+
* Each library becomes ONE content-hashed ESM file (`<entry>-<hash>.js`), so a
|
|
9
|
+
* canvas frame's import map is an address book only: the browser fetches a
|
|
10
|
+
* library when the canvas imports it, then caches it for good. Three.js addons
|
|
11
|
+
* import `three` through the same map, so a scene and its controls share one
|
|
12
|
+
* Three. Plotly ships only a classic browser build: it is copied as is, and a
|
|
13
|
+
* canvas loads it with a `<script src>`. reveal.js brings its stylesheet and
|
|
14
|
+
* themes. KaTeX's stylesheet and fonts already ride `/share-runtime/katex/`.
|
|
15
|
+
*
|
|
16
|
+
* Output: the files plus `manifest.json` ({ imports, exports, libs, assets }).
|
|
17
|
+
* The canvas frame route reads `imports` for its import map; `libs` names each
|
|
18
|
+
* library's pinned version (release notes, the save check of a later phase).
|
|
19
|
+
* Mini apps read a subset of the same files (app-libraries.ts): the app
|
|
20
|
+
* runtime build copies those `imports` into the app import map and their
|
|
21
|
+
* `exports` into the app import check, so there is one vendored copy.
|
|
22
|
+
*/
|
|
23
|
+
import * as fs from 'node:fs';
|
|
24
|
+
import * as path from 'node:path';
|
|
25
|
+
import { createRequire } from 'node:module';
|
|
26
|
+
import { fileURLToPath } from 'node:url';
|
|
27
|
+
import esbuild from 'esbuild';
|
|
28
|
+
|
|
29
|
+
const REAL_DIR = path.dirname(fileURLToPath(import.meta.url));
|
|
30
|
+
const ENTRY_NS = 'canvas-entry';
|
|
31
|
+
const require = createRequire(import.meta.url);
|
|
32
|
+
|
|
33
|
+
/** One importable library: the bare specifier a canvas writes, the entry
|
|
34
|
+
* source that re-exports it, the npm package whose version it pins, and the
|
|
35
|
+
* specifiers left to the import map (a Three addon imports `three`). */
|
|
36
|
+
type CanvasModule = {
|
|
37
|
+
specifier: string;
|
|
38
|
+
entry: string;
|
|
39
|
+
source: string;
|
|
40
|
+
pkg: string;
|
|
41
|
+
external?: string[];
|
|
42
|
+
/** Resolved from the APP that serves the runtime (server/web), not from
|
|
43
|
+
* this package: a private workspace package this published one must not
|
|
44
|
+
* name as a dependency (scripts/publish-contract.mjs refuses that). */
|
|
45
|
+
fromApp?: true;
|
|
46
|
+
};
|
|
47
|
+
|
|
48
|
+
/** The import map's modules, by bare specifier. A canvas writes exactly
|
|
49
|
+
* these names; anything else is not in the set. */
|
|
50
|
+
export const CANVAS_MODULES: readonly CanvasModule[] = [
|
|
51
|
+
{ specifier: 'echarts', entry: 'echarts', pkg: 'echarts', source: "export * from 'echarts';" },
|
|
52
|
+
{ specifier: 'd3', entry: 'd3', pkg: 'd3', source: "export * from 'd3';" },
|
|
53
|
+
{
|
|
54
|
+
specifier: 'konva',
|
|
55
|
+
entry: 'konva',
|
|
56
|
+
pkg: 'konva',
|
|
57
|
+
source: "import Konva from 'konva';\nexport default Konva;",
|
|
58
|
+
},
|
|
59
|
+
{ specifier: 'three', entry: 'three', pkg: 'three', source: "export * from 'three';" },
|
|
60
|
+
{
|
|
61
|
+
specifier: 'three/addons/controls/OrbitControls.js',
|
|
62
|
+
entry: 'three-orbit-controls',
|
|
63
|
+
pkg: 'three',
|
|
64
|
+
source: "export * from 'three/addons/controls/OrbitControls.js';",
|
|
65
|
+
external: ['three'],
|
|
66
|
+
},
|
|
67
|
+
{ specifier: 'motion', entry: 'motion', pkg: 'motion', source: "export * from 'motion';" },
|
|
68
|
+
{
|
|
69
|
+
specifier: 'reveal.js',
|
|
70
|
+
entry: 'reveal',
|
|
71
|
+
pkg: 'reveal.js',
|
|
72
|
+
source: "import Reveal from 'reveal.js';\nexport default Reveal;",
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
specifier: 'katex',
|
|
76
|
+
entry: 'katex',
|
|
77
|
+
pkg: 'katex',
|
|
78
|
+
source: "import katex from 'katex';\nexport default katex;",
|
|
79
|
+
},
|
|
80
|
+
// The diagram templates' browser runtime (@mantle/diagram-templates): a
|
|
81
|
+
// template canvas imports `mount` from here instead of carrying the
|
|
82
|
+
// runtime inline, so it is its data and a few lines.
|
|
83
|
+
{
|
|
84
|
+
specifier: '@mantle/diagram-templates/browser',
|
|
85
|
+
entry: 'diagram-templates',
|
|
86
|
+
pkg: '@mantle/diagram-templates',
|
|
87
|
+
source: "export * from '@mantle/diagram-templates/browser';",
|
|
88
|
+
fromApp: true,
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
specifier: 'alpinejs',
|
|
92
|
+
entry: 'alpine',
|
|
93
|
+
pkg: 'alpinejs',
|
|
94
|
+
source: "import Alpine from 'alpinejs';\nexport default Alpine;",
|
|
95
|
+
},
|
|
96
|
+
];
|
|
97
|
+
|
|
98
|
+
/** Libraries with a classic browser build only, loaded with `<script src>`
|
|
99
|
+
* (the path is stable, so the authoring skill can name it). */
|
|
100
|
+
const CLASSIC_SCRIPTS: readonly { pkg: string; from: string; to: string }[] = [
|
|
101
|
+
{ pkg: 'plotly.js-dist-min', from: 'plotly.min.js', to: 'plotly/plotly.min.js' },
|
|
102
|
+
];
|
|
103
|
+
|
|
104
|
+
/** Stylesheets copied beside the modules, at stable paths. */
|
|
105
|
+
const STYLE_ASSETS: readonly { pkg: string; from: string; to: string }[] = [
|
|
106
|
+
{ pkg: 'reveal.js', from: 'dist/reveal.css', to: 'reveal/reveal.css' },
|
|
107
|
+
{ pkg: 'reveal.js', from: 'dist/theme', to: 'reveal/theme' },
|
|
108
|
+
];
|
|
109
|
+
|
|
110
|
+
export type CanvasRuntimeManifest = {
|
|
111
|
+
/** Bare specifier → hashed URL under the prefix (the import map). */
|
|
112
|
+
imports: Record<string, string>;
|
|
113
|
+
/** Bare specifier → the names its module exports ('default' included when
|
|
114
|
+
* it has one), from esbuild's metafile. The mini-app import check reads
|
|
115
|
+
* it (a wrong name fails the app at link time, past any error boundary). */
|
|
116
|
+
exports: Record<string, string[]>;
|
|
117
|
+
/** npm package → the version this runtime pins. */
|
|
118
|
+
libs: Record<string, string>;
|
|
119
|
+
/** The stable non-module paths (classic scripts, stylesheets). */
|
|
120
|
+
assets: string[];
|
|
121
|
+
builtAt: string;
|
|
122
|
+
};
|
|
123
|
+
|
|
124
|
+
/** A package's install directory. Not `require.resolve('<pkg>/package.json')`:
|
|
125
|
+
* a package whose `exports` omits it (reveal.js) refuses that. */
|
|
126
|
+
function packageDir(pkg: string, from: NodeJS.Require = require): string {
|
|
127
|
+
for (const base of from.resolve.paths(pkg) ?? []) {
|
|
128
|
+
const dir = path.join(base, pkg);
|
|
129
|
+
if (fs.existsSync(path.join(dir, 'package.json'))) return dir;
|
|
130
|
+
}
|
|
131
|
+
throw new Error(`canvas runtime: package '${pkg}' is not installed`);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function packageVersion(pkg: string, from: NodeJS.Require = require): string {
|
|
135
|
+
const json = JSON.parse(
|
|
136
|
+
fs.readFileSync(path.join(packageDir(pkg, from), 'package.json'), 'utf8'),
|
|
137
|
+
) as {
|
|
138
|
+
version: string;
|
|
139
|
+
};
|
|
140
|
+
return json.version;
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
function entryPlugin(appDir: string): esbuild.Plugin {
|
|
144
|
+
const byEntry = new Map(CANVAS_MODULES.map((m) => [m.entry, m]));
|
|
145
|
+
return {
|
|
146
|
+
name: 'canvas-runtime',
|
|
147
|
+
setup(build) {
|
|
148
|
+
build.onResolve({ filter: /^entry:/ }, (args) => ({
|
|
149
|
+
path: args.path.slice('entry:'.length),
|
|
150
|
+
namespace: ENTRY_NS,
|
|
151
|
+
}));
|
|
152
|
+
build.onLoad({ filter: /.*/, namespace: ENTRY_NS }, (args) => ({
|
|
153
|
+
contents: byEntry.get(args.path)?.source ?? '',
|
|
154
|
+
loader: 'js',
|
|
155
|
+
resolveDir: byEntry.get(args.path)?.fromApp ? appDir : REAL_DIR,
|
|
156
|
+
}));
|
|
157
|
+
},
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** Leave exactly these specifiers to the import map. Not esbuild's
|
|
162
|
+
* `external`, which also takes every subpath (`three` would take the addon
|
|
163
|
+
* being built, `three/addons/...`, and bundle nothing). */
|
|
164
|
+
function exactExternals(names: readonly string[]): esbuild.Plugin {
|
|
165
|
+
return {
|
|
166
|
+
name: 'canvas-exact-externals',
|
|
167
|
+
setup(build) {
|
|
168
|
+
build.onResolve({ filter: /.*/ }, (args) =>
|
|
169
|
+
names.includes(args.path) ? { path: args.path, external: true } : undefined,
|
|
170
|
+
);
|
|
171
|
+
},
|
|
172
|
+
};
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** The canvas runtime's import map JSON for a manifest (imports only). */
|
|
176
|
+
export function canvasImportMapJson(manifest: Pick<CanvasRuntimeManifest, 'imports'>): string {
|
|
177
|
+
return JSON.stringify({ imports: manifest.imports });
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/**
|
|
181
|
+
* Build the canvas runtime into `outDir` (server/web/public/canvas-runtime)
|
|
182
|
+
* and return its manifest. `urlPrefix` is the public path it is served at;
|
|
183
|
+
* `appDir` is the app that serves it (a `fromApp` module resolves there).
|
|
184
|
+
*/
|
|
185
|
+
export async function buildCanvasRuntime(
|
|
186
|
+
outDir: string,
|
|
187
|
+
urlPrefix = '/canvas-runtime/',
|
|
188
|
+
appDir = path.resolve(outDir, '..', '..'),
|
|
189
|
+
): Promise<CanvasRuntimeManifest> {
|
|
190
|
+
const appRequire = createRequire(path.join(appDir, 'package.json'));
|
|
191
|
+
fs.rmSync(outDir, { recursive: true, force: true });
|
|
192
|
+
fs.mkdirSync(outDir, { recursive: true });
|
|
193
|
+
|
|
194
|
+
const imports: Record<string, string> = {};
|
|
195
|
+
const exports: Record<string, string[]> = {};
|
|
196
|
+
// One build per module: each is self-contained, except the externals it
|
|
197
|
+
// names, which the import map resolves at run time.
|
|
198
|
+
for (const m of CANVAS_MODULES) {
|
|
199
|
+
const result = await esbuild.build({
|
|
200
|
+
entryPoints: [{ in: `entry:${m.entry}`, out: m.entry }],
|
|
201
|
+
bundle: true,
|
|
202
|
+
format: 'esm',
|
|
203
|
+
platform: 'browser',
|
|
204
|
+
target: 'es2020',
|
|
205
|
+
minify: true,
|
|
206
|
+
legalComments: 'none',
|
|
207
|
+
define: { 'process.env.NODE_ENV': '"production"' },
|
|
208
|
+
outdir: outDir,
|
|
209
|
+
entryNames: '[name]-[hash]',
|
|
210
|
+
write: true,
|
|
211
|
+
metafile: true,
|
|
212
|
+
logLevel: 'silent',
|
|
213
|
+
plugins: [entryPlugin(appDir), exactExternals(m.external ?? [])],
|
|
214
|
+
});
|
|
215
|
+
const out = Object.keys(result.metafile.outputs).find((p) => p.endsWith('.js'));
|
|
216
|
+
if (!out) throw new Error(`canvas runtime: no output for '${m.specifier}'`);
|
|
217
|
+
imports[m.specifier] = urlPrefix + path.basename(out);
|
|
218
|
+
exports[m.specifier] = result.metafile.outputs[out]!.exports ?? [];
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
const assets: string[] = [];
|
|
222
|
+
for (const a of [...CLASSIC_SCRIPTS, ...STYLE_ASSETS]) {
|
|
223
|
+
const from = path.join(packageDir(a.pkg), a.from);
|
|
224
|
+
const to = path.join(outDir, a.to);
|
|
225
|
+
fs.mkdirSync(path.dirname(to), { recursive: true });
|
|
226
|
+
fs.cpSync(from, to, { recursive: true });
|
|
227
|
+
assets.push(urlPrefix + a.to);
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
const libs: Record<string, string> = {};
|
|
231
|
+
for (const m of CANVAS_MODULES) {
|
|
232
|
+
libs[m.pkg] = packageVersion(m.pkg, m.fromApp ? appRequire : require);
|
|
233
|
+
}
|
|
234
|
+
for (const s of CLASSIC_SCRIPTS) libs[s.pkg] = packageVersion(s.pkg);
|
|
235
|
+
|
|
236
|
+
const manifest: CanvasRuntimeManifest = {
|
|
237
|
+
imports,
|
|
238
|
+
exports,
|
|
239
|
+
libs,
|
|
240
|
+
assets,
|
|
241
|
+
builtAt: new Date().toISOString(),
|
|
242
|
+
};
|
|
243
|
+
fs.writeFileSync(path.join(outDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
|
|
244
|
+
return manifest;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** The bare specifiers a canvas may import (the import map's keys). */
|
|
248
|
+
export const CANVAS_MODULE_SPECIFIERS: readonly string[] = CANVAS_MODULES.map((m) => m.specifier);
|
package/src/css.ts
CHANGED
|
@@ -103,3 +103,13 @@ export async function buildAppCss(source: AppSource): Promise<string> {
|
|
|
103
103
|
const min = await esbuild.transform(css, { loader: 'css', minify: true });
|
|
104
104
|
return min.code;
|
|
105
105
|
}
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* A Present canvas's utility CSS (docs/proposals/canvas-files.md section
|
|
109
|
+
* 6.3): the same compile as an app's, over the canvas's one HTML document,
|
|
110
|
+
* so `class="rounded-lg bg-card p-6"` works with no CDN and no in-browser
|
|
111
|
+
* Tailwind. Run on save; the result is stored beside the source.
|
|
112
|
+
*/
|
|
113
|
+
export async function buildCanvasCss(html: string): Promise<string> {
|
|
114
|
+
return buildAppCss({ entry: 'index.html', files: { 'index.html': html } });
|
|
115
|
+
}
|