build-start-rebuild-perf 0.0.0 → 0.1.0

package/.github/workflows/plan-release.yml

@@ -0,0 +1,94 @@
+name: Plan Release
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+  pull_request_target: # This workflow has permissions on the repo, do NOT run code from PRs in this workflow. See https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
+    types:
+      - labeled
+      - unlabeled
+
+concurrency:
+  group: plan-release # only the latest one of these should ever be running
+  cancel-in-progress: true
+
+jobs:
+  is-this-a-release:
+    name: "Is this a release?"
+    runs-on: ubuntu-latest
+    outputs:
+      command: ${{ steps.check-release.outputs.command }}
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+          ref: 'main'
+      # This will only cause the `is-this-a-release` job to have a "command" of `release`
+      # when the .release-plan.json file was changed on the last commit.
+      - id: check-release
+        run: if git diff --name-only HEAD HEAD~1 | grep -w -q ".release-plan.json"; then echo "command=release"; fi >> $GITHUB_OUTPUT
+
+  create-prepare-release-pr:
+    name: Create Prepare Release PR
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    needs: is-this-a-release
+    permissions:
+      contents: write
+      issues: read
+      pull-requests: write
+    # only run on push event or workflow dispatch if plan wasn't updated (don't create a release plan when we're releasing)
+    # only run on labeled event if the PR has already been merged
+    if: ((github.event_name == 'push' || github.event_name == 'workflow_dispatch') && needs.is-this-a-release.outputs.command != 'release') || (github.event_name == 'pull_request_target' && github.event.pull_request.merged == true)
+
+    steps:
+      - uses: actions/checkout@v4
+        # We need to download lots of history so that
+        # github-changelog can discover what's changed since the last release
+        with:
+          fetch-depth: 0
+          ref: 'main'
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: "Generate Explanation and Prep Changelogs"
+        id: explanation
+        run: |
+          set +e
+          pnpm release-plan prepare 2> >(tee -a release-plan-stderr.txt >&2)
+
+          if [ $? -ne 0 ]; then
+            release_plan_output=$(cat release-plan-stderr.txt)
+          else
+            release_plan_output=$(jq .description .release-plan.json -r)
+            rm release-plan-stderr.txt
+
+            if [ $(jq '.solution | length' .release-plan.json) -eq 1 ]; then
+              new_version=$(jq -r '.solution[].newVersion' .release-plan.json)
+              echo "new_version=v$new_version" >> $GITHUB_OUTPUT
+            fi
+          fi
+            echo 'text<<EOF' >> $GITHUB_OUTPUT
+          echo "$release_plan_output" >> $GITHUB_OUTPUT
+            echo 'EOF' >> $GITHUB_OUTPUT
+        env:
+          GITHUB_AUTH: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: peter-evans/create-pull-request@v7
+        with:
+          commit-message: "Prepare Release ${{ steps.explanation.outputs.new_version}} using 'release-plan'"
+          labels: "internal"
+          branch: release-preview
+          title: Prepare Release ${{ steps.explanation.outputs.new_version }}
+          body: |
+            This PR is a preview of the release that [release-plan](https://github.com/embroider-build/release-plan) has prepared. To release you should just merge this PR 👍
+
+            -----------------------------------------
+
+            ${{ steps.explanation.outputs.text }}

package/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+# For every push to the primary branch with .release-plan.json modified,
+# runs release-plan.
+
+name: Publish Stable
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - '.release-plan.json'
+
+concurrency:
+  group: publish-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  publish:
+    name: "NPM Publish"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+      attestations: write
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          # This creates an .npmrc that reads the NODE_AUTH_TOKEN environment variable
+          registry-url: 'https://registry.npmjs.org'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Publish to NPM
+        run: NPM_CONFIG_PROVENANCE=true pnpm release-plan publish
+        env:
+          GITHUB_AUTH: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request: {}
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          cache: pnpm
+      - run: pnpm i --frozen-lockfile
+      - run: pnpm run lint
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: [lint]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          cache: pnpm
+      - run: pnpm i --frozen-lockfile
+      - run: pnpm run test

package/.release-plan.json

@@ -0,0 +1,18 @@
+{
+  "solution": {
+    "build-start-rebuild-perf": {
+      "impact": "minor",
+      "oldVersion": "0.0.1",
+      "newVersion": "0.1.0",
+      "tagName": "latest",
+      "constraints": [
+        {
+          "impact": "minor",
+          "reason": "Appears in changelog section :rocket: Enhancement"
+        }
+      ],
+      "pkgJSONPath": "./package.json"
+    }
+  },
+  "description": "## Release (2025-08-08)\n\n* build-start-rebuild-perf 0.1.0 (minor)\n\n#### :rocket: Enhancement\n* `build-start-rebuild-perf`\n  * [#21](https://github.com/mainmatter/build-start-rebuild-perf/pull/21) Show stack on error. ([@NullVoxPopuli](https://github.com/NullVoxPopuli))\n\n#### Committers: 1\n- [@NullVoxPopuli](https://github.com/NullVoxPopuli)\n"
+}

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## Release (2025-08-08)
+
+* build-start-rebuild-perf 0.1.0 (minor)
+
+#### :rocket: Enhancement
+* `build-start-rebuild-perf`
+  * [#21](https://github.com/mainmatter/build-start-rebuild-perf/pull/21) Show stack on error. ([@NullVoxPopuli](https://github.com/NullVoxPopuli))
+
+#### Committers: 1
+- [@NullVoxPopuli](https://github.com/NullVoxPopuli)
+
+## Release (2025-08-07)
+
+* build-start-rebuild-perf 0.0.1 (patch)
+
+#### :bug: Bug Fix
+* `build-start-rebuild-perf`
+  * [#12](https://github.com/mainmatter/build-start-rebuild-perf/pull/12) fix pnpm workspace ([@mansona](https://github.com/mansona))
+
+#### :memo: Documentation
+* `build-start-rebuild-perf`
+  * [#8](https://github.com/mainmatter/build-start-rebuild-perf/pull/8) Improve README ([@pichfl](https://github.com/pichfl))
+
+#### :house: Internal
+* `build-start-rebuild-perf`
+  * [#7](https://github.com/mainmatter/build-start-rebuild-perf/pull/7) Run tests in CI ([@pichfl](https://github.com/pichfl))
+  * [#6](https://github.com/mainmatter/build-start-rebuild-perf/pull/6) reset version in package.json ([@mansona](https://github.com/mansona))
+  * [#4](https://github.com/mainmatter/build-start-rebuild-perf/pull/4) start using release-plan ([@mansona](https://github.com/mansona))
+
+#### Committers: 2
+- Chris Manson ([@mansona](https://github.com/mansona))
+- Florian Pichler ([@pichfl](https://github.com/pichfl))

package/README.md

@@ -1,2 +1,61 @@
 # build-start-rebuild-perf
-Measure your build, app start up, and rebuild times in one go
+
+Measures web app performance metrics:
+- Dev server startup time
+- Time to first paint
+- Time to app load (waiting for an element selector)
+- Reload time after a file changes
+
+## Usage
+
+```sh
+pnpm dlx build-start-rebuild-perf [options]
+```
+
+### Example
+
+```sh
+# assuming running in an Ember project with a <img class="logo" /> in the app layout
+pnpm dlx build-start-rebuild-perf --file "app/router.js" --wait-for ".logo"
+```
+
+## Options
+
+```
+	-u, --url <url>            URL to load (default: "http://localhost:4200")
+	-f, --file <path>          File to touch to trigger a reload (no default, but app/router.js is an option)
+	-c, --command <cmd>        Command to start dev server (default: "pnpm start")
+	-w, --wait-for <selector>  Element selector to wait for (default: "body")
+	-l, --log-level <level>    Set the log level (choices: "log", "warn", "error")
+	-h, --help                 display help for command
+```
+
+## Example Output
+
+```md
+# Performance Results
+
+| Dev Server Ready | First Paint | App Loaded | Reload after change |
+| ---------------- | ----------- | ---------- | ------------------- |
+| 5,523 ms         | 5,618 ms    | 6,142 ms   | 918 ms              |
+```
+
+## Share with us
+
+Assuming you're in an Ember project and wondering if moving to Vite from the old Ember CLI is worth it, here's how you can use the script to create useful numbers:
+
+1. Start on your `main` branch or anywhwere you're still using Ember CLI with Webpack and Embroider
+2. Clear all caches (browser, build, etc) and remove your `node_modules`
+3. Run `pnpm install` to reinstall dependencies
+4. Run `build-start-rebuild-perf` once to get numbers for a cold start
+5. Run `build-start-rebuild-perf` again to measure a warm start
+6. Move to your `vite` branch where you enabled the new Vite based Embroider
+7. Repeat steps 2-5.
+
+Share a your results with the Ember Initiative via [email](https://mainmatter.com/contact/), or [Mastodon](https://fosstodon.org/@mainmatter), or [Bluesky](https://bsky.app/profile/mainmatter.com).
+
+---
+
+## License
+
+This project is part of the [Ember Initative](https://mainmatter.com/ember-initiative/). It is developed by and &copy; [Mainmatter GmbH](http://mainmatter.com) and contributors. It is released under the [MIT License](./LICENSE).

package/RELEASE.md

@@ -0,0 +1,27 @@
+# Release Process
+
+Releases in this repo are mostly automated using [release-plan](https://github.com/embroider-build/release-plan/). Once you label all your PRs correctly (see below) you will have an automatically generated PR that updates your CHANGELOG.md file and a `.release-plan.json` that is used to prepare the release once the PR is merged.
+
+## Preparation
+
+Since the majority of the actual release process is automated, the remaining tasks before releasing are:
+
+- correctly labeling **all** pull requests that have been merged since the last release
+- updating pull request titles so they make sense to our users
+
+Some great information on why this is important can be found at [keepachangelog.com](https://keepachangelog.com/en/1.1.0/), but the overall
+guiding principle here is that changelogs are for humans, not machines.
+
+When reviewing merged PR's the labels to be used are:
+
+- breaking - Used when the PR is considered a breaking change.
+- enhancement - Used when the PR adds a new feature or enhancement.
+- bug - Used when the PR fixes a bug included in a previous release.
+- documentation - Used when the PR adds or updates documentation.
+- internal - Internal changes or things that don't fit in any other category.
+
+**Note:** `release-plan` requires that **all** PRs are labeled. If a PR doesn't fit in a category it's fine to label it as `internal`
+
+## Release
+
+Once the prep work is completed, the actual release is straight forward: you just need to merge the open [Plan Release](https://github.com/mainmatter/build-start-rebuild-perf/pulls?q=is%3Apr+is%3Aopen+%22Prepare+Release%22+in%3Atitle) PR

package/bin/cli.js

@@ -0,0 +1,41 @@
+import { cleanupBrowser } from "../lib/browser.js";
+import { setLogLevel } from "../lib/log.js";
+import { formatResults, measure } from "../lib/measure.js";
+import program from "../lib/program.js";
+import { terminateServer } from "../lib/server.js";
+
+// Parse arguments and run measurement
+program.parse();
+const options = program.opts();
+// get defaults like this: const DEFAULTS = program.options.map((option) => option.defaultValue);
+
+setLogLevel(options.level);
+
+["SIGINT", "SIGTERM", "SIGQUIT"].forEach((signal) => {
+  process.on(signal, async () => {
+    console.log(`\nReceived ${signal}, cleaning up...`);
+    await terminateServer();
+    await cleanupBrowser();
+    process.exit(0);
+  });
+});
+
+try {
+  let results = await measure(options);
+
+  console.log(
+    `
+Measurement completed successfully!
+
+# Performance Results
+
+${formatResults(results)}
+
+`,
+  );
+  process.exit(0);
+} catch (err) {
+  console.error("Measurement failed");
+  console.error(err);
+  process.exit(1);
+}

package/biome.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.1.3/schema.json",
+  "files": {
+    "includes": ["bin/**", "lib/**", "src/**", "test/**", "*.js", "*.mjs", "*.json"],
+    "ignoreUnknown": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "style": {
+        "useConst": "off"
+      }
+    }
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 100
+  },
+  "javascript": {
+    "formatter": {
+      "semicolons": "always",
+      "quoteStyle": "double"
+    }
+  }
+}

package/lib/browser.js

@@ -0,0 +1,133 @@
+import { promises as fs } from "node:fs";
+import { resolve } from "node:path";
+import { Launcher } from "chrome-launcher";
+import puppeteer from "puppeteer-core";
+import { error, log, warn } from "./log.js";
+
+export const VIEWPORT = {
+  width: 1366,
+  height: 768,
+};
+
+let browser = null;
+let page = null;
+
+export async function initBrowser() {
+  browser = await puppeteer.launch({
+    executablePath: Launcher.getInstallations()[0],
+    headless: process.env.SHOW_BROWSER !== "true",
+    args: ["--no-sandbox"],
+  });
+
+  page = await browser.newPage();
+
+  // Setup page event listeners
+  page.on("console", (msg) => {
+    if (["error", "warning"].includes(msg.type())) {
+      warn(`PAGE ${msg.type().toUpperCase()}: ${msg.text()}`);
+    }
+  });
+
+  page.on("pageerror", (err) => {
+    error(`PAGE ERROR: ${err.message}`);
+  });
+
+  page.on("response", (resp) => {
+    if (!resp.ok() && resp.status() !== 302 && resp.status() !== 304) {
+      warn(`FAILED HTTP REQUEST TO ${resp.url()} Status: ${resp.status()}`);
+    }
+  });
+
+  await page.setViewport(VIEWPORT);
+
+  // Setup authentication if credentials are provided
+  if (process.env.AUTH_USER && process.env.AUTH_PASSWORD) {
+    await page.authenticate({
+      username: process.env.AUTH_USER,
+      password: process.env.AUTH_PASSWORD,
+    });
+  }
+}
+
+export async function measurePageLoad(url, waitForSelector = "body") {
+  log(`Loading page: ${url}`);
+
+  const response = await page.goto(url, {
+    timeout: 60_000,
+    waitUntil: "load",
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to load page: ${response.status()}`);
+  }
+
+  const atFirstPaint = performance.now();
+
+  log("Waiting for page to fully load...");
+  await page.waitForNetworkIdle();
+
+  log(`Waiting for element: ${waitForSelector}`);
+  await page.waitForSelector(waitForSelector, {
+    visible: true,
+    timeout: 60_000,
+  });
+
+  const atAppLoad = performance.now();
+
+  log(`Page loaded`);
+
+  return {
+    atFirstPaint,
+    atAppLoad,
+  };
+}
+
+export async function measureFileReload(filePath) {
+  if (!filePath) {
+    log("No file specified for reload test, skipping...");
+    return 0;
+  }
+
+  const resolvedPath = resolve(filePath);
+
+  try {
+    await fs.access(resolvedPath);
+  } catch {
+    warn(`File ${filePath} not found, skipping reload test...`);
+    return {};
+  }
+
+  log(`Testing reload with file: ${filePath}`);
+
+  log("Triggering file change...");
+  const atFileChange = performance.now();
+
+  const originalContent = await fs.readFile(resolvedPath, "utf8");
+  await fs.writeFile(resolvedPath, `${originalContent}\n// reload trigger`);
+
+  const atFileChanged = performance.now();
+
+  log("Waiting for hot reload to complete...");
+  await page.waitForNetworkIdle();
+
+  const atReloadComplete = performance.now();
+
+  log("Restoring original file content...");
+  await fs.writeFile(resolvedPath, originalContent);
+
+  return {
+    atFileChange,
+    atFileChanged,
+    atReloadComplete,
+  };
+}
+
+export async function cleanupBrowser() {
+  if (browser) {
+    try {
+      await browser.close();
+    } catch (err) {
+      error("Error closing browser:", err.message);
+    }
+  }
+}

package/lib/log.js

@@ -0,0 +1,24 @@
+let logLevel = "warn";
+
+/**
+ * @param level {'log' | 'warn'  | 'error'}
+ */
+export function setLogLevel(level) {
+  logLevel = level;
+}
+
+export function log(message) {
+  if (logLevel === "log") {
+    console.log(message);
+  }
+}
+
+export function warn(message) {
+  if (logLevel === "log" || logLevel === "warn") {
+    console.warn(message);
+  }
+}
+
+export function error(message) {
+  console.error(message);
+}

package/lib/measure.js

@@ -0,0 +1,78 @@
+import { markdownTable } from "markdown-table";
+import { cleanupBrowser, initBrowser, measureFileReload, measurePageLoad } from "./browser.js";
+import { error, log } from "./log.js";
+import { startServer, terminateServer } from "./server.js";
+import { formatMs } from "./utils.js";
+
+/**
+ * @typedef {Object} MeasureResults
+ * @property {number} atStart
+ * @property {number} atServerUp
+ * @property {number} atFirstPaint
+ * @property {number} atAppLoad
+ * @property {number} [atFileChange]
+ * @property {number} [atFileChanged]
+ * @property {number} [atReloadComplete]
+ */
+
+/**
+ *
+ * @param {*} options
+ * @returns {Promise<MeasureResults>}
+ */
+export async function measure(options) {
+  try {
+    await initBrowser();
+    log("Starting performance measurement...\n");
+
+    const atStart = performance.now();
+    const serverURL = await startServer(options);
+    const atServerUp = performance.now();
+    const pageLoadMetrics = await measurePageLoad(serverURL, options.waitFor);
+    const reloadMetrics = await measureFileReload(options.file);
+    await terminateServer();
+
+    return {
+      atStart,
+      atServerUp,
+      ...pageLoadMetrics,
+      ...reloadMetrics,
+    };
+  } catch (err) {
+    error("Performance measurement failed:", err.message);
+    throw err;
+  } finally {
+    await terminateServer();
+    await cleanupBrowser();
+  }
+}
+
+/**
+ *
+ * @param {MeasureResults} results
+ * @returns string
+ */
+export function formatResults({
+  atStart,
+  atServerUp,
+  atFirstPaint,
+  atAppLoad,
+  atFileChanged,
+  atReloadComplete,
+}) {
+  const reloaded = atReloadComplete !== undefined;
+
+  const tableData = [
+    ["Dev Server Ready", "First Paint", "App Loaded", reloaded && "Reload after change"].filter(
+      Boolean,
+    ),
+    [
+      formatMs(atServerUp - atStart),
+      formatMs(atFirstPaint - atStart),
+      formatMs(atAppLoad - atStart),
+      reloaded && formatMs(atReloadComplete - atFileChanged),
+    ].filter(Boolean),
+  ];
+
+  return markdownTable(tableData);
+}

package/lib/program.js

@@ -0,0 +1,34 @@
+import { Command, Option } from "commander";
+
+const program = new Command();
+
+program
+  .name("build-start-perf-test")
+  .description("Measures build and load performance for web applications")
+  .option("-u, --url <url>", "URL to load", "http://localhost:4200")
+  .option("-f, --file <path>", "File to touch to trigger a reload")
+  .option("-c, --command <cmd>", "Command to start dev server", "pnpm start")
+  .option("-w, --wait-for <selector>", "Element selector to wait for", "body")
+  .addOption(
+    new Option("-l, --log-level <level>", "Set the log level", "warn").choices([
+      "log",
+      "warn",
+      "error",
+    ]),
+  )
+  .addHelpText(
+    "after",
+    `
+Measures:
+- Build time
+- Time to first paint
+- Time to app load (waiting for specified element)
+- Time to finished reload after file changes
+
+Examples:
+  $ build-start-perf-test --url http://localhost:3000 --command "npm run dev"
+  $ build-start-perf-test --file app.js --wait-for ".app-container"
+`,
+  );
+
+export default program;