Add Node.js sample using a native WinUI 3 Application and Window

[leileizhang (lei9444)]

Description

Usage Example

Related Issue

Type of Change

• 🐛 Bug fix
• ✨ New feature
• 💥 Breaking change
• 📝 Documentation
• 🔧 Config/build
• ♻️ Refactoring
• 🧪 Test update

Checklist

• New tests added for new functionality (if applicable)
• Tested locally on Windows
• Main README.md updated (if applicable)
• docs/usage.md updated (if CLI commands changed)
• Language-specific guides updated (if applicable)
• Sample projects updated to reflect changes (if applicable)
• Agent skill templates updated in docs/fragments/skills/ (if CLI commands/workflows changed)

Screenshots / Demo

Additional Notes

AI Description

This pull request introduces a new sample demonstrating how to create a WinUI 3 application and window directly from Node.js, using the Microsoft.UI.Xaml controls projected into JavaScript. It includes necessary files like main.js, package.json, and a README for usage instructions. To run the sample, use the following commands:

npm install
npm run restore
npm start

[github-actions]

⏳ Build in progress — metrics below are from a previous commit and will update when the current build finishes.

Build Metrics Report

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	36.77 MB	36.77 MB	✅ 0.0 KB (0.00%)
CLI (x64)	36.95 MB	36.95 MB	✅ 0.0 KB (0.00%)
MSIX (ARM64)	15.36 MB	15.36 MB	📈 +0.1 KB (+0.00%)
MSIX (x64)	16.30 MB	16.30 MB	📉 -0.0 KB (-0.00%)
NPM Package	32.06 MB	32.06 MB	📈 +0.3 KB (+0.00%)
NuGet Package	32.09 MB	32.09 MB	📈 +0.0 KB (+0.00%)

Test Results

✅ 3338 passed, 4 skipped out of 3342 tests in 872.9s (+135.3s vs. baseline)

Test Coverage

✅ 86.3% line coverage, 80% branch coverage · ✅ no change vs. baseline

CLI Startup Time

52ms median (x64, winapp --version) · ✅ no change vs. baseline

---

Updated 2026-07-16 13:46:21 UTC · commit 35c3701 · workflow run

[Copilot]

Pull request overview

Adds a new Node.js sample that demonstrates creating a native WinUI 3 Application + Window directly from JavaScript using dynwinrt, along with CI coverage to keep the sample working over time.

Changes:

• Adds the samples/node-winui sample project (restore/generate scripts, WinUI worker implementation, and documentation).
• Adds a Pester test for the new sample and wires it into the test-samples.yml matrix.
• Updates the repo root README.md to include the new sample in the Samples table.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
samples/node-winui/winui-worker.js	Worker-thread WinUI Application.start() sample UI composition + event wiring.
samples/node-winui/main.js	Bootstraps Windows App SDK and starts the WinUI worker.
samples/node-winui/package.json	Declares sample scripts, #winapp/bindings imports, dynwinrt deps, and winapp.jsBindings config.
samples/node-winui/README.md	Sample usage + architecture explanation + binding regeneration guidance.
samples/node-winui/winapp.yaml	WinApp restore package set for generating WinUI bindings.
samples/node-winui/test.Tests.ps1	Pester validation for restore + generated bindings + basic JS syntax checks.
samples/node-winui/.gitignore	Ignores .winapp/ output and node_modules/.
samples/node-winui/.npmrc	Sets npm registry (see review comment).
README.md	Fixes formatting in install section and adds the new sample to the Samples table.
.github/workflows/test-samples.yml	Adds node-winui to workflow_dispatch options, matrix, and Node setup gating.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Nikola Metulev (nmetulev)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (2)

README.md:255

• This adds a new framework sample to the public sample index, but there is no corresponding Node/WinUI guide under docs/guides/. Other framework samples have an end-to-end guide surface, and the repository contribution guidance requires language-specific guides to stay synchronized. Add a Node WinUI guide (and link it from the relevant guide index) so this workflow is discoverable outside the sample table.

| [Node.js WinUI 3](/samples/node-winui/README.md) | Native WinUI 3 controls created directly from JavaScript |

samples/node-winui/test.Tests.ps1:100

• Phase 2 only parses the JavaScript and matches source strings; it never executes the restored sample. Consequently, failures in Windows App SDK bootstrap, Application.create(), resource loading, window activation, or event wiring would all pass CI. Add a smoke test that launches node main.js from $script:appDir, waits for the ready message/window, exercises one callback, closes it, and asserts a clean exit.

        It "Should contain valid JavaScript" -Skip:$script:skip {
            & node --check (Join-Path $script:sampleDir 'main.js')
            $LASTEXITCODE | Should -Be 0
            & node --check (Join-Path $script:sampleDir 'winui-worker.js')
            $LASTEXITCODE | Should -Be 0

[Copilot]

Copilot resolve the merge conflicts in this pull request

Merge conflicts resolved in 321e001. The only conflicted file was .github/workflows/test-samples.yml — I took the union of both sample lists (node-winui plus main's winui-app/winui-solution/winui-unpackaged-app) in the matrix and the setup-node condition, keeping main's pinned actions/setup-node SHA.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated no new comments.

Suppressed comments (3)

README.md:259

• The new sample is listed here, but no corresponding page was added under docs/guides/ or the top-level Guides section. The repository’s new-sample shipping checklist requires that guide surface; add a Node WinUI guide (the sample README content can be reused) and link it from the Guides section.

| [Node.js WinUI 3](/samples/node-winui/README.md) | Native WinUI 3 controls created directly from JavaScript |

samples/node-winui/winui-worker.js:141

• This ComboBox has no accessible name because its header is a TextBlock; UI Automation reports only an unnamed ComboBox, so screen-reader users cannot identify the theme selector. Using a string-valued header gives it the accessible name “Theme” (verified with winapp ui inspect).

        themePicker.header = createText('Theme', 13, 600);

samples/node-winui/main.js:29

• The sample test only checks syntax and source patterns; it never executes this bootstrap/worker path. CI would therefore pass even if npm start crashes before creating a window. Add a smoke test that launches the restored copy, waits for the ready message/window, closes it, and asserts a zero exit code.

const { initWinappsdk } = require('@microsoft/dynwinrt');
initWinappsdk(2, 2);

const worker = new Worker(path.join(__dirname, 'winui-worker.js'));