ember.nvp 0.5.0 → 0.7.0

package/packages/rolldown/README.md

@@ -0,0 +1,115 @@
+# `@nullvoxpopuli/ember-rolldown`
+
+A batteries-included meta-plugin for building Ember v2 libraries (addons) with
+[rolldown](https://rolldown.rs/) — or [tsdown](https://tsdown.dev/), which is
+built on top of rolldown and also emits `.d.ts` files.
+
+It compiles `.gts`/`.gjs` and template-tag (`<template>`) source into
+publishable output, so a single `ember()` call replaces the usual stack of
+`@embroider/*` externals handling, content-tag preprocessing, and babel wiring.
+
+## Install
+
+```bash
+npm add --save-dev @nullvoxpopuli/ember-rolldown
+```
+
+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
+
+In your `tsdown.config.js` (recommended — emits declarations):
+
+```js
+import { defineConfig, ember } from "@nullvoxpopuli/ember-rolldown";
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  plugins: [ember()],
+});
+```
+
+This 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 `plugins`; any tsdown option you
+pass wins.
+
+Or in a plain `rolldown.config.js`:
+
+```js
+import { defineConfig } from "rolldown";
+import { ember } from "@nullvoxpopuli/ember-rolldown";
+
+export default defineConfig({
+  input: ["src/index.ts"],
+  plugins: [ember()],
+});
+```
+
+A `babel.config.js` is optional. Without one, `ember()` compiles templates
+(to `precompileTemplate`), decorators (via
+[decorator-transforms](https://github.com/ef4/decorator-transforms)), and
+TypeScript; with one, your config runs instead.
+
+### Declarations
+
+Declarations are emitted with isolated declarations — the only declaration
+pipeline that can see `<template>` (`.gts`/`.gjs`) modules, which exist only
+inside the bundler's module graph. Your `tsconfig.json` must enable it
+(`ember()` errors otherwise):
+
+```jsonc
+{
+  "compilerOptions": {
+    "isolatedDeclarations": true,
+  },
+}
+```
+
+Isolated declarations means every exported value carries an explicit type
+annotation. For template-only components:
+
+```gts
+import type { TOC } from "@ember/component/template-only";
+
+export const Badge: TOC<BadgeSignature> = <template>...</template>;
+```
+
+## What `ember()` does
+
+`ember()` returns an array of rolldown plugins:
+
+- **`emberIsolatedDeclarations()`** — errors when a `tsconfig.json` is present
+  without `isolatedDeclarations: true`.
+- **`emberExternals()`** — keeps your `dependencies`, `peerDependencies`, and
+  the ember virtual packages (e.g. `@ember/component`, `@glimmer/tracking`, the
+  template compiler) external, so the consuming app resolves them.
+- **`emberTransform()`** — preprocesses `<template>` via
+  [content-tag](https://github.com/embroider-build/content-tag) and maps
+  `.gts`/`.gjs` to `.ts`/`.js` so rolldown understands them. Also rewrites
+  `.gts` specifiers in emitted `.d.ts` files.
+- **`emberBabel()`** — runs babel with `babelHelpers: "bundled"`, but only on
+  the files that actually need it (template-tag, decorators, template imports);
+  everything else stays on rolldown's fast native (oxc) transform.
+
+## Configuration
+
+```ts
+ember({
+  babel: {
+    configFile: "./babel.config.js",
+    babelHelpers: "bundled",
+    plugins: [],
+    filter: { include: { imports: ["ember-concurrency"], code: [] } },
+  },
+});
+```
+
+Each option is documented on `BabelOptions`.
+
+## Credit
+
+The `emberExternals` and `emberTransform` plugins are derived from
+[embroider-build/embroider#2658](https://github.com/embroider-build/embroider/pull/2658).

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>...\`.`,
+        );
+      }
+    },
+  };
+}