@timber-js/app 0.2.0-alpha.223 → 0.2.0-alpha.224

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.
@@ -0,0 +1,439 @@
1
+ /**
2
+ * timber-optimize-package-imports — rewrites named imports from a listed
3
+ * barrel package into imports of only the modules that define those names.
4
+ *
5
+ * In dev, `@vitejs/plugin-rsc` keeps packages with a `react` peer dependency
6
+ * in the rsc and ssr module graphs without pre-bundling them, so on the server
7
+ * `import { Play } from 'lucide-react'` enters lucide's barrel and Vite
8
+ * transforms all ~2,000 icon modules it re-exports, once per environment. A
9
+ * build loads all of them too, before tree-shaking. The
10
+ * rewrite turns that import into one of the icon's own file:
11
+ *
12
+ * import { Play } from 'lucide-react'
13
+ * → import { default as Play } from "/…/lucide-react/dist/esm/icons/play.mjs";
14
+ *
15
+ * Next.js does the same for its `optimizePackageImports` list
16
+ * (next-barrel-loader.ts, optimize_barrel.rs). It applies to every environment
17
+ * in builds; in dev, to the server environments and only for packages Vite
18
+ * compiles itself (the client environment pre-bundles them; the server
19
+ * environments hand most other packages to Node). See design/21-dev-server.md
20
+ * §"Barrel Import Optimization".
21
+ *
22
+ * Every rule here leans toward leaving the import alone. A missed rewrite costs
23
+ * compile time; a wrong one breaks the app. An import is rewritten only when
24
+ * the barrel is a pure barrel (nothing but imports and re-exports) and every
25
+ * imported name is in its export map with a target that resolves to a file.
26
+ */
27
+
28
+ import { readFileSync } from 'node:fs';
29
+ import { isAbsolute } from 'node:path';
30
+ import { MagicString } from 'magic-string';
31
+ import { parseAst, type Plugin } from 'vite';
32
+ import type { PluginContext } from '../plugin-context.ts';
33
+ import { DEFAULT_OPTIMIZE_PACKAGE_IMPORTS } from './optimize-package-imports-defaults.ts';
34
+
35
+ type Program = ReturnType<typeof parseAst>;
36
+ type ModuleItem = Program['body'][number];
37
+ type ImportDeclaration = Extract<ModuleItem, { type: 'ImportDeclaration' }>;
38
+ type ExportNamedDeclaration = Extract<ModuleItem, { type: 'ExportNamedDeclaration' }>;
39
+ type ModuleExportName = ExportNamedDeclaration['specifiers'][number]['local'];
40
+ type Lang = 'js' | 'jsx' | 'ts' | 'tsx';
41
+
42
+ /** Where a barrel's export comes from. */
43
+ export interface BarrelExport {
44
+ /** The specifier as written in the barrel (`'./icons/play.mjs'`). */
45
+ source: string;
46
+ /** The name in `source`: an export name, `'default'`, or `'*'` for a namespace. */
47
+ imported: string;
48
+ }
49
+
50
+ /** Export name → origin, for the names a barrel states explicitly. */
51
+ export type BarrelExportMap = ReadonlyMap<string, BarrelExport>;
52
+
53
+ /** A barrel the rewrite may import past, as seen from one importer. */
54
+ export interface ResolvedBarrel {
55
+ exports: BarrelExportMap;
56
+ /** Resolve a source from `exports` relative to the barrel; null = leave the import alone. */
57
+ resolveTarget(source: string): Promise<string | null>;
58
+ }
59
+
60
+ /**
61
+ * Merge the user's list with the defaults (Next's semantics: the user list
62
+ * adds, never replaces). Config validation reports invalid entries without
63
+ * stopping the dev server, so only the valid ones (non-empty strings) are used
64
+ * here; a string list is not spread into characters, and an empty entry does
65
+ * not match every quoted empty string.
66
+ */
67
+ export function resolveOptimizedPackages(user: readonly string[] | undefined): ReadonlySet<string> {
68
+ const extra = Array.isArray(user)
69
+ ? user.filter((entry) => typeof entry === 'string' && entry.trim() !== '')
70
+ : [];
71
+ return new Set([...DEFAULT_OPTIMIZE_PACKAGE_IMPORTS, ...extra]);
72
+ }
73
+
74
+ function nameOf(node: ModuleExportName): string {
75
+ return node.type === 'Literal' ? node.value : node.name;
76
+ }
77
+
78
+ /**
79
+ * Read a barrel's export map, or null when the file is not a pure barrel.
80
+ *
81
+ * A pure barrel holds only imports, re-exports, and `export { local }` of an
82
+ * imported binding (`import * as icons from './icons'; export { icons }`, which
83
+ * lucide-react's barrel opens with). Anything that runs code of its own, a
84
+ * declaration, an expression, a bare side-effect import, makes it not a barrel:
85
+ * importing past it would skip that code. So does any directive except
86
+ * `'use strict'`: a `'use client'` or `'use server'` barrel is a boundary
87
+ * plugin-rsc draws around the barrel module itself, and importing past it would
88
+ * load the re-exported files on the wrong side of it.
89
+ *
90
+ * `export default local` is not followed even when `local` is imported: it
91
+ * exports the value `local` held when the barrel ran, not a live binding, so
92
+ * importing `local` directly would see later reassignments the barrel's
93
+ * default never does. `export { local as default }` is live and is followed.
94
+ *
95
+ * A source-phase or deferred import, or import attributes, change what the
96
+ * barrel's binding is, so a barrel using them is not followed. An
97
+ * `export {} from` with no names only runs the module, like a bare import.
98
+ *
99
+ * `export * from` adds no entries. A name it might supply is not in the map, so
100
+ * an import of that name falls back; explicit exports shadow star exports, so
101
+ * every name that is in the map is exact.
102
+ */
103
+ export function readBarrelExportMap(code: string, lang: Lang): BarrelExportMap | null {
104
+ let program: Program;
105
+ try {
106
+ program = parseAst(code, { lang });
107
+ } catch {
108
+ return null;
109
+ }
110
+
111
+ const imported = new Map<string, BarrelExport>();
112
+ for (const item of program.body) {
113
+ if (item.type !== 'ImportDeclaration' || item.importKind === 'type') continue;
114
+ const source = item.source.value;
115
+ for (const spec of item.specifiers) {
116
+ if (spec.type === 'ImportSpecifier') {
117
+ if (spec.importKind === 'type') continue;
118
+ imported.set(spec.local.name, { source, imported: nameOf(spec.imported) });
119
+ } else if (spec.type === 'ImportDefaultSpecifier') {
120
+ imported.set(spec.local.name, { source, imported: 'default' });
121
+ } else {
122
+ imported.set(spec.local.name, { source, imported: '*' });
123
+ }
124
+ }
125
+ }
126
+
127
+ const exports = new Map<string, BarrelExport>();
128
+ for (const item of program.body) {
129
+ switch (item.type) {
130
+ case 'ExpressionStatement':
131
+ if ('directive' in item && item.directive === 'use strict') continue;
132
+ return null;
133
+ case 'ImportDeclaration':
134
+ if (item.importKind === 'type') continue;
135
+ if (item.specifiers.length === 0 || item.phase !== null || item.attributes.length > 0) {
136
+ return null;
137
+ }
138
+ continue;
139
+ case 'ExportAllDeclaration':
140
+ if (item.exportKind === 'type') continue;
141
+ if (item.attributes.length > 0) return null;
142
+ if (item.exported) {
143
+ exports.set(nameOf(item.exported), { source: item.source.value, imported: '*' });
144
+ }
145
+ continue;
146
+ case 'ExportNamedDeclaration': {
147
+ if (item.exportKind === 'type') continue;
148
+ if (item.declaration || item.attributes.length > 0) return null;
149
+ if (item.source && item.specifiers.length === 0) return null;
150
+ for (const spec of item.specifiers) {
151
+ if (spec.exportKind === 'type') continue;
152
+ const local = nameOf(spec.local);
153
+ const origin = item.source
154
+ ? { source: item.source.value, imported: local }
155
+ : imported.get(local);
156
+ if (!origin) return null;
157
+ exports.set(nameOf(spec.exported), origin);
158
+ }
159
+ continue;
160
+ }
161
+ // Erased by the TypeScript transform; they run nothing.
162
+ case 'TSInterfaceDeclaration':
163
+ case 'TSTypeAliasDeclaration':
164
+ continue;
165
+ default:
166
+ return null;
167
+ }
168
+ }
169
+ return exports;
170
+ }
171
+
172
+ const IDENTIFIER_RE = /^[A-Za-z_$][\w$]*$/;
173
+
174
+ /** An export name as it must be written in an import or export clause. */
175
+ function clauseName(name: string): string {
176
+ return IDENTIFIER_RE.test(name) ? name : JSON.stringify(name);
177
+ }
178
+
179
+ /** One binding the rewritten statement must still provide. */
180
+ interface Binding {
181
+ /** The name the user's statement wanted from the barrel. */
182
+ barrelName: string;
183
+ /** The local name (import) or exported name (re-export) it binds. */
184
+ as: string;
185
+ }
186
+
187
+ /**
188
+ * The bindings a statement takes from `source`, or null when the statement is
189
+ * not a candidate: a namespace import, `import type`, an import attribute, a
190
+ * source phase import, or a statement with no value bindings.
191
+ */
192
+ function statementBindings(item: ImportDeclaration | ExportNamedDeclaration): Binding[] | null {
193
+ if (item.attributes.length > 0) return null;
194
+ const bindings: Binding[] = [];
195
+ if (item.type === 'ImportDeclaration') {
196
+ if (item.importKind === 'type' || item.phase !== null) return null;
197
+ for (const spec of item.specifiers) {
198
+ if (spec.type === 'ImportNamespaceSpecifier') return null;
199
+ if (spec.type === 'ImportDefaultSpecifier') {
200
+ bindings.push({ barrelName: 'default', as: spec.local.name });
201
+ } else if (spec.importKind !== 'type') {
202
+ bindings.push({ barrelName: nameOf(spec.imported), as: spec.local.name });
203
+ }
204
+ }
205
+ } else {
206
+ if (item.exportKind === 'type' || item.declaration) return null;
207
+ for (const spec of item.specifiers) {
208
+ if (spec.exportKind === 'type') continue;
209
+ bindings.push({ barrelName: nameOf(spec.local), as: nameOf(spec.exported) });
210
+ }
211
+ }
212
+ return bindings.length > 0 ? bindings : null;
213
+ }
214
+
215
+ /** The replacement statements for one candidate, or null to leave it alone. */
216
+ async function rewriteStatement(
217
+ item: ImportDeclaration | ExportNamedDeclaration,
218
+ barrel: ResolvedBarrel
219
+ ): Promise<string | null> {
220
+ const bindings = statementBindings(item);
221
+ if (!bindings) return null;
222
+ const out: string[] = [];
223
+ for (const { barrelName, as } of bindings) {
224
+ const origin = barrel.exports.get(barrelName);
225
+ if (!origin) return null;
226
+ const target = await barrel.resolveTarget(origin.source);
227
+ if (!target) return null;
228
+ const from = JSON.stringify(target);
229
+ if (item.type === 'ImportDeclaration') {
230
+ out.push(
231
+ origin.imported === '*'
232
+ ? `import * as ${as} from ${from};`
233
+ : `import { ${clauseName(origin.imported)} as ${as} } from ${from};`
234
+ );
235
+ } else {
236
+ out.push(
237
+ origin.imported === '*'
238
+ ? `export * as ${clauseName(as)} from ${from};`
239
+ : `export { ${clauseName(origin.imported)} as ${clauseName(as)} } from ${from};`
240
+ );
241
+ }
242
+ }
243
+ return out.join(' ');
244
+ }
245
+
246
+ /**
247
+ * Rewrite every import and `export { … } from` of a listed specifier whose
248
+ * names the barrel's export map covers. Returns null when nothing changed.
249
+ *
250
+ * Replacements stay on the statement's own lines, so positions after it keep
251
+ * their line numbers even before the source map is applied.
252
+ */
253
+ export async function rewriteBarrelImports(
254
+ code: string,
255
+ packages: ReadonlySet<string>,
256
+ loadBarrel: (specifier: string) => Promise<ResolvedBarrel | null>
257
+ ): Promise<MagicString | null> {
258
+ let program: Program;
259
+ try {
260
+ // Runs after Vite's TypeScript/JSX transform, so the code is JavaScript.
261
+ program = parseAst(code, { lang: 'js' });
262
+ } catch {
263
+ return null;
264
+ }
265
+ let s: MagicString | null = null;
266
+ const barrels = new Map<string, ResolvedBarrel | null>();
267
+ for (const item of program.body) {
268
+ if (item.type !== 'ImportDeclaration' && item.type !== 'ExportNamedDeclaration') continue;
269
+ const specifier = item.source?.value;
270
+ if (specifier === undefined || !packages.has(specifier)) continue;
271
+ let barrel = barrels.get(specifier);
272
+ if (barrel === undefined) {
273
+ barrel = await loadBarrel(specifier);
274
+ barrels.set(specifier, barrel);
275
+ }
276
+ if (!barrel) continue;
277
+ const replacement = await rewriteStatement(item, barrel);
278
+ if (replacement === null) continue;
279
+ s ??= new MagicString(code);
280
+ const lineBreaks = code.slice(item.start, item.end).split('\n').length - 1;
281
+ s.overwrite(item.start, item.end, replacement + '\n'.repeat(lineBreaks));
282
+ }
283
+ return s;
284
+ }
285
+
286
+ /** The npm package a bare specifier names: `@scope/pkg/sub` → `@scope/pkg`. */
287
+ function packageNameOf(specifier: string): string {
288
+ const parts = specifier.split('/');
289
+ return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
290
+ }
291
+
292
+ /** The resolve options that decide whether a server environment externalizes a package. */
293
+ export interface ExternalizationConfig {
294
+ noExternal: string | RegExp | readonly (string | RegExp)[] | true;
295
+ external: readonly string[] | true;
296
+ }
297
+
298
+ /**
299
+ * Whether the environment loads `specifier` through Vite rather than handing
300
+ * it to Node. Only those imports are rewritten.
301
+ *
302
+ * A server environment externalizes most of node_modules in dev: Node loads
303
+ * the package natively, so its barrel costs nothing to compile. Rewriting such
304
+ * an import to a file path would pull that file into Vite's module graph
305
+ * while any other import of the package stayed external, two instances of one
306
+ * module. In dev, plugin-rsc keeps packages with a `react` peer dependency
307
+ * (lucide-react, the icon sets, the component libraries) out of
308
+ * externalization, and timber's production build sets `noExternal: true`.
309
+ *
310
+ * Vite's own check is internal, so this is its conservative subset: the
311
+ * package must match `resolve.noExternal` exactly (a string or a RegExp) and
312
+ * `resolve.external` must not name it. A glob string in `noExternal` does
313
+ * not match here, which only costs the optimization.
314
+ */
315
+ export function isLoadedThroughVite(specifier: string, config: ExternalizationConfig): boolean {
316
+ const pkg = packageNameOf(specifier);
317
+ const { noExternal, external } = config;
318
+ if (external === true || external.includes(specifier) || external.includes(pkg)) return false;
319
+ if (noExternal === true) return true;
320
+ const patterns = Array.isArray(noExternal) ? noExternal : [noExternal];
321
+ return patterns.some((p) => (typeof p === 'string' ? p === pkg : p.test(pkg)));
322
+ }
323
+
324
+ function langForFile(file: string): Lang {
325
+ if (file.endsWith('.tsx')) return 'tsx';
326
+ if (/\.[mc]?ts$/.test(file)) return 'ts';
327
+ if (file.endsWith('.jsx')) return 'jsx';
328
+ return 'js';
329
+ }
330
+
331
+ /**
332
+ * A resolved id as a plain file import, or null when it is not one (virtual,
333
+ * relative, or carrying a query that changes what the module is).
334
+ *
335
+ * Vite's dev resolver appends `?v=<hash>` to files under node_modules, in the
336
+ * server environments too, and appends the same query again when it resolves
337
+ * the absolute path this rewrite emits. So the query is dropped, never copied:
338
+ * the emitted path resolves to the same id the barrel's own import would, which
339
+ * keeps one module instance per file.
340
+ */
341
+ function asFilePath(id: string): string | null {
342
+ const path = id.replace(/\?v=[\w.-]+$/, '');
343
+ return isAbsolute(path) && !path.includes('?') && !path.includes('\0') ? path : null;
344
+ }
345
+
346
+ function escapeRegExp(text: string): string {
347
+ return text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
348
+ }
349
+
350
+ export function timberOptimizePackageImports(ctx: PluginContext): Plugin {
351
+ let packages: ReadonlySet<string> = new Set();
352
+ let isDev = false;
353
+ // Cheap pre-filter: a module that never quotes a listed specifier is not parsed.
354
+ let mentionsListed = /(?!)/;
355
+ // Installed packages are assumed not to change while the process runs (Next
356
+ // makes the same assumption); after a reinstall, restart the dev server. A
357
+ // barrel outside node_modules (a linked workspace package) can be edited, so
358
+ // it is read on every transform and never cached. The read and parse are
359
+ // synchronous, so concurrent transforms cannot parse one barrel twice and
360
+ // there is no in-flight promise to time out.
361
+ const exportMaps = new Map<string, BarrelExportMap | null>();
362
+ const targets = new Map<string, string | null>();
363
+
364
+ const isInstalled = (path: string) => path.includes('/node_modules/');
365
+
366
+ function exportMapFor(barrelPath: string): BarrelExportMap | null {
367
+ const cached = exportMaps.get(barrelPath);
368
+ if (cached !== undefined) return cached;
369
+ let code: string;
370
+ try {
371
+ code = readFileSync(barrelPath, 'utf8');
372
+ } catch {
373
+ // Unreadable (deleted, or a transient EMFILE): leave imports alone this
374
+ // time and try again on the next transform.
375
+ return null;
376
+ }
377
+ const map = readBarrelExportMap(code, langForFile(barrelPath));
378
+ if (isInstalled(barrelPath)) exportMaps.set(barrelPath, map);
379
+ return map;
380
+ }
381
+
382
+ return {
383
+ name: 'timber-optimize-package-imports',
384
+
385
+ configResolved(config) {
386
+ isDev = config.command === 'serve';
387
+ packages = resolveOptimizedPackages(ctx.config.optimizePackageImports);
388
+ const alternatives = [...packages].map(escapeRegExp).join('|');
389
+ mentionsListed = new RegExp(`(["'])(?:${alternatives})\\1`);
390
+ },
391
+
392
+ // Normal order, after Vite's TypeScript transform: an import that names a
393
+ // type without `type` (`import { Play, LucideIcon }`) has been reduced to
394
+ // its value names, so the type does not fall the whole import back.
395
+ async transform(code, id) {
396
+ // In dev the client environment pre-bundles these packages into one
397
+ // module; importing past that bundle would load a second copy of the
398
+ // package. Builds have no pre-bundle, so every environment is rewritten.
399
+ if (isDev && this.environment.config.consumer !== 'server') return null;
400
+ if (id.startsWith('\0') || !mentionsListed.test(code)) return null;
401
+ const envName = this.environment.name;
402
+
403
+ const { consumer, resolve } = this.environment.config;
404
+
405
+ const s = await rewriteBarrelImports(code, packages, async (specifier) => {
406
+ if (consumer === 'server' && !isLoadedThroughVite(specifier, resolve)) return null;
407
+ const resolved = await this.resolve(specifier, id);
408
+ const barrelPath = resolved && !resolved.external ? asFilePath(resolved.id) : null;
409
+ if (!barrelPath) return null;
410
+ // The rewrite takes the barrel out of this module's import graph, so
411
+ // an edit to an editable barrel would not otherwise re-transform it.
412
+ const installed = isInstalled(barrelPath);
413
+ if (!installed) this.addWatchFile(barrelPath);
414
+ const exports = exportMapFor(barrelPath);
415
+ if (!exports) return null;
416
+ return {
417
+ exports,
418
+ resolveTarget: async (source) => {
419
+ // Only the barrel's own files. A bare source names another
420
+ // package, which the environment may externalize to Node: an
421
+ // absolute path to it would load a second copy beside Node's (or
422
+ // a CJS file Vite's runner cannot run). resolveId does not report
423
+ // that externalization in dev, so it cannot be checked here.
424
+ if (!source.startsWith('./') && !source.startsWith('../')) return null;
425
+ const key = `${envName}\0${barrelPath}\0${source}`;
426
+ const cached = targets.get(key);
427
+ if (cached !== undefined) return cached;
428
+ const target = await this.resolve(source, barrelPath);
429
+ const path = target && !target.external ? asFilePath(target.id) : null;
430
+ if (installed) targets.set(key, path);
431
+ return path;
432
+ },
433
+ };
434
+ });
435
+ if (!s) return null;
436
+ return { code: s.toString(), map: s.generateMap({ hires: 'boundary' }) };
437
+ },
438
+ };
439
+ }