Skip to content

fix(deps): ship a zero-warning, minimal install #1784

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kevincodex1 merged 5 commits into from
Jul 7, 2026
Merged

fix(deps): ship a zero-warning, minimal install #1784

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a71a73f
fix(deps): ship a zero-warning, minimal install
kevincodex1 Jun 25, 2026
a8fa64c
fix(deps): address optional runtime review findings
jatmn Jul 7, 2026
19ebc64
test(deps): isolate optional runtime importer mocks
jatmn Jul 7, 2026
dc0c61d
fix(deps): clarify AWS optional auth labels
jatmn Jul 7, 2026
ca21b79
fix(deps): close optional runtime review gaps
jatmn Jul 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
252 changes: 111 additions & 141 deletions bun.lock
View file
Open in desktop

Large diffs are not rendered by default.

32 changes: 31 additions & 1 deletion docs/advanced-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,10 +98,22 @@ third-party gateways.

Authentication uses Google Application Default Credentials through
`google-auth-library`. There is no `OPENAI_API_KEY`-style API key for this
route. Authenticate with either a service-account file or local ADC:
route. **For global npm installs, install the auth package on demand** (it is
not bundled by default — see [Optional provider packages](#optional-provider-packages)):

```bash
npm i -g google-auth-library
```

Authenticate with either local Application Default Credentials (ADC) or a
service-account key file:

```bash
# Option 1 — local ADC (interactive, uses your own Google account):
gcloud auth application-default login

# Option 2 — service-account key file (headless / CI):
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

Minimal setup:
Expand Down Expand Up @@ -319,6 +331,24 @@ export OPENAI_MODEL=accounts/fireworks/models/llama-v3p1-70b-instruct

The **OpenClaude VS Code extension** can store the key in Secret Storage and set these variables for you when you launch from the Control Center. See `vscode-extension/openclaude-vscode/README.md`.

## Optional provider packages

To keep the default `npm i -g @gitlawb/openclaude` install small and
warning-free, a few provider SDKs and the native image library are **not
bundled**. They are loaded on demand, and the CLI prints an `npm install <pkg>`
hint (add `-g` for the global CLI) if you enable a feature whose package is
missing. Install only what you need:

| Feature | Trigger | Install |
| --- | --- | --- |
| AWS Bedrock | `CLAUDE_CODE_USE_BEDROCK=1` | `npm i -g @anthropic-ai/bedrock-sdk`. Profile-based auth (`~/.aws/credentials`) additionally needs `@aws-sdk/credential-providers` and `@aws-sdk/client-sts`; model listing needs `@aws-sdk/client-bedrock`. Proxy and skip-auth setups may also need `@aws-sdk/credential-provider-node`, `@smithy/node-http-handler`, or `@smithy/core`. The CLI prints the exact missing package if you hit one. |
| Azure Foundry | `CLAUDE_CODE_USE_FOUNDRY=1` | `npm i -g @anthropic-ai/foundry-sdk @azure/identity` |
| Claude on Vertex AI / Gemini ADC | `CLAUDE_CODE_USE_VERTEX=1` / Gemini ADC auth | `npm i -g google-auth-library` |
| Reading/processing images | reading an image file | `npm i -g sharp` |
Comment thread
coderabbitai[bot] marked this conversation as resolved.

When installing OpenClaude from source (`bun install`), all of these are
already present as dev dependencies, so source/dev builds need no extra steps.

## Environment Variables

| Variable | Required | Description |
Expand Down
3 changes: 2 additions & 1 deletion knip.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@
],
"ignoreDependencies": [
"@types/bun",
"@anthropic-ai/foundry-sdk"
"@anthropic-ai/foundry-sdk",
"google-auth-library"
]
}
36 changes: 27 additions & 9 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,18 +75,29 @@
"prepack": "npm run build"
},
"dependencies": {
"@orama/orama": "^3.1.18",
"@orama/plugin-data-persistence": "^3.1.18",
"@vscode/ripgrep": "^1.17.1"
},
"devDependencies": {
"@alcalzone/ansi-tokenize": "0.3.0",
"@anthropic-ai/bedrock-sdk": "0.29.1",
"@anthropic-ai/foundry-sdk": "0.2.3",
"@anthropic-ai/sandbox-runtime": "0.0.55",
"@anthropic-ai/sdk": "0.94.0",
"@aws-sdk/client-bedrock": "3.1047.0",
"@aws-sdk/client-sts": "3.1047.0",
"@aws-sdk/credential-provider-node": "3.972.41",
"@azure/identity": "^4.13.1",
"@commander-js/extra-typings": "12.1.0",
"@grpc/grpc-js": "^1.14.3",
"@grpc/proto-loader": "^0.8.0",
"@modelcontextprotocol/sdk": "1.29.0",
"@orama/orama": "^3.1.18",
"@orama/plugin-data-persistence": "^3.1.18",
"@vscode/ripgrep": "^1.17.1",
"@smithy/core": "3.24.3",
"@smithy/node-http-handler": "4.7.3",
"@types/bun": "1.3.11",
"@types/node": "25.5.0",
"@types/react": "19.2.14",
"ajv": "8.18.0",
"auto-bind": "5.0.1",
"axios": "1.16.0",
Expand All @@ -111,6 +122,7 @@
"ignore": "7.0.5",
"indent-string": "5.0.0",
"jsonc-parser": "3.3.1",
"knip": "^6.16.1",
"lodash-es": "4.18.1",
"lru-cache": "11.2.7",
"marked": "15.0.12",
Expand All @@ -129,6 +141,7 @@
"tree-kill": "1.2.2",
"turndown": "7.2.2",
"type-fest": "4.41.0",
"typescript": "5.9.3",
"undici": "7.28.0",
"usehooks-ts": "3.1.1",
"vscode-languageserver-protocol": "3.17.5",
Expand All @@ -138,12 +151,17 @@
"yaml": "2.8.3",
"zod": "3.25.76"
},
"devDependencies": {
"@types/bun": "1.3.11",
"@types/node": "25.5.0",
"@types/react": "19.2.14",
"knip": "^6.16.1",
"typescript": "5.9.3"
"peerDependencies": {
"@anthropic-ai/sdk": "^0.94.0",
"@modelcontextprotocol/sdk": "^1.29.0",
"react": "^19.0.0",
"react-reconciler": "^0.33.0"
},
"peerDependenciesMeta": {
"@anthropic-ai/sdk": { "optional": true },
"@modelcontextprotocol/sdk": { "optional": true },
"react": { "optional": true },
"react-reconciler": { "optional": true }
},
"engines": {
"node": ">=22.0.0"
Expand Down
78 changes: 70 additions & 8 deletions scripts/externals.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,23 @@
* added here (large packages, native modules, or packages with many exports).
*/

// Packages that should be kept external in ALL bundles (CLI + SDK)
// Packages that should be kept external in ALL bundles (CLI + SDK).
// NOTE: some entries here are ALSO in OPTIONAL_RUNTIME_EXTERNALS below
// (sharp, google-auth-library, @aws-sdk/*, @azure/identity). That overlap is
// intentional: membership here means "never inline into the bundle", while
// membership in OPTIONAL_RUNTIME_EXTERNALS additionally means "not shipped in
// the default install — loaded on demand". A package can be both.
export const COMMON_EXTERNALS: string[] = [
// Native image processing
'sharp',
// Cloud provider SDKs
'@aws-sdk/client-bedrock',
'@aws-sdk/client-bedrock-runtime',
'@aws-sdk/client-sts',
'@aws-sdk/credential-provider-node',
'@aws-sdk/credential-providers',
'@smithy/core',
'@smithy/node-http-handler',
'@azure/identity',
'google-auth-library',
// @vscode/ripgrep ships a platform-specific binary alongside its
Expand All @@ -35,16 +43,67 @@ export const SDK_ONLY_EXTERNALS: string[] = [
'@modelcontextprotocol/sdk',
]

// Packages kept external but NOT listed in package.json dependencies.
// These are dynamically imported at runtime — they're optional and resolved
// from transitive deps or installed by users who need that provider/protocol.
// Optional runtime packages: dynamically imported only when a provider/feature
// needs them, and NOT listed in package.json `dependencies`, so a default
// `npm install -g @gitlawb/openclaude` stays small and warning-free.
//
// Two shapes (see RUNTIME_INDIRECTION_ONLY_EXTERNALS below):
// - Most stay external in both bundles (in COMMON_EXTERNALS) so esbuild never
// inlines them — they ARE referenced where esbuild can see them.
// - The indirection-only subset (@anthropic-ai/{bedrock,foundry}-sdk) is the
// opposite: loaded purely via the runtime importer, so esbuild never sees a
// static reference and they must stay OUT of the externals lists.
export const OPTIONAL_RUNTIME_EXTERNALS: string[] = [
// Cloud provider SDKs (dynamically imported per-provider)
'@aws-sdk/client-bedrock',
'@aws-sdk/client-bedrock-runtime',
'@aws-sdk/client-sts',
'@aws-sdk/credential-provider-node',
'@aws-sdk/credential-providers',
'@smithy/core',
'@smithy/node-http-handler',
'@azure/identity',
// Anthropic Bedrock client — loaded via the runtime importer in
// services/api/client.ts. Not bundled (it statically imports @aws-sdk) and
// not shipped; Bedrock users install it on demand (it pulls @aws-sdk itself).
'@anthropic-ai/bedrock-sdk',
// Anthropic Foundry client — also loaded only via the runtime importer in
// services/api/client.ts (CLAUDE_CODE_USE_FOUNDRY). The Function indirection
// means esbuild never sees it, so it is not bundled; Foundry users install it
// on demand. (It is NOT in COMMON_EXTERNALS for the same reason as bedrock.)
'@anthropic-ai/foundry-sdk',
// GCP/Vertex auth — loaded via runtime import in services/api/client.ts.
// Optional: only Vertex users need it. Its transitive tree (gaxios →
// node-fetch → fetch-blob → node-domexception) is what triggered the
// deprecation warning on install, so we no longer ship it by default.
'google-auth-library',
// Native image processing — loaded via dynamic import in the image tools.
// Optional: only image reads need it, and it carries a native install
// script. Kept opt-in so default installs run no install scripts.
'sharp',
]

// OPTIONAL_RUNTIME_EXTERNALS that are loaded ONLY through the runtime importer
// (the `new Function` indirection in src/utils/optionalRuntimeModule.ts), so
// esbuild never sees a static reference to them. These must NOT appear in the
// externals lists: marking @anthropic-ai/bedrock-sdk external would let esbuild
// keep (and at startup evaluate) its static `@aws-sdk/client-bedrock-runtime`
// import, which is exactly the default-install crash this design avoids. Every
// OTHER optional external IS referenced somewhere esbuild can see (e.g. sharp's
// dynamic import in imageProcessor.ts) and therefore must stay external.
export const RUNTIME_INDIRECTION_ONLY_EXTERNALS: string[] = [
'@anthropic-ai/bedrock-sdk',
'@anthropic-ai/foundry-sdk',
]

// OPTIONAL_RUNTIME_EXTERNALS that are NOT direct devDependencies because they
// are pulled transitively by another optional package's dependency tree, so
// source builds/tests still resolve them. Every OTHER optional external must be
// a direct devDependency (validated) so `bun install` source/dev builds keep
// working.
export const TRANSITIVE_OPTIONAL_EXTERNALS: string[] = [
'@aws-sdk/client-bedrock-runtime',
'@aws-sdk/credential-providers',
]

// Computed full lists
Expand All @@ -54,10 +113,13 @@ export const SDK_EXTERNALS: string[] = [...COMMON_EXTERNALS, ...SDK_ONLY_EXTERNA
// Packages intentionally bundled (not external, not flagged by validation)
// These are small utilities that are fine to inline into the output bundle.
export const INTENTIONALLY_BUNDLED: string[] = [
// Test utilities (bundled, not external)
// Anthropic provider variants (bundled, not the main SDK)
'@anthropic-ai/bedrock-sdk',
'@anthropic-ai/foundry-sdk',
// Anthropic provider variants (bundled, not the main SDK).
// NOTE: @anthropic-ai/bedrock-sdk AND @anthropic-ai/foundry-sdk are
// intentionally NOT bundled — they are loaded only via the runtime importer in
// services/api/client.ts (esbuild never sees the specifier), so they live in
// OPTIONAL_RUNTIME_EXTERNALS / RUNTIME_INDIRECTION_ONLY_EXTERNALS and Bedrock /
// Foundry users install them on demand. @anthropic-ai/sandbox-runtime IS
// statically imported (utils/sandbox/sandbox-adapter.ts), so esbuild bundles it.
'@anthropic-ai/sandbox-runtime',
// CLI / TUI utilities
'@alcalzone/ansi-tokenize',
Expand Down
Loading