ember.nvp 0.6.0 → 0.7.0

package/packages/rolldown/index.ts

@@ -0,0 +1,56 @@
+import type { Plugin } from "rolldown";
+
+import { emberBabel, type BabelOptions } from "./src/babel.ts";
+import { emberExternals } from "./src/externals.ts";
+import { emberIsolatedDeclarations } from "./src/isolated-declarations.ts";
+import { emberTransform } from "./src/transform.ts";
+
+export { defineConfig } from "./src/define-config.ts";
+
+interface Config {
+  /**
+   * Options for the babel step; see `BabelOptions`.
+   */
+  babel?: BabelOptions;
+}
+
+/**
+ * A batteries-included plugin for building Ember v2 libraries (addons) with
+ * rolldown (or tsdown, which is built on rolldown).
+ *
+ * It bundles everything needed to compile `.gts`/`.gjs` and template-tag
+ * (`<template>`) source into publishable output:
+ *
+ * - `emberIsolatedDeclarations()` — errors when a tsconfig.json is present
+ *   without `isolatedDeclarations: true` (required: it is the only
+ *   declaration pipeline that can see compiled template-tag modules).
+ * - `emberExternals()` — keeps your dependencies, peerDependencies, and the
+ *   ember virtual packages external, so consuming apps resolve them.
+ * - `emberTransform()` — preprocesses `<template>` via content-tag and maps
+ *   `.gts`/`.gjs` to `.ts`/`.js` so rolldown can understand them.
+ * - `emberBabel()` — runs babel (template compilation, decorators, type
+ *   stripping) with `babelHelpers: "bundled"`, but only on the files that
+ *   actually need it (via `maybeBabel`); everything else stays on the fast
+ *   native transform. The library's own `babel.config.js` is used when it
+ *   exists; no config file is required.
+ *
+ * Usage in `tsdown.config.js` / `rolldown.config.js`:
+ *
+ * ```js
+ * import { ember } from "@nullvoxpopuli/ember-rolldown";
+ *
+ * export default defineConfig({
+ *   entry: ["./src/index.ts"],
+ *   dts: true,
+ *   plugins: [ember()],
+ * });
+ * ```
+ */
+export function ember(config: Config = {}): Plugin[] {
+  return [
+    emberIsolatedDeclarations(),
+    emberExternals(),
+    emberTransform(),
+    emberBabel(config.babel),
+  ];
+}

package/packages/rolldown/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nullvoxpopuli/ember-rolldown",
+  "version": "1.1.0",
+  "description": "Meta plugin for building ember v2 libraries/addons with rolldown & tsdown.",
+  "type": "module",
+  "main": "index.ts",
+  "publishConfig": {
+    "main": "dist/index.js"
+  },
+  "keywords": [
+    "rolldown",
+    "tsdown",
+    "ember",
+    "meta plugin",
+    "v2 addon",
+    "library"
+  ],
+  "author": "NullVoxPopuli",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NullVoxPopuli/ember.nvp",
+    "directory": "packages/rolldown"
+  },
+  "scripts": {
+    "build": "rolldown --config",
+    "prepack": "pnpm build"
+  },
+  "packageManager": "pnpm@10.28.0",
+  "dependencies": {
+    "@babel/core": "^7.28.10",
+    "@babel/plugin-transform-typescript": "^7.28.10",
+    "@embroider/core": "^4.4.2",
+    "@nullvoxpopuli/ember-build-tooling-utils": "workspace:*",
+    "babel-plugin-ember-template-compilation": "^4.0.0",
+    "content-tag": "^4.2.0",
+    "decorator-transforms": "^2.3.2"
+  },
+  "engines": {
+    "node": ">= 24"
+  },
+  "peerDependencies": {
+    "tsdown": ">= 0.22.0",
+    "typescript": ">= 5.5"
+  },
+  "peerDependenciesMeta": {
+    "tsdown": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "rolldown": "^1.1.2",
+    "tsdown": "^0.22.7",
+    "typescript": "^6.0.3"
+  }
+}

package/packages/rolldown/rolldown.config.js

@@ -0,0 +1,21 @@
+import { defineConfig } from "rolldown";
+
+import manifest from "./package.json" with { type: "json" };
+
+const deps = [
+  ...Object.keys(manifest.dependencies || {}),
+  ...Object.keys(manifest.peerDependencies || {}),
+];
+
+export default defineConfig({
+  input: "index.ts",
+  output: {
+    format: "esm",
+    file: "dist/index.js",
+    codeSplitting: false,
+  },
+  external(id) {
+    if (id.startsWith("node:")) return true;
+    if (deps.some((dep) => id.startsWith(dep))) return true;
+  },
+});

package/packages/rolldown/src/babel.ts

@@ -0,0 +1,136 @@
+import { maybeBabel } from "@nullvoxpopuli/ember-build-tooling-utils";
+import transformTypeScript from "@babel/plugin-transform-typescript";
+import templateCompilation from "babel-plugin-ember-template-compilation";
+import decoratorTransforms from "decorator-transforms";
+import { loadPartialConfigSync } from "@babel/core";
+import type { PluginItem } from "@babel/core";
+import type { Plugin } from "rolldown";
+
+export interface BabelOptions {
+  babelHelpers?: "bundled" | "runtime" | "inline" | "external";
+  /**
+   * The babel config file to use.
+   *
+   * - `undefined`: auto-detect the project's babel config (via babel's own
+   *   config resolution).
+   * - a string: use that config file.
+   * - `false`: ignore config files entirely.
+   *
+   * Without a config file, templates, decorators, and TypeScript are still
+   * handled (see `defaultPlugins`).
+   */
+  configFile?: string | false;
+  /**
+   * Extra babel plugins to run, appended after the config's plugins.
+   */
+  plugins?: PluginItem[];
+  /**
+   * Opt additional files into babel (see maybeBabel's `filter`). Use this to
+   * cover addons that ship code needing babel (e.g. `ember-concurrency`).
+   */
+  filter?: {
+    include: {
+      imports: string[];
+      code: (string | RegExp)[];
+    };
+  };
+}
+
+/**
+ * Resolve the project's root babel config the way babel itself does
+ * (`babel.config.{js,cjs,mjs,cts,json}`, honoring `rootMode` semantics).
+ *
+ * The sync API evaluates the config file; on node 24+ that works for native
+ * ESM configs too (require(esm)).
+ */
+function detectConfigFile(): string | undefined {
+  const partial = loadPartialConfigSync({ cwd: process.cwd() });
+
+  return partial?.config ?? undefined;
+}
+
+/**
+ * Everything a library without its own babel config needs:
+ *
+ * - TypeScript stripping
+ * - template compilation to `precompileTemplate` (`targetFormat: "hbs"`).
+ *   Published libraries must NOT ship wire format: the wire format is
+ *   private between the template compiler and the glimmer runtime of the
+ *   same version, so baking it in ties the published artifact to the
+ *   consuming app's exact ember-source. The consuming app performs final
+ *   compilation.
+ * - decorator-transforms, with its runtime left as a bare specifier so the
+ *   consuming app resolves it (the library keeps `decorator-transforms` as
+ *   a real dependency).
+ */
+function defaultPlugins(): PluginItem[] {
+  return [
+    [
+      transformTypeScript,
+      {
+        allExtensions: true,
+        onlyRemoveTypeImports: true,
+        allowDeclareFields: true,
+      },
+    ],
+    [templateCompilation, { targetFormat: "hbs" }],
+    [
+      decoratorTransforms,
+      {
+        // Emit `import ... from "decorator-transforms/runtime-esm"` as a bare
+        // specifier so it stays external and the consuming app resolves it.
+        runtime: { import: "decorator-transforms/runtime-esm" },
+      },
+    ],
+  ];
+}
+
+/**
+ * We still need babel (not just oxc/rolldown's native transforms) for two
+ * reasons:
+ *
+ * - template compilation: `babel-plugin-ember-template-compilation` turns the
+ *   content-tag output into `precompileTemplate` calls; oxc has no equivalent.
+ * - decorators: Ember uses the legacy/stage-1 decorator signature together
+ *   with `decorator-transforms`, which rewrites decorated class fields
+ *   (`@tracked x`) into getter/setters backed by a runtime. oxc's native
+ *   "legacy decorators" emit tsc-style `__decorate` output, which does not
+ *   match those semantics.
+ *
+ * But we don't want to send *every* file through babel and give back the speed
+ * rolldown/oxc buys us -- so we run babel via `maybeBabel`, which filters down
+ * to only the files that actually need it (template-tag, decorators, template
+ * imports). Everything else stays on the native transform.
+ *
+ * The library's own babel config is used when it exists; without one,
+ * `defaultPlugins` covers templates, decorators, and TypeScript, so no
+ * config file is required.
+ *
+ * Libraries default to `babelHelpers: "bundled"` so the emitted output is
+ * self-contained.
+ */
+export function emberBabel(options: BabelOptions = {}): Plugin {
+  const configFile = options.configFile === undefined ? detectConfigFile() : options.configFile;
+
+  const shared = {
+    babelHelpers: options.babelHelpers ?? "bundled",
+    filter: options.filter,
+  };
+
+  if (configFile) {
+    return maybeBabel({
+      ...shared,
+      configFile,
+      plugins: options.plugins ?? [],
+    }) as unknown as Plugin;
+  }
+
+  return maybeBabel({
+    ...shared,
+    // No config file (or the caller opted out): don't let babel go looking
+    // for one -- we provide the whole plugin list inline.
+    configFile: false,
+    babelrc: false,
+    plugins: defaultPlugins().concat(options.plugins ?? []),
+  }) as unknown as Plugin;
+}

package/packages/rolldown/src/define-config.ts

@@ -0,0 +1,32 @@
+import type { UserConfig } from "tsdown";
+
+/**
+ * tsdown's config, set up for an Ember v2 library: builds your entry to
+ * `dist/*.js` and `dist/*.d.ts` with sourcemaps, cleaning `dist/` between
+ * builds and leaving the ember virtual packages to the consuming app.
+ *
+ * You choose the `entry` and the `plugins` (e.g. `ember()`); any tsdown
+ * option you pass wins.
+ *
+ * ```js
+ * import { defineConfig, ember } from "@nullvoxpopuli/ember-rolldown";
+ *
+ * export default defineConfig({
+ *   entry: ["./src/index.ts"],
+ *   plugins: [ember()],
+ * });
+ * ```
+ */
+export function defineConfig(config: UserConfig): UserConfig {
+  return {
+    sourcemap: true,
+    clean: true,
+    dts: true,
+    // tsdown's extensions are .mjs/.d.mts otherwise, even in type-module
+    // packages; exports maps conventionally point at .js/.d.ts
+    outExtensions: () => ({ js: ".js", dts: ".d.ts" }),
+    // provided by the consuming app
+    neverBundle: ["node:*", "@ember/*", "@glimmer/*"],
+    ...config,
+  };
+}

package/packages/rolldown/src/externals.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+
+import type { Plugin } from "rolldown";
+
+// @embroider/core is cjs, so we default-import and destructure.
+import pkg from "@embroider/core";
+const { emberVirtualPackages, emberVirtualPeerDeps, packageName, templateCompilationModules } = pkg;
+
+const compilationModules = new Set(templateCompilationModules.map((m) => m.module));
+
+/**
+ * @param {string} path
+ */
+function readJsonSync(path: string) {
+  return JSON.parse(readFileSync(path, { encoding: "utf8" }));
+}
+
+/**
+ * Everything the library declares as a `dependency` or `peerDependency` is
+ * resolvable by the consuming app, so we never bundle it.
+ */
+function resolvableDependencies(): Set<string> {
+  const deps = new Set<string>();
+  const manifest = readJsonSync("package.json");
+
+  for (const name of Object.keys(manifest.dependencies ?? {})) {
+    deps.add(name);
+  }
+  for (const name of Object.keys(manifest.peerDependencies ?? {})) {
+    deps.add(name);
+  }
+
+  return deps;
+}
+
+/**
+ * Keeps the library's declared dependencies and the ember virtual packages
+ * (things like `@ember/component`, `@glimmer/tracking`, the template compiler,
+ * …) external, so the app that consumes the library resolves them instead of
+ * the library bundling copies of them.
+ */
+export function emberExternals(): Plugin {
+  let deps: Set<string>;
+
+  return {
+    name: "ember:externals",
+
+    buildStart() {
+      this.addWatchFile("package.json");
+      deps = resolvableDependencies();
+    },
+
+    resolveId: {
+      order: "pre",
+      handler(source) {
+        // Anything with a protocol (`node:`, virtual modules, …) is not ours
+        // to externalize.
+        if (source.includes(":")) {
+          return null;
+        }
+
+        const pkgName = packageName(source);
+
+        if (!pkgName) {
+          // No package name means a relative import, which we don't deal with.
+          return null;
+        }
+
+        if (
+          deps.has(pkgName) ||
+          emberVirtualPeerDeps.has(pkgName) ||
+          emberVirtualPackages.has(pkgName) ||
+          compilationModules.has(pkgName)
+        ) {
+          // `false` tells rolldown to treat the id as external.
+          return false;
+        }
+
+        return undefined;
+      },
+    },
+  };
+}

package/packages/rolldown/src/isolated-declarations.ts

@@ -0,0 +1,65 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+import type { Plugin } from "rolldown";
+
+/**
+ * Errors the build when a `tsconfig.json` is present without
+ * `isolatedDeclarations: true`.
+ *
+ * This is required: declarations for `.gts`/`.gjs` (template tag) modules can
+ * only be emitted by the isolated-declarations pipeline, which reads compiled
+ * modules from the bundler's module graph. The `tsc`-based pipeline reads
+ * source files from disk, where the compiled modules don't exist, and fails
+ * with "Source file not found".
+ *
+ * Failing fast here -- rather than only when declaration emit happens to run
+ * -- keeps the project honest: editors and `tsc`/`ember-tsc` then check the
+ * same rules the build enforces (exported values need explicit type
+ * annotations, e.g. `export const X: TOC<Sig> = <template>...`).
+ *
+ * Projects without a `tsconfig.json` (JavaScript libraries) or without the
+ * `typescript` package have no declarations to emit, so there is nothing to
+ * check.
+ */
+export function emberIsolatedDeclarations(): Plugin {
+  return {
+    name: "ember:isolated-declarations",
+
+    async buildStart() {
+      const tsconfigPath = resolve("tsconfig.json");
+
+      if (!existsSync(tsconfigPath)) return;
+
+      let ts: typeof import("typescript");
+
+      try {
+        ts = (await import("typescript")).default;
+      } catch {
+        return;
+      }
+
+      const { config, error } = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+
+      if (error) {
+        // Unreadable/unparsable tsconfig: tsc itself will report this with a
+        // better message than we can.
+        return;
+      }
+
+      // Resolves `extends` chains, so the flag may come from a base config.
+      const parsed = ts.parseJsonConfigFileContent(config, ts.sys, dirname(tsconfigPath));
+
+      if (parsed.options.isolatedDeclarations !== true) {
+        this.error(
+          `${tsconfigPath} must set "compilerOptions.isolatedDeclarations": true.\n\n` +
+            `Declarations for .gts/.gjs (template tag) modules can only be emitted by the ` +
+            `isolated-declarations pipeline, which reads compiled modules from the bundler's ` +
+            `module graph -- the tsc-based pipeline reads from disk and cannot see them.\n\n` +
+            `Isolated declarations require exported values to have explicit type annotations, ` +
+            `e.g. \`export const X: TOC<Sig> = <template>...\`.`,
+        );
+      }
+    },
+  };
+}

package/packages/rolldown/src/transform.ts

@@ -0,0 +1,162 @@
+import { Preprocessor } from "content-tag";
+import { existsSync } from "node:fs";
+import { readFile, writeFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import type { Plugin } from "rolldown";
+
+const processor = new Preprocessor();
+
+/**
+ * `.d.ts` files emitted for `.gts` source reference the original `.gts`
+ * specifiers. Consumers can't resolve those, so we rewrite them back to
+ * extension-less specifiers.
+ */
+function fixDeclarationImports(content: string): string {
+  return content
+    .replace(/from\s+'([^']+)\.gts'/g, "from '$1'")
+    .replace(/from\s+"([^"]+)\.gts"/g, 'from "$1"')
+    .replace(/import\("([^"]+)\.gts"\)/g, 'import("$1")')
+    .replace(/import\('([^']+)\.gts'\)/g, "import('$1')");
+}
+
+async function fixDtsExtensionsInDir(dir: string): Promise<void> {
+  const entries = await readdir(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      await fixDtsExtensionsInDir(fullPath);
+    } else if (entry.name.endsWith(".d.ts")) {
+      const content = await readFile(fullPath, { encoding: "utf8" });
+      const fixed = fixDeclarationImports(content);
+
+      if (fixed !== content) {
+        await writeFile(fullPath, fixed);
+      }
+    }
+  }
+}
+
+/**
+ * Maps `.gts` -> `.ts` and `.gjs` -> `.js` (so rolldown can identify them as
+ * ts/js) and preprocesses `<template>` via content-tag.
+ */
+export function emberTransform(): Plugin {
+  const virtualFiles = new Set<string>();
+
+  return {
+    name: "ember:transform",
+
+    resolveId: {
+      order: "pre",
+      handler(id, importer) {
+        if (!importer) return null;
+
+        const fileName = path.join(path.dirname(importer), id);
+
+        if (id.endsWith(".gts") && !importer.endsWith(".d.ts")) {
+          virtualFiles.add(fileName);
+          return {
+            id: fileName.replace(/\.gts$/, ".ts"),
+            meta: { fileName },
+          };
+        }
+
+        if (id.endsWith(".gjs") && !importer.endsWith(".d.ts")) {
+          virtualFiles.add(fileName);
+          return {
+            id: fileName.replace(/\.gjs$/, ".js"),
+            meta: { fileName },
+          };
+        }
+
+        if (id.endsWith(".d.ts") && importer.endsWith(".d.ts")) {
+          const gtsFile = fileName.replace(".d.ts", ".gts");
+          if (virtualFiles.has(gtsFile)) {
+            return fileName;
+          }
+        }
+
+        if (id.endsWith(".ts") && !importer.endsWith(".d.ts")) {
+          const gtsFileName = fileName.replace(/\.ts$/, ".gts");
+          if (existsSync(gtsFileName) && !existsSync(fileName)) {
+            virtualFiles.add(gtsFileName);
+            return { id: fileName, meta: { fileName: gtsFileName } };
+          }
+        }
+
+        if (id.endsWith(".js") && !importer.endsWith(".d.ts")) {
+          const gjsFileName = fileName.replace(/\.js$/, ".gjs");
+          if (existsSync(gjsFileName) && !existsSync(fileName)) {
+            virtualFiles.add(gjsFileName);
+            return { id: fileName, meta: { fileName: gjsFileName } };
+          }
+        }
+
+        return null;
+      },
+    },
+
+    load: {
+      order: "pre",
+      filter: {
+        id: /\.(ts|js)$/,
+      },
+      async handler(id) {
+        const meta = this.getModuleInfo(id)?.meta ?? {};
+        const fileName = meta?.fileName;
+
+        if (fileName) {
+          this.addWatchFile(fileName);
+          const source = await readFile(fileName, { encoding: "utf8" });
+
+          if (source.includes("<template>")) {
+            const { code, map } = processor.process(source, {
+              filename: fileName,
+            });
+            return { code, map };
+          }
+
+          return source;
+        }
+
+        return null;
+      },
+    },
+
+    transform: {
+      order: "pre",
+      filter: {
+        code: /\.gts/,
+        id: /\.(js|ts)$/,
+      },
+      handler(input, id) {
+        if (input.includes(".gts") && id.endsWith(".d.ts")) {
+          return input.replace(
+            /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
+            (_m, q, p) => `${q}${p.replace(/\.gts$/, ".d.ts")}${q}`,
+          );
+        }
+
+        if (input.includes(".gts") && !id.endsWith(".d.ts")) {
+          return input.replace(
+            /(['"`])((?:\.\.?\/|\/|@|[A-Za-z0-9_\-])[^'"]*?\.gts)\1/g,
+            (_m, q, p) => `${q}${p.replace(/\.gts$/, ".ts")}${q}`,
+          );
+        }
+
+        return input;
+      },
+    },
+
+    writeBundle: {
+      async handler(options) {
+        const outDir = (options as { dir?: string }).dir;
+        if (outDir) {
+          await fixDtsExtensionsInDir(path.resolve(outDir));
+        }
+      },
+    },
+  };
+}

package/packages/vite/README.md

@@ -8,7 +8,9 @@ A speed-optimized default meta-config for ember projects.
 npm add @nullvoxpopuli/ember-vite
 ```
 
-Requires node 24+
+Requires node 24+, and — since these packages ship TypeScript source — a
+modern TypeScript when type-checking: 6+ with `lib` covering `es2025` (e.g.
+`esnext`).
 
 ## Usage
 
@@ -43,34 +45,18 @@ The `ember()` plugin takes the following options:
 
 ```ts
 ember({
-  // optional production configs
   production: {
-    // optional configuration of codeSplitting.groups
-    // in the vite config.
-    //
-    // Docs here:
-    // https://rolldown.rs/reference/OutputOptions.codeSplitting#groups
     codeSplittingGroups: [
-      /* ... */
+      /* https://rolldown.rs/reference/OutputOptions.codeSplitting#groups */
     ],
   },
-  // optional babel config
   babel: {
-    // defaults to true.
-    // when babel runs, do so in parallel across many cores.
     parallel: false,
-    // optional way to configure when babel is activateed.
-    // by default, all transforming is oxc, except when babel is needed
-    // (for things not currently implemented in oxc)
     include: {
-      // if a file imports from anything in this array, use babel instead of
-      // oxc for that file.
-      //
-      // For example: ['ember-concurrency', 'ember-intl/format-message'],
-      whenImporting: [
-        /* ... */
-      ],
+      whenImporting: ["ember-concurrency", "ember-intl/format-message"],
     },
   },
 });
 ```
+
+Each option is documented on its type.

package/packages/vite/index.ts

@@ -1,2 +1,2 @@
 export { ember } from "./src/ember.ts";
-export { maybeBabel } from "./src/maybe-babel.ts";
+export { maybeBabel } from "@nullvoxpopuli/ember-build-tooling-utils";