ember.nvp 1.7.0 → 1.7.1

package/packages/vite/src/ember.ts

@@ -19,14 +19,16 @@ function absolutePath(relativePath: string) {
  * 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)
+ * - template compilation, to the wire format
+ *   (vite serves and 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`)
+ * - decorator-transforms, with its runtime left as a bare specifier
+ *   so it resolves from the project
+ *   (the project depends on `decorator-transforms`)
  *
- * The plugins are named, not imported: babel resolves them from the
- * project, which carries them as its own dependencies.
+ * The plugins are named, not imported.
+ * babel resolves them from the project, which carries them as its own dependencies.
  */
 function defaultBabelPlugins() {
   const macros = buildMacros();
@@ -56,12 +58,14 @@ type BabelOptions =
     };
 
 /**
- * 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`.
+ * 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 in that case:
+ * projects without a babel config don't carry `@babel/runtime`.
  */
 function babelOptions(nvpConfig: Config): BabelOptions {
   const configFile = resolve(
@@ -83,9 +87,12 @@ function babelOptions(nvpConfig: Config): BabelOptions {
 /**
  * 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.
+ * These libraries ship code that still needs babel:
+ * - ember-concurrency's decorators
+ * - ember-scoped-css transforms
+ * - ember-intl's formatMessage macro
+ *
+ * The `initializeRuntimeMacrosConfig` runtime call must also be compiled away.
  */
 function babelFilter(nvpConfig: Config) {
   return {
@@ -120,9 +127,10 @@ interface Config {
     configFile?: string;
 
     /**
-     * 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)
+     * optional way to configure when babel is activated.
+     *
+     * by default, all transforming is oxc,
+     * except when babel is needed (for things not currently implemented in oxc)
      */
     include?: {
       /**
@@ -154,10 +162,12 @@ export function ember(nvpConfig: Config = {}) {
   const filter = babelFilter(nvpConfig);
 
   /*
-   * Plugins must be returned as top-level array entries — NOT pushed into
-   * config.plugins inside a config() hook.  Vite 8 extracts user plugins
-   * *before* config hooks run, so anything added later is invisible to the
-   * plugin container (resolveId, load, etc. hooks never fire).
+   * Plugins must be returned as top-level array entries,
+   * NOT pushed into config.plugins inside a config() hook.
+   *
+   * Vite 8 extracts user plugins *before* config hooks run,
+   * so anything added later is invisible to the plugin container
+   * (resolveId, load, etc. hooks never fire).
    */
   return [
     {
@@ -194,9 +204,8 @@ export function ember(nvpConfig: Config = {}) {
           resolver({ rolldown: true }),
           templateTag(),
 
-          // Libraries will have precompileTemplate and macros, etc,
-          // and we need to compile that away using this app's
-          // template compiler
+          // Libraries ship precompileTemplate calls and macros.
+          // Both must compile away here, with this app's template compiler.
           maybeBabel({
             ...babel,
             parallel: nvpConfig.babel?.parallel,
@@ -231,14 +240,12 @@ function applyConfig(viteConfig: ResolvedConfig, env: ConfigEnv, nvpConfig: Conf
 }
 
 function dev(viteConfig: ResolvedConfig, nvpConfig: Config) {
-  /**************************************
-   *
+  /**
    * build config for tests
    *
-   * NOTE: we can't minify because some tests
-   *       are checking x.constructor.name, which changes when minified
-   *
-   *************************************/
+   * NOTE: we can't minify.
+   *       some tests check x.constructor.name, which changes when minified
+   */
   Object.assign(viteConfig.build, {
     sourcemap: true,
     cleanCssOptions: { sourceMap: true },
@@ -333,7 +340,8 @@ function prod(viteConfig: ResolvedConfig, nvpConfig: Config) {
     minify: true,
     cleanDir: true,
     /**
-     * This is needed due to how we manage module state.
+     * Needed due to how we manage module state.
+     *
      * This can create waterfalls when too much top-level await is used.
      */
     strictExecutionOrder: true,
@@ -342,10 +350,10 @@ function prod(viteConfig: ResolvedConfig, nvpConfig: Config) {
      */
     codeSplitting: {
       /**
-       * Kind of a shame this isn't automatic based on dynamic import usage
-       * in vite8.
-       * Kinda forces us to know every potential problem area of the app,
-       * rather than rely on automatic optimizations based on import/module usage
+       * Kind of a shame this isn't automatic based on dynamic import usage in vite8.
+       *
+       * This forces us to know every potential problem area of the app,
+       * rather than rely on automatic optimizations based on import/module usage.
        */
       groups: [...(nvpConfig?.production?.codeSplittingGroups ?? [])],
     },

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

@@ -3,10 +3,10 @@ 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/**.
+ * Everything a QUnit + testem run needs, with no project-specific references.
+ *
+ * - root-relative specifiers keep it independent of where the project keeps its files
+ * - the globs pick up tests/** as well as co-located `*-test` modules under src/**
  */
 const DEFAULT_TEST_HTML = `<!doctype html>
 <html>
@@ -39,14 +39,16 @@ const DEFAULT_TEST_HTML = `<!doctype 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).
+ * 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)
+ * - 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.
+ * 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");

package/src/bases/README.md

@@ -1,5 +1,8 @@
-Each of these base projects are _real_ projects that can be ran in these directories.
+Each base is a _real_ project.
+You can run it from its `files/` directory.
 
-For changing the name of a project, the code in the base layer's index.js should find all the places the name is used and swap it out (codemod style).
+A base never uses a template language such as ejs:
+that would make the base unrunnable.
 
-We don't want to use ejs, because it makes the base layers unrunnable.
+To change the project name, the base's `index.js` finds every place the name is used,
+and swaps it out (codemod style).

package/src/bases/minimal-app/app.test.ts

@@ -110,8 +110,9 @@ const DEBUG_MARKERS = {
 
 /**
  * Lives in app/services/ so that app.ts's eager
- * `import.meta.glob("./services/**\/*")` pulls it into the build
- * without needing to modify any generated files.
+ * `import.meta.glob("./services/**\/*")` pulls it into the build.
+ *
+ * No generated file needs to change.
  */
 const debugFixture = `
 import { assert, deprecate, warn } from "@ember/debug";
@@ -134,8 +135,10 @@ if (macroCondition(isDevelopingApp())) {
 `;
 
 /**
- * Only .js files -- the sourcemaps (.map) contain the original
- * source (with markers) even in production builds.
+ * Only .js files.
+ *
+ * The sourcemaps (.map) contain the original source (with markers),
+ * even in production builds.
  */
 async function builtJavaScript(project: Project): Promise<string> {
   let files = globSync("dist/**/*.js", { cwd: project.directory });

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

@@ -1,11 +1,10 @@
 /**
  * Looking for services that come from addons?
  *
+ * App-tree merging from libraries is not supported.
  * See: https://github.com/embroider-build/embroider/issues/2659
  *
- * We currently don't support app-tree merging from libraries.
- *
- * For services, I highly recommend looking in to either of
+ * For services, look in to either of:
  * - https://github.com/chancancode/ember-polaris-service-
  * - https://ember-primitives.pages.dev/6-utils/createService.md
  *   - https://ember-primitives.pages.dev/6-utils/createAsyncService.md

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

@@ -10,10 +10,10 @@ export default class Router extends EmbroiderRouter {
 Router.map(function () {});
 
 /**
+ * Route bundles (lazy-loaded route groups) have no nice API yet.
+ *
  * Caveat:
  * - https://github.com/embroider-build/embroider/issues/2521
- *   We don't yet have a way to do this in a nice way
- *
  */
 // function bundle(name: string, loader: () => Promise<{ default: unknown }>[]) {
 //   return {
@@ -35,7 +35,7 @@ Router.map(function () {});
 // }
 
 /**
- * Examples from:
+ * Example usage, from:
  * - https://github.com/NullVoxPopuli/limber/blob/67e2f54bbe224052e38f9a9e566d704411e65e86/apps/repl/app/router.ts#L35
  */
 // (window as any)._embroiderRouteBundles_ = [

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

@@ -5,7 +5,7 @@ import { applyFolderTo } from "#utils/fs.js";
 import { removeConfiguredPlugin } from "#utils/babel.js";
 
 /**
- * Minimal Layer
+ * Minimal App Base
  *
  * Provides the absolute bare minimum for an Ember app:
  * - type: "module" in package.json
@@ -22,8 +22,10 @@ export default {
   /**
    * 1. Apply files
    *   a. Remove TS if needed
-   * 2. Remove TS deps/files if needed
-   * 3. Update name(s)
+   * 2. Update name(s)
+   * 3. Remove TS deps/files if needed
+   * 4. Upgrade in-range dependencies
+   * 5. Update an existing babel config, if any
    *
    * @param {import('#utils/project.js').Project} project
    */
@@ -37,6 +39,8 @@ export default {
 };
 
 /**
+ * A JavaScript project's babel config must not reference the TS plugin.
+ *
  * @param {import('#utils/project.js').Project} project
  */
 async function updateBabelConfig(project) {
@@ -72,10 +76,10 @@ async function makeJavaScript(project) {
   if (await project.hasOrWantsLayer("typescript")) return;
 
   /**
-   * We don't actually remove anything, because we want intellisense for JS
+   * Intellisense for JS needs some of these,
+   * but minimal means minimal.
    *
-   * But perhaps for the sake of minimal, we do remoev it.
-   * And we add a layer later for JSDoc ased TS or something
+   * A later layer for JSDoc-based TS can add them back.
    */
   await packageJson.removeDevDependencies(
     [

package/src/bases/minimal-custom-element/files/README.md

@@ -52,19 +52,22 @@ pnpm start
 ## Structure
 
 - `src/components/counter.gts` is the Ember component.
-- `src/element.ts` is the custom element. Its `connectedCallback` renders the component
-  into the element with `renderComponent` from `@ember/renderer`. Its
-  `disconnectedCallback` destroys that render.
-- `src/register.ts` defines the tag. Consumers import this file for its side effect.
-- `src/index.ts` is the public entry point. It exports the element class and the
-  component.
+- `src/element.ts` is the custom element.
+  Its `connectedCallback` renders the component with `renderComponent` from `@ember/renderer`.
+  Its `disconnectedCallback` destroys that render.
+- `src/register.ts` defines the tag.
+  Consumers import this file for its side effect.
+- `src/index.ts` is the public entry point.
+  It exports the element class and the component.
 - `dist/` is the built output that gets published (git-ignored).
 
 ### Reactive attributes
 
-The element lists its attributes in `observedAttributes`. Each attribute change writes
-to a tracked object. The component reads its args from that object, so the DOM updates
-on the next render. To add an attribute:
+The element lists its attributes in `observedAttributes`.
+Each attribute change writes to a tracked object.
+The component reads its args from that object, so the DOM updates on the next render.
+
+To add an attribute:
 
 1. Add its name to `observedAttributes`.
 2. Give it a default value in the tracked object.
@@ -77,9 +80,10 @@ so every exported value needs an explicit type annotation.
 
 ### Development or production ember
 
-The build bundles the production build of ember. To bundle the development build,
-with assertions and deprecation messages, add the `development` condition in
-`tsdown.config.js`:
+The build bundles the production build of ember.
+
+To bundle the development build (assertions and deprecation messages),
+add the `development` condition in `tsdown.config.js`:
 
 ```js
 inputOptions: { resolve: { conditionNames: ["development"] } },

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

@@ -4,18 +4,21 @@ A [Manifest V3](https://developer.chrome.com/docs/extensions/develop/migrate/wha
 
 ## Developing
 
-The popup is a regular web page, so the fastest feedback loop is the vite dev server in a normal browser tab:
+The popup is a regular web page.
+The fastest feedback loop is the vite dev server in a normal browser tab:
 
 ```bash
 pnpm dev
 ```
 
-To run as an actual extension, build (in watch mode) and load the `dist/` directory as an unpacked extension:
+To run it as an extension, build in watch mode:
 
 ```bash
 pnpm build:watch
 ```
 
+Then load the `dist/` directory as an unpacked extension:
+
 - **Chrome / Edge / Brave**: `chrome://extensions` → enable "Developer mode" → "Load unpacked" → select `dist/`
 - **Firefox**: `about:debugging#/runtime/this-firefox` → "Load Temporary Add-on…" → select `dist/manifest.json`
 
@@ -23,9 +26,14 @@ After a rebuild, re-open the popup (or reload the extension) to see changes.
 
 ## Anatomy
 
-- `public/manifest.json` — the extension manifest; copied verbatim into `dist/`. Add [`background`](https://developer.chrome.com/docs/extensions/reference/manifest/background), [`content_scripts`](https://developer.chrome.com/docs/extensions/reference/manifest/content-scripts), permissions, and icons here as your extension grows.
-- `index.html` — the popup page (`action.default_popup`). Extension pages are served with a `script-src 'self'` Content-Security-Policy, so the app boots from `app/boot.ts` rather than an inline script.
-- `app/` — a normal Ember app. Routing uses `locationType: "none"`, since extension pages have no URL bar to bind to.
+- `public/manifest.json` is the extension manifest. It is copied verbatim into `dist/`.
+  Add [`background`](https://developer.chrome.com/docs/extensions/reference/manifest/background),
+  [`content_scripts`](https://developer.chrome.com/docs/extensions/reference/manifest/content-scripts),
+  permissions, and icons here as your extension grows.
+- `index.html` is the popup page (`action.default_popup`).
+  Extension pages forbid inline scripts, so the app boots from `app/boot.ts`.
+- `app/` is a normal Ember app.
+  Extension pages have no URL bar, so routing uses `locationType: "none"`.
 
 ## Building for release
 

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

@@ -1,11 +1,10 @@
 /**
  * Looking for services that come from addons?
  *
+ * App-tree merging from libraries is not supported.
  * See: https://github.com/embroider-build/embroider/issues/2659
  *
- * We currently don't support app-tree merging from libraries.
- *
- * For services, I highly recommend looking in to either of
+ * For services, look in to either of:
  * - https://github.com/chancancode/ember-polaris-service-
  * - https://ember-primitives.pages.dev/6-utils/createService.md
  *   - https://ember-primitives.pages.dev/6-utils/createAsyncService.md

package/src/bases/minimal-extension/files/app/config.ts

@@ -10,9 +10,11 @@ const ENV: Config = {
   environment: import.meta.env.DEV ? "development" : "production",
   rootURL: "/",
   /**
-   * Extension pages live at chrome-extension://<id>/index.html (or
-   * moz-extension://), where history-based routing has nothing to bind
-   * to. "none" keeps routing fully programmatic.
+   * Extension pages live at chrome-extension://<id>/index.html
+   * (or moz-extension://).
+   *
+   * History-based routing has nothing to bind to there.
+   * "none" keeps routing fully programmatic.
    */
   locationType: "none",
   EmberENV: {},

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

@@ -12,8 +12,8 @@ import { removeConfiguredPlugin } from "#utils/babel.js";
  * whose popup is an Ember app:
  * - type: "module" in package.json
  * - public/manifest.json copied verbatim into dist
- * - index.html popup booting from an external script (extension pages
- *   forbid inline scripts via CSP)
+ * - index.html popup booting from an external script
+ *   (extension pages forbid inline scripts via CSP)
  * - No testing framework
  * - No linting or formatting
  * - No ember-welcome-page
@@ -25,8 +25,8 @@ export default {
   /**
    * 1. Apply files
    *   a. Remove TS if needed
-   * 2. Remove TS deps/files if needed
-   * 3. Update name(s)
+   * 2. Update name(s)
+   * 3. Remove TS deps/files if needed
    * 4. Upgrade in-range dependencies
    * 5. Update an existing babel config, if any
    *
@@ -42,6 +42,8 @@ export default {
 };
 
 /**
+ * A JavaScript project's babel config must not reference the TS plugin.
+ *
  * @param {import('#utils/project.js').Project} project
  */
 async function updateBabelConfig(project) {
@@ -60,7 +62,9 @@ async function applyFiles(project) {
 }
 
 /**
- * Operates on known files where the name matters
+ * Operates on known files where the name matters.
+ *
+ * The extension's display name lives in public/manifest.json.
  *
  * @param {import('#utils/project.js').Project} project
  */
@@ -86,10 +90,10 @@ async function makeJavaScript(project) {
   if (await project.hasOrWantsLayer("typescript")) return;
 
   /**
-   * We don't actually remove anything, because we want intellisense for JS
+   * Intellisense for JS needs some of these,
+   * but minimal means minimal.
    *
-   * But perhaps for the sake of minimal, we do remoev it.
-   * And we add a layer later for JSDoc ased TS or something
+   * A later layer for JSDoc-based TS can add them back.
    */
   await packageJson.removeDevDependencies(
     [
@@ -110,9 +114,10 @@ async function makeJavaScript(project) {
   }, project.directory);
 
   /**
-   * The import-rewriting pass only handles module files; the popup's
-   * <script src> points at the boot module by path, so it has to follow
-   * the .ts -> .js rename by hand.
+   * The import-rewriting pass only handles module files.
+   *
+   * The popup's <script src> points at the boot module by path,
+   * so it has to follow the .ts -> .js rename by hand.
    */
   if (!project.hasFile("index.html")) return;
 

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

@@ -24,16 +24,17 @@ 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).
+- `src/` is your library source.
+  Author components in `.gts`/`.gjs` (template-tag) and plain modules in `.ts`/`.js`.
+- `src/index.ts` is 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/` is 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<...>`.
+so every exported value needs an explicit type annotation.
+In particular, annotate exported template-only components with `TOC<...>`.
 
 ## Publishing
 

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

@@ -11,9 +11,9 @@ import { removeConfiguredPlugin } from "#utils/babel.js";
  * 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
+ * - an empty src/ with an index entry
+ * - No babel.config.js
+ *   (ember() covers TS stripping, template compilation, and decorators)
  * - No testing framework
  * - No linting or formatting
  *
@@ -65,8 +65,10 @@ async function updateName(project) {
 }
 
 /**
- * The template's package.json is `private: true` so it can never be
- * published from this repo; the generated library exists to be published,
+ * 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
@@ -78,9 +80,11 @@ async function makePublishable(project) {
 }
 
 /**
- * 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).
+ * When the project is JavaScript (no typescript layer):
+ * - remove the TS toolchain
+ * - drop the tsconfig
+ * - point the build at the emitted `.js` entry
+ *   (declarations can't be produced without types)
  *
  * @param {import('#utils/project.js').Project} project
  */
@@ -99,8 +103,8 @@ async function makeJavaScript(project) {
 }
 
 /**
- * No declarations are emitted for a JavaScript library, so the `types`
- * export conditions would point at files that never exist.
+ * 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
  */
@@ -115,8 +119,9 @@ async function removeTypesExports(project) {
 }
 
 /**
- * Rewrites the tsdown config so it builds the JavaScript entry and stops
- * emitting declarations (defineConfig defaults to `dts: true`).
+ * Rewrites the tsdown config so it:
+ * - builds the JavaScript entry
+ * - stops emitting declarations (defineConfig defaults to `dts: true`)
  *
  * @param {import('#utils/project.js').Project} project
  */
@@ -152,9 +157,10 @@ async function upgradeDependencies(project) {
 }
 
 /**
- * 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.
+ * The base doesn't emit a babel.config.js,
+ * but this can run over an existing project that has one.
+ *
+ * A JavaScript project's babel config must not reference the TS plugin.
  *
  * @param {import('#utils/project.js').Project} project
  */