Both Getting Started guides fail on macOS (Quickstart + README)

[XueyanZhang]

Both Getting Started guides fail on macOS (Quickstart + README)

Summary

Neither of the two official getting started paths work out of the box on macOS. As a new user trying A2UI for the first time, I was unable to get the demo running following either guide. This is likely a significant barrier for newcomers evaluating the project.

Environment

• OS: macOS (MacBook)
• Node.js: v18+
• Python: 3.13 (via conda env py313)
• uv: installed
• GEMINI_API_KEY: set

---

Issue 1: Quickstart guide — confusing directory navigation

Docs page: https://a2ui.org/quickstart/#step-4-install-and-run

Problem

The quickstart instructs users to navigate to samples/client/lit and run npm run demo:all. However, the repo also contains a renderers/lit directory, and it's easy to end up there instead — especially when browsing the repo structure or following the README's separate instructions which reference the renderers/ path.

Running npm run demo:all from renderers/lit produces:

npm error Missing script: "demo:all"

---

Issue 2: README Getting Started — multi-step manual build fails

Docs page: https://github.com/google/a2ui#getting-started

Problem

The README provides an alternative getting started flow that involves manually building multiple packages in sequence:

# Install and build the Markdown renderer
cd renderers/markdown/markdown-it
npm install
npm run build

# Install and build the Web Core library
cd ../../web_core
npm install
npm run build

# Install and build the Lit renderer
cd ../lit
npm install
npm run build

# Install and run the shell client
cd ../../samples/client/lit/shell
npm install
npm run dev

This multi-step process fails on macOS. The number of sequential cd + npm install + npm run build steps makes it fragile — if any single step fails or produces an unexpected output, the entire chain breaks, and it's difficult for new users to diagnose which step went wrong.

[Varun-S10]

Hi @XueyanZhang, We truly appreciate you taking the time to report this. We have reproduced the issue on our end and will be escalating it to our team. Thank you for your patience and understanding.

[Varun-S10]

Here is what I tried and where the errors occur:
For the Backend Agent: I navigated into cd samples/agent/adk/restaurant_finder and ran uv run ., but it immediately crashed and gave me this error:

ERROR:__main__:An error occurred during server startup: Failed to validate example examples/confirmation.json: Component 'confirmation-card' references non-existent component 'confirmation-column' in field 'child'

For the Frontend Client: I went into cd renderers/markdown/markdown-it and ran npm install followed by npm run build, but the build failed with this message:

npm warn Unknown project config "always-auth" (//us-npm.pkg.dev/oss-exit-gate-prod/a2ui--npm/:always-auth). This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.

> @a2ui/markdown-it@0.0.2 build
> wireit

src/markdown.ts:19:24 - error TS2307: Cannot find module '@a2ui/web_core' or its corresponding type declarations.

19 import * as Types from '@a2ui/web_core';
                          ~~~~~~~~~~~~~~~~

src/raw-markdown.ts:18:24 - error TS2307: Cannot find module '@a2ui/web_core' or its corresponding type declarations.

18 import * as Types from '@a2ui/web_core';
                          ~~~~~~~~~~~~~~~~


Found 2 errors.


❌ [build] exited with exit code 1.
❌ 1 script failed.

[Dihubopen]

以下是我尝试的操作以及出现错误的地方： **对于后端代理：**我导航到cd samples/agent/adk/restaurant_finder并运行了命令uv run .，但它立即崩溃并出现以下错误：

ERROR:__main__:An error occurred during server startup: Failed to validate example examples/confirmation.json: Component 'confirmation-card' references non-existent component 'confirmation-column' in field 'child'

**对于前端客户端：**我进入cd renderers/markdown/markdown-it并运行了npm install，npm run build但构建失败并显示以下消息：

npm warn Unknown project config "always-auth" (//us-npm.pkg.dev/oss-exit-gate-prod/a2ui--npm/:always-auth). This will stop working in the next major version of npm. See `npm help npmrc` for supported config options.

> @a2ui/markdown-it@0.0.2 build
> wireit

src/markdown.ts:19:24 - error TS2307: Cannot find module '@a2ui/web_core' or its corresponding type declarations.

19 import * as Types from '@a2ui/web_core';
                          ~~~~~~~~~~~~~~~~

src/raw-markdown.ts:18:24 - error TS2307: Cannot find module '@a2ui/web_core' or its corresponding type declarations.

18 import * as Types from '@a2ui/web_core';
                          ~~~~~~~~~~~~~~~~


Found 2 errors.


❌ [build] exited with exit code 1.
❌ 1 script failed.

You see : #951