ember.nvp 0.6.0 → 1.0.0

package/packages/vite/src/ember.ts

@@ -1,9 +1,12 @@
+import { buildMacros } from "@embroider/macros/babel";
 import { ember as embroiderEmber, extensions, resolver, templateTag } from "@embroider/vite";
 import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import type { ConfigEnv, ResolvedConfig } from "vite";
 
-import { maybeBabel } from "./maybe-babel.ts";
+import { maybeBabel } from "@nullvoxpopuli/ember-build-tooling-utils";
+
+import { testHtml } from "./test-html.ts";
 
 const emberConfig = embroiderEmber()[3]!;
 
@@ -12,6 +15,92 @@ function absolutePath(relativePath: string) {
   return join(cwd, relativePath);
 }
 
+/**
+ * Everything a project without its own babel config needs:
+ *
+ * - TypeScript stripping
+ * - template compilation (wire format: vite serves/bundles for the
+ *   project's own ember-source, so the final compile happens here)
+ * - build macros, evaluated at build time
+ * - decorator-transforms, with its runtime left as a bare specifier so it
+ *   resolves from the project (which depends on `decorator-transforms`)
+ *
+ * The plugins are named, not imported: babel resolves them from the
+ * project, which carries them as its own dependencies.
+ */
+function defaultBabelPlugins() {
+  const macros = buildMacros();
+
+  return [
+    [
+      "@babel/plugin-transform-typescript",
+      {
+        allExtensions: true,
+        onlyRemoveTypeImports: true,
+        allowDeclareFields: true,
+      },
+    ],
+    ["babel-plugin-ember-template-compilation", { transforms: [...macros.templateMacros] }],
+    ["module:decorator-transforms", { runtime: { import: "decorator-transforms/runtime-esm" } }],
+    ...macros.babelMacros,
+  ];
+}
+
+type BabelOptions =
+  | { configFile: string }
+  | {
+      configFile: false;
+      babelrc: false;
+      babelHelpers: "inline";
+      plugins: ReturnType<typeof defaultBabelPlugins>;
+    };
+
+/**
+ * The project's babel config wins when it exists -- `babel.configFile`
+ * selects which one (e.g. a test-only `config/test/babel.config.js`).
+ * Without one (libraries), `defaultBabelPlugins` covers TypeScript,
+ * templates, macros, and decorators, so no config file is required --
+ * helpers are inlined because projects without a babel config don't
+ * carry `@babel/runtime`.
+ */
+function babelOptions(nvpConfig: Config): BabelOptions {
+  const configFile = resolve(
+    join(process.cwd(), nvpConfig.babel?.configFile ?? "./babel.config.js"),
+  );
+
+  if (existsSync(configFile)) {
+    return { configFile };
+  }
+
+  return {
+    configFile: false,
+    babelrc: false,
+    babelHelpers: "inline",
+    plugins: defaultBabelPlugins(),
+  };
+}
+
+/**
+ * Additional opt-ins beyond maybeBabel's built-in list.
+ *
+ * These libraries ship code that still needs babel (ember-concurrency's
+ * decorators, ember-scoped-css transforms, ember-intl's formatMessage macro),
+ * and the `initializeRuntimeMacrosConfig` runtime call must be compiled away.
+ */
+function babelFilter(nvpConfig: Config) {
+  return {
+    include: {
+      imports: [
+        "ember-concurrency",
+        "ember-scoped-css",
+        "ember-intl/helpers/format-message",
+        ...(nvpConfig.babel?.include?.whenImporting ?? []),
+      ],
+      code: [/\bintl\.formatMessage\b/, "initializeRuntimeMacrosConfig"] as (string | RegExp)[],
+    },
+  };
+}
+
 interface Config {
   babel?: {
     /**
@@ -20,6 +109,16 @@ interface Config {
      */
     parallel?: false;
 
+    /**
+     * which babel config file to use for this build, relative to the
+     * project root. defaults to "./babel.config.js".
+     *
+     * useful when the root babel config belongs to another pipeline
+     * (e.g. a library's publish build) and the vite build needs its own,
+     * such as "./config/test/babel.config.js".
+     */
+    configFile?: string;
+
     /**
      * optional way to configure when babel is activateed.
      * by default, all transforming is oxc, except when babel is needed
@@ -51,8 +150,8 @@ interface Config {
 }
 
 export function ember(nvpConfig: Config = {}) {
-  const babelConfigFile = resolve(join(process.cwd(), "./babel.config.js"));
-  const defaultEnv = { mode: process.env.NODE_ENV || "development" };
+  const babel = babelOptions(nvpConfig);
+  const filter = babelFilter(nvpConfig);
 
   /*
    * Plugins must be returned as top-level array entries — NOT pushed into
@@ -98,16 +197,21 @@ export function ember(nvpConfig: Config = {}) {
           // Libraries will have precompileTemplate and macros, etc,
           // and we need to compile that away using this app's
           // template compiler
-          maybeBabel({ env, parallel: nvpConfig.babel?.parallel, configFile: babelConfigFile }),
+          maybeBabel({
+            ...babel,
+            parallel: nvpConfig.babel?.parallel,
+            filter,
+          }),
         ];
       },
     },
     resolver({ rolldown: true }),
     templateTag(),
+    testHtml(),
     maybeBabel({
-      env: defaultEnv,
+      ...babel,
       parallel: nvpConfig.babel?.parallel,
-      configFile: babelConfigFile,
+      filter,
     }),
   ];
 }
@@ -146,13 +250,10 @@ function dev(viteConfig: ResolvedConfig, nvpConfig: Config) {
   viteConfig.build.rolldownOptions.input ||= {};
   viteConfig.build.rolldownOptions.output ||= {};
 
-  Object.assign(viteConfig.build.rolldownOptions.input, {
-    main: absolutePath("./index.html"),
-  });
-
-  if (existsSync("./tests.html")) {
+  // libraries don't, by default, have a "demo app" entrypoint
+  if (existsSync("./index.html")) {
     Object.assign(viteConfig.build.rolldownOptions.input, {
-      tests: absolutePath("./tests.html"),
+      main: absolutePath("./index.html"),
     });
   }
 
@@ -160,6 +261,16 @@ function dev(viteConfig: ResolvedConfig, nvpConfig: Config) {
     Object.assign(viteConfig.build.rolldownOptions.input, {
       tests: absolutePath("./tests/index.html"),
     });
+  } else if (existsSync("./tests.html")) {
+    Object.assign(viteConfig.build.rolldownOptions.input, {
+      tests: absolutePath("./tests.html"),
+    });
+  } else if (existsSync("./tests")) {
+    // no html of its own: the default-test-html plugin answers for
+    // tests/index.html
+    Object.assign(viteConfig.build.rolldownOptions.input, {
+      tests: absolutePath("./tests/index.html"),
+    });
   }
 
   Object.assign(viteConfig.build.rolldownOptions.output, {
@@ -203,9 +314,12 @@ function prod(viteConfig: ResolvedConfig, nvpConfig: Config) {
   viteConfig.build.rolldownOptions.optimization ||= {};
   viteConfig.build.rolldownOptions.output ||= {};
 
-  Object.assign(viteConfig.build.rolldownOptions.input, {
-    main: absolutePath("./index.html"),
-  });
+  // libraries don't, by default, have a "demo app" entrypoint
+  if (existsSync("./index.html")) {
+    Object.assign(viteConfig.build.rolldownOptions.input, {
+      main: absolutePath("./index.html"),
+    });
+  }
 
   Object.assign(viteConfig.build.rolldownOptions.optimization, {
     inlineConst: {

package/packages/vite/src/test-html.ts

@@ -0,0 +1,86 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ViteDevServer } from "vite";
+
+/**
+ * Everything a QUnit + testem run needs, with no project-specific
+ * references: root-relative specifiers keep it independent of where the
+ * project keeps its files, and the globs pick up tests/** as well as
+ * co-located `*-test` modules under src/**.
+ */
+const DEFAULT_TEST_HTML = `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Tests</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="qunit"></div>
+    <div id="qunit-fixture">
+      <div id="ember-testing-container">
+        <div id="ember-testing"></div>
+      </div>
+    </div>
+
+    <script src="/testem.js" integrity="" data-embroider-ignore></script>
+    <script type="module">
+      import "ember-testing";
+    </script>
+
+    <script type="module">
+      import { start } from "/tests/test-helper";
+      import.meta.glob("/tests/**/*.{js,ts,gjs,gts}", { eager: true });
+      import.meta.glob("/src/**/*-test.{js,ts,gjs,gts}", { eager: true });
+      start();
+    </script>
+  </body>
+</html>
+`;
+
+/**
+ * Lets a project run its tests without maintaining a tests/index.html:
+ * whenever that file is absent, this plugin answers for it -- `load`
+ * supplies the html to the build (so `tests/index.html` still lands in
+ * dist for testem), and the dev-server middleware serves it (through
+ * `transformIndexHtml`, so the html goes through the same pipeline as an
+ * on-disk file).
+ *
+ * A tests/index.html on disk always wins; every hook here defers to it.
+ */
+export function testHtml() {
+  const htmlPath = join(process.cwd(), "tests", "index.html");
+
+  return {
+    name: "ember:default-test-html",
+
+    resolveId(id: string) {
+      if (id === htmlPath && !existsSync(htmlPath)) {
+        return id;
+      }
+    },
+
+    load(id: string) {
+      if (id === htmlPath && !existsSync(htmlPath)) {
+        return DEFAULT_TEST_HTML;
+      }
+    },
+
+    configureServer(server: ViteDevServer) {
+      server.middlewares.use(async (req, res, next) => {
+        if (existsSync(htmlPath)) return next();
+
+        const url = (req.url ?? "").split("?")[0];
+
+        if (url !== "/tests" && url !== "/tests/" && url !== "/tests/index.html") {
+          return next();
+        }
+
+        const html = await server.transformIndexHtml("/tests/index.html", DEFAULT_TEST_HTML);
+
+        res.setHeader("Content-Type", "text/html");
+        res.end(html);
+      });
+    },
+  };
+}

package/src/bases/minimal-app/files/app/router.ts

@@ -1,4 +1,5 @@
 import EmbroiderRouter from "@embroider/router";
+
 import config from "#config";
 
 export default class Router extends EmbroiderRouter {

package/src/bases/minimal-app/files/tsconfig.json

@@ -2,6 +2,7 @@
   "extends": "@ember/app-tsconfig",
   "compilerOptions": {
     "allowJs": true,
+    "lib": ["esnext", "dom", "dom.iterable"],
     "types": [
       "ember-source/types",
       "@embroider/core/virtual",

package/src/bases/minimal-app/index.js

@@ -1,6 +1,6 @@
 import { packageJson, js } from "ember-apply";
+import { join } from "node:path";
 import { getLatest } from "#utils/npm.js";
-import { fileURLToPath } from "node:url";
 import { applyFolderTo } from "#utils/fs.js";
 import { removeConfiguredPlugin } from "#utils/babel.js";
 
@@ -49,7 +49,7 @@ async function updateBabelConfig(project) {
  * @param {import('#utils/project.js').Project} project
  */
 async function applyFiles(project) {
-  let filePath = fileURLToPath(new URL("files", import.meta.url));
+  let filePath = join(import.meta.dirname, "files");
 
   await applyFolderTo(filePath, project);
 }

package/src/bases/minimal-library/files/README.md

@@ -0,0 +1,41 @@
+# minimal-library
+
+An Ember v2 library (addon) built with
+[`@nullvoxpopuli/ember-rolldown`](https://github.com/NullVoxPopuli/ember.nvp/tree/main/packages/rolldown)
+and [tsdown](https://tsdown.dev/).
+
+## Development
+
+```bash
+pnpm install
+```
+
+Build the distributable (JS + `.d.ts` into `dist/`):
+
+```bash
+pnpm build
+```
+
+Rebuild on change while developing:
+
+```bash
+pnpm start
+```
+
+## Structure
+
+- `src/` — your library source. Author components in `.gts`/`.gjs`
+  (template-tag) and plain modules in `.ts`/`.js`.
+- `src/index.ts` — the public entry point. Everything a consumer can import
+  must be re-exported from here (or added as an entry in `tsdown.config.js`).
+- `dist/` — the built output that gets published (git-ignored).
+
+Declarations are emitted with
+[isolated declarations](https://www.typescriptlang.org/tsconfig/#isolatedDeclarations),
+so every exported value needs an explicit type annotation — in particular,
+annotate exported template-only components with `TOC<...>`.
+
+## Publishing
+
+`dist/` is built automatically on `prepack`, so `npm publish` ships the
+compiled output plus your `src/`.

package/src/bases/minimal-library/files/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "minimal-library",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Your Ember library's description here",
+  "license": "MIT",
+  "author": "",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "start": "tsdown --watch"
+  },
+  "dependencies": {
+    "decorator-transforms": "^2.3.2"
+  },
+  "peerDependencies": {
+    "@glimmer/component": "^2.0.0",
+    "ember-source": ">= 6.0.0"
+  },
+  "devDependencies": {
+    "@ember/library-tsconfig": "^2.0.0",
+    "@glimmer/component": "^2.1.1",
+    "@nullvoxpopuli/ember-rolldown": "workspace:*",
+    "ember-source": "~7.0.0",
+    "tsdown": "^0.22.7",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">= 24"
+  },
+  "ember": {
+    "edition": "octane"
+  }
+}

package/src/bases/minimal-library/files/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@ember/library-tsconfig",
+  "include": ["src"],
+  "compilerOptions": {
+    "rootDir": "./src",
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "isolatedDeclarations": true,
+    "types": ["ember-source/types", "@glint/ember-tsc/types"]
+  }
+}

package/src/bases/minimal-library/files/tsdown.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from "tsdown";
+import { ember } from "@nullvoxpopuli/ember-rolldown";
+
+export default defineConfig({
+  entry: ["./src/index.ts"],
+  plugins: [ember()],
+});

package/src/bases/minimal-library/index.js

@@ -1,10 +1,166 @@
+import { packageJson } from "ember-apply";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getLatest } from "#utils/npm.js";
+import { applyFolderTo } from "#utils/fs.js";
+import { removeConfiguredPlugin } from "#utils/babel.js";
+
+/**
+ * Minimal Library Base
+ *
+ * Provides the absolute bare minimum for an Ember v2 library (addon):
+ * - type: "module" in package.json
+ * - built with tsdown + @nullvoxpopuli/ember-rolldown
+ * - a sample `<template>` component and a plain module
+ * - No babel.config.js: ember() covers TS stripping, template compilation,
+ *   and decorators
+ * - No testing framework
+ * - No linting or formatting
+ *
+ * Testing, linting, formatting, etc. are opt-in via layers.
+ */
 export default {
   label: "Minimal Library Base",
-  description: "Bare minimum library structure",
+  description: "Bare minimum Ember v2 library (addon) structure",
 
   /**
+   * 1. Apply files
+   *   a. Remove TS if needed
+   * 2. Update name(s)
+   * 3. Make publishable
+   * 4. Remove TS deps/files/config if needed
+   * 5. Upgrade in-range dependencies
+   * 6. Update an existing babel config, if any
    *
    * @param {import('#utils/project.js').Project} project
    */
-  async run(project) {},
+  async run(project) {
+    await applyFiles(project);
+    await updateName(project);
+    await makePublishable(project);
+    await makeJavaScript(project);
+    await upgradeDependencies(project);
+    await updateBabelConfig(project);
+  },
 };
+
+/**
+ * @param {import('#utils/project.js').Project} project
+ */
+async function applyFiles(project) {
+  let filePath = join(import.meta.dirname, "files");
+
+  await applyFolderTo(filePath, project);
+}
+
+/**
+ * Operates on known files where the name matters
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updateName(project) {
+  await packageJson.modify((json) => {
+    json.name = project.desires.name;
+  }, project.directory);
+}
+
+/**
+ * The template's package.json is `private: true` so it can never be
+ * published from this repo; the generated library exists to be published,
+ * so the flag is removed entirely.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function makePublishable(project) {
+  await packageJson.modify((json) => {
+    delete json.private;
+  }, project.directory);
+}
+
+/**
+ * When the project is JavaScript (no typescript layer), remove the TS
+ * toolchain, drop the tsconfig, and point the build at the emitted `.js`
+ * entry (declarations can't be produced without types).
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function makeJavaScript(project) {
+  if (await project.hasOrWantsLayer("typescript")) return;
+
+  await packageJson.removeDevDependencies(
+    ["@babel/plugin-transform-typescript", "@ember/library-tsconfig", "typescript"],
+    project.directory,
+  );
+
+  await project.removeFile("tsconfig.json");
+
+  await removeTypesExports(project);
+  await pointBuildAtJavaScript(project);
+}
+
+/**
+ * No declarations are emitted for a JavaScript library, so the `types`
+ * export conditions would point at files that never exist.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function removeTypesExports(project) {
+  await packageJson.modify((json) => {
+    for (let condition of Object.values(json.exports ?? {})) {
+      if (condition && typeof condition === "object") {
+        delete condition.types;
+      }
+    }
+  }, project.directory);
+}
+
+/**
+ * Rewrites the tsdown config so it builds the JavaScript entry and stops
+ * emitting declarations (defineConfig defaults to `dts: true`).
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function pointBuildAtJavaScript(project) {
+  let configPath = project.path("tsdown.config.js");
+  let contents = await readFile(configPath, "utf-8");
+
+  contents = contents.replace(
+    `entry: ["./src/index.ts"],`,
+    `entry: ["./src/index.js"],\n  dts: false,`,
+  );
+
+  await writeFile(configPath, contents);
+}
+
+/**
+ * Bumps in-range only.
+ * Majors will need to go through PR to this repo.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function upgradeDependencies(project) {
+  let existing = await packageJson.read(project.directory);
+
+  await packageJson.modify(async (json) => {
+    if (json.dependencies) {
+      Object.assign(json.dependencies, await getLatest(existing.dependencies));
+    }
+    if (json.devDependencies) {
+      Object.assign(json.devDependencies, await getLatest(existing.devDependencies));
+    }
+  }, project.directory);
+}
+
+/**
+ * The base doesn't emit a babel.config.js, but this can run over an
+ * existing project that has one -- and a JavaScript project's config
+ * must not reference the TS plugin.
+ *
+ * @param {import('#utils/project.js').Project} project
+ */
+async function updateBabelConfig(project) {
+  if (await project.hasOrWantsLayer("typescript")) return;
+  if (!project.hasFile("babel.config.js")) return;
+
+  await removeConfiguredPlugin(project, "@babel/plugin-transform-typescript");
+}

package/src/cli/index.js

@@ -10,7 +10,8 @@ import { askPath } from "./questions/path.js";
 import { askIfOK } from "./questions/ok.js";
 import { askToWrite } from "./questions/write.js";
 import { styleText } from "node:util";
-import { rm } from "node:fs/promises";
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
 import { Project } from "#utils/project.js";
 import { Stage } from "#utils/stage.js";
 import { askReplaceOrUpdate } from "./questions/replace-or-update.js";
@@ -31,7 +32,7 @@ async function main() {
   const projectPath = await askPath(projectName);
   const replaceOrUpdate = await askReplaceOrUpdate(projectPath);
   const projectType = await askProjectType();
-  const selectedLayers = await askLayers();
+  const selectedLayers = await askLayers(projectType);
   const packageManager = await askPackageManager();
 
   await askIfOK();
@@ -120,9 +121,27 @@ async function main() {
 
   p.log.success(`Applied ${toApply.length} change${toApply.length === 1 ? "" : "s"}`);
 
+  /**
+   * Converted / generated files are written expecting the project's own
+   * formatting and lint pass to run right away (e.g. blank lines between
+   * import groups are `eslint --fix`'s job) -- so when the project has a
+   * lint:fix script, surface it as the step right after install.
+   */
+  let lintFixStep = "";
+  try {
+    const manifest = JSON.parse(await readFile(join(projectPath, "package.json"), "utf-8"));
+
+    if (manifest.scripts?.["lint:fix"]) {
+      lintFixStep = `${packageManager} ${packageManager === "npm" ? "run " : ""}lint:fix\n`;
+    }
+  } catch {
+    // no readable package.json -- skip the suggestion
+  }
+
   p.note(
     `cd ${projectName}\n` +
       `${packageManager} install\n` +
+      lintFixStep +
       `${packageManager} ${packageManager === "npm" ? "run " : ""}start`,
     "Next steps",
   );

package/src/cli/questions/layers.js

@@ -3,7 +3,10 @@ import { discoverLayers } from "#layers";
 
 import * as p from "@clack/prompts";
 
-export async function askLayers() {
+/**
+ * @param {import('#types').ProjectType} projectType
+ */
+export async function askLayers(projectType) {
   const optionalLayers = (await discoverLayers()).filter(
     (layer) => typeof layer.run === "function",
   );
@@ -34,7 +37,7 @@ export async function askLayers() {
   const defaultValues = (
     await Promise.all(
       optionalLayers.map(async (layer) => {
-        let result = await layer.defaultValue?.();
+        let result = await layer.defaultValue?.(projectType);
 
         return result && layer.name;
       }),

package/src/cli/questions/project-type.js

@@ -41,11 +41,6 @@ export async function askProjectType() {
     ],
   });
 
-  if (answer === "library") {
-    p.cancel("Not implemented yet, apologies!");
-    return process.exit(0);
-  }
-
   if (p.isCancel(answer)) {
     p.cancel("Operation cancelled");
     return process.exit(0);