Skip to content

docs: troubleshooting and additional packages version pinning#3092

Open
isshaddad wants to merge 6 commits intomainfrom
docs/connection-error-and-additional-packages
Open

docs: troubleshooting and additional packages version pinning#3092
isshaddad wants to merge 6 commits intomainfrom
docs/connection-error-and-additional-packages

Conversation

@isshaddad
Copy link
Collaborator

  • Connection error troubleshooting
  • Additional packages version pinning
  • Realtime stream error troubleshooting

@changeset-bot
Copy link

changeset-bot bot commented Feb 19, 2026

⚠️ No Changeset found

Latest commit: 49fdbc8

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Feb 19, 2026

Walkthrough

This pull request updates two documentation files. In docs/config/extensions/additionalPackages.mdx it adds guidance to pin exact package versions to avoid cached or older resolutions and updates the example to use additionalPackages({ packages: ["wrangler@1.19.0"] }). In docs/troubleshooting.mdx it adds a "Connection error" section with steps for clearing saved auth, checking VPN/firewall, and updating TLS/certificate stores (with commands), and a "Realtime stream error" section advising wrapping waitUntilComplete() in try/catch or awaiting completion before closing the stream, with a code example and link.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The pull request description is largely incomplete compared to the required template. It lacks the issue reference, checklist items, testing details, detailed changelog, and screenshots sections. Fill out the description template by adding issue reference, completing all checklist items, describing testing steps, providing detailed changelog entries, and adding any relevant screenshots.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and specifically summarizes the main changes: adding troubleshooting documentation and version pinning guidance for additional packages.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch docs/connection-error-and-additional-packages

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

devin-ai-integration[bot]

This comment was marked as resolved.

coderabbitai[bot]

This comment was marked as resolved.

devin-ai-integration[bot]

This comment was marked as resolved.

devin-ai-integration[bot]

This comment was marked as resolved.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/config/extensions/additionalPackages.mdx (1)

24-34: ⚠️ Potential issue | 🟡 Minor

wrangler@1.19.0 is a deprecated v1.x release — update the example version.

The current latest wrangler version is 4.67.0. The @cloudflare/wrangler package (v1.x) is no longer supported. Using wrangler@1.19.0 as the illustrative example risks users copying it verbatim and installing an ancient, unsupported CLI. Replace it with a current stable version (e.g., wrangler@3.0.0 or a recent 4.x) or a placeholder like wrangler@X.Y.Z to make the intent purely illustrative.

✏️ Proposed fix
-If you omit the version, the build may use a cached or older resolution. For reproducible builds, pin the exact version (e.g. `wrangler@1.19.0`).
+If you omit the version, the build may use a cached or older resolution. For reproducible builds, pin the exact version (e.g. `wrangler@3.0.0`).
-    extensions: [additionalPackages({ packages: ["wrangler@1.19.0"] })],
+    extensions: [additionalPackages({ packages: ["wrangler@3.0.0"] })],
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/config/extensions/additionalPackages.mdx` around lines 24 - 34, The
example pins an outdated deprecated wrangler version; update the example in the
build.extensions/additionalPackages usage so it no longer suggests
"wrangler@1.19.0". Locate the additionalPackages({ packages: [...] }) call
inside the defineConfig(...) build.extensions block and replace the hardcoded
deprecated version with either a current stable version (e.g., a 4.x) or a
neutral placeholder like "wrangler@X.Y.Z" so the docs do not encourage
installing a deprecated v1.x release.
🧹 Nitpick comments (2)
docs/config/extensions/additionalPackages.mdx (2)

22-22: Nit: repeated "want to" in the same sentence (flagged by LanguageTool).

✏️ Suggested rewording
-This allows you to include additional packages in the build that are not automatically included via imports. This is useful if you want to install a package that includes a CLI tool that you want to invoke in your tasks via `exec`. We will try to automatically resolve the version of the package but you can specify the version by using the `@` symbol.
+This allows you to include additional packages in the build that are not automatically included via imports. This is useful if you need to install a package that includes a CLI tool to invoke in your tasks via `exec`. We will try to automatically resolve the version of the package but you can specify the version by using the `@` symbol.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/config/extensions/additionalPackages.mdx` at line 22, The sentence in
additionalPackages.mdx repeats "want to" — edit the sentence that currently
reads about installing a package that includes a CLI tool you "want to invoke in
your tasks via `exec`" to remove the duplicate phrasing (e.g., change to
"install a package that includes a CLI tool to invoke in your tasks via `exec`"
or "install a package that includes a CLI tool you can invoke in your tasks via
`exec`"), keeping the rest of the paragraph about automatic version resolution
and optional `@version` syntax unchanged.

7-24: Consider aligning the introductory example with the new version-pinning recommendation.

The first code block (line 17) still shows wrangler without a version, while the new text on line 24 explicitly warns against that. Users who copy only the first snippet land in precisely the situation the guidance warns about. Either update line 17 to already use a pinned version (making the second block redundant) or add an explicit "without version pinning" label/callout above it to set expectations.

✏️ Suggested update for the first code block
-    extensions: [additionalPackages({ packages: ["wrangler"] })],
+    extensions: [additionalPackages({ packages: ["wrangler@3.x.x"] })],

Or, consolidate to a single example and replace lines 7–37 with a single snippet + inline prose:

-Import the `additionalPackages` build extension and use it in your `trigger.config.ts` file:
-
-```ts
-...
-    extensions: [additionalPackages({ packages: ["wrangler"] })],
-...
-```
-
-This allows you to ... you can specify the version by using the `@` symbol.
-
-If you omit the version, the build may use a cached or older resolution. For reproducible builds, pin the exact version (e.g. `wrangler@1.19.0`).
-
-```ts
-...
-    extensions: [additionalPackages({ packages: ["wrangler@1.19.0"] })],
-...
-```
+Import the `additionalPackages` build extension and use it in your `trigger.config.ts` file.
+Always pin the exact version to avoid cached or older resolutions.
+
+```ts
+...
+    extensions: [additionalPackages({ packages: ["wrangler@3.x.x"] })],
+...
+```
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/config/extensions/additionalPackages.mdx` around lines 7 - 24, Update
the example so it pins a package version (or clearly labels the unpinned
example) to match the prose: change the call to additionalPackages({ packages:
[...] }) in the shown trigger.config.ts snippet to use a pinned package like
"wrangler@1.19.0" (or replace the unpinned snippet with a single consolidated
example showing additionalPackages({ packages: ["wrangler@<version>"] }) and the
inline guidance about pinning) so the code sample matches the recommendation in
the surrounding text.
📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e0166b1 and 51c7c49.

📒 Files selected for processing (1)
  • docs/config/extensions/additionalPackages.mdx
🧰 Additional context used
🧠 Learnings (11)
📚 Learning: 2026-01-15T11:50:06.067Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to {packages,integrations}/**/* : Add a changeset when modifying any public package in `packages/*` or `integrations/*` using `pnpm run changeset:add`

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Use build extensions in trigger.config.ts (additionalFiles, additionalPackages, aptGet, prismaExtension, etc.) to customize the build

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:26:58.661Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/webapp.mdc:0-0
Timestamp: 2025-11-27T16:26:58.661Z
Learning: Applies to apps/webapp/**/*.{ts,tsx} : When importing from `trigger.dev/core` in the webapp, use subpath exports from the package.json instead of importing from the root path

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `trigger.dev/sdk/v3` for all imports in Trigger.dev tasks

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Configure build process in trigger.config.ts using `build` object with external packages, extensions, and JSX settings

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Configure Trigger.dev project in `trigger.config.ts` using `defineConfig()` with project ref and task directories

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use the `task()` function from `trigger.dev/sdk/v3` to define tasks with id and run properties

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2026-01-15T11:50:06.067Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to **/*.{ts,tsx} : Always import tasks from `trigger.dev/sdk`, never use `trigger.dev/sdk/v3` or deprecated `client.defineJob` pattern

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger/**/*.{ts,tsx,js,jsx} : Use `tasks.trigger()` with type-only imports to trigger tasks from backend code without importing the task implementation

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2026-01-15T11:50:06.067Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: CLAUDE.md:0-0
Timestamp: 2026-01-15T11:50:06.067Z
Learning: Applies to **/*.{ts,tsx,js,jsx} : Import from `trigger.dev/core` using subpaths only, never import from root

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
📚 Learning: 2025-11-27T16:27:35.304Z
Learnt from: CR
Repo: triggerdotdev/trigger.dev PR: 0
File: .cursor/rules/writing-tasks.mdc:0-0
Timestamp: 2025-11-27T16:27:35.304Z
Learning: Applies to **/trigger.config.ts : Specify task locations in trigger.config.ts using the `dirs` array, with automatic exclusion of .test and .spec files

Applied to files:

  • docs/config/extensions/additionalPackages.mdx
🪛 LanguageTool
docs/config/extensions/additionalPackages.mdx

[style] ~22-~22: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...ckage that includes a CLI tool that you want to invoke in your tasks via exec. We wil...

(REP_WANT_TO_VB)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
  • GitHub Check: Analyze (javascript-typescript)
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@docs/config/extensions/additionalPackages.mdx`:
- Around line 24-34: The example pins an outdated deprecated wrangler version;
update the example in the build.extensions/additionalPackages usage so it no
longer suggests "wrangler@1.19.0". Locate the additionalPackages({ packages:
[...] }) call inside the defineConfig(...) build.extensions block and replace
the hardcoded deprecated version with either a current stable version (e.g., a
4.x) or a neutral placeholder like "wrangler@X.Y.Z" so the docs do not encourage
installing a deprecated v1.x release.

---

Nitpick comments:
In `@docs/config/extensions/additionalPackages.mdx`:
- Line 22: The sentence in additionalPackages.mdx repeats "want to" — edit the
sentence that currently reads about installing a package that includes a CLI
tool you "want to invoke in your tasks via `exec`" to remove the duplicate
phrasing (e.g., change to "install a package that includes a CLI tool to invoke
in your tasks via `exec`" or "install a package that includes a CLI tool you can
invoke in your tasks via `exec`"), keeping the rest of the paragraph about
automatic version resolution and optional `@version` syntax unchanged.
- Around line 7-24: Update the example so it pins a package version (or clearly
labels the unpinned example) to match the prose: change the call to
additionalPackages({ packages: [...] }) in the shown trigger.config.ts snippet
to use a pinned package like "wrangler@1.19.0" (or replace the unpinned snippet
with a single consolidated example showing additionalPackages({ packages:
["wrangler@<version>"] }) and the inline guidance about pinning) so the code
sample matches the recommendation in the surrounding text.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

Comments